Skip to main content

Getting Started with CitadelMesh

Welcome to CitadelMesh! This guide will get you up and running with the autonomous multi-agent building intelligence platform in under 15 minutes.

Prerequisites​

Before you begin, ensure you have the following installed:

Required Software​

ToolVersionPurpose
.NET SDK8.0+Aspire AppHost and microservices
Docker DesktopLatestContainer runtime for infrastructure
Python3.12+Agent runtime
Node.js20+MCP adapters
GitLatestSource control
  • VS Code with C# Dev Kit extension
  • Visual Studio 2022 (Windows/Mac)
  • Docker Compose plugin

Verify Installation​

# Check versions
dotnet --version          # Should be 8.0+
docker --version          # Should be 20.10+
python --version          # Should be 3.12+
node --version           # Should be 20+

Quick Start​

1. Clone the Repository​

git clone https://github.com/your-org/CitadelMesh.git
cd CitadelMesh

2. Understand the Directory Structure​

CitadelMesh/
├── src/
│   ├── CitadelMesh.AppHost/      # 🚀 START HERE - Aspire orchestration
│   ├── agents/                   # Python LangGraph agents
│   │   ├── runtime/              # Base agent framework
│   │   └── security/             # Security agent example
│   ├── microservices/            # .NET services
│   │   ├── CitadelMesh.Safety/   # OPA policy enforcement
│   │   └── CitadelMesh.Orchestrator/  # Event coordination
│   └── proto_gen/                # Generated Protobuf code
├── mcp-servers/                  # Vendor adapters
│   ├── ecostruxure-ebo/         # HVAC control
│   └── citadel-schemas/         # Shared types
├── policies/                     # OPA/Rego safety rules
│   ├── security.rego            # Security policies
│   ├── energy.rego              # Energy optimization
│   └── hvac/                    # HVAC policies
├── config/                      # Deployment configs
│   └── spiffe/                  # Zero-trust identity
├── docs/                        # Architecture documentation
└── tests/                       # Integration tests

3. First Run - Aspire Dashboard​

The Aspire dashboard is your main development interface. It orchestrates all services and provides observability.

# Navigate to AppHost
cd src/CitadelMesh.AppHost

# Run the dashboard
dotnet run

Expected Output:

info: Aspire.Hosting.DistributedApplication[0]
      Aspire version: 8.0.0

info: Aspire.Hosting.DistributedApplication[0]
      Distributed application started. Press Ctrl+C to shut down.

info: Aspire.Hosting.DistributedApplication[0]
      Dashboard URL: https://localhost:5000

4. Open the Dashboard​

Navigate to: https://localhost:5000

You'll see:

  • Resources tab: All running services

    • Redis (caching)
    • PostgreSQL (persistence)
    • NATS (event bus)
    • OPA (policy engine)
    • SPIRE (zero-trust identity)
    • Jaeger (tracing)

  • Console Logs tab: Real-time service logs

  • Structured Logs tab: Filtered, searchable logs

  • Traces tab: Distributed tracing

  • Metrics tab: Performance metrics

5. Verify Services​

Check that all services are healthy:

# In a new terminal

# Check OPA is running
curl http://localhost:8181/health
# Expected: {"status": "ok"}

# Check SPIRE server
curl http://localhost:8081/healthz
# Expected: HTTP 200

# Check Redis
docker exec citadel-redis redis-cli ping
# Expected: PONG

6. Run Your First Agent​

Let's run the security agent example:

# Navigate to agents directory
cd /path/to/CitadelMesh/src/agents

# Install Python dependencies
pip install -r requirements.txt

# Run the security agent demo
python security/demo_security_agent.py

Expected Output:

🛡️ CitadelMesh Security Agent - Multi-Vendor Orchestration
============================================================
INFO: MCP clients initialized
INFO: Security agent initialized
INFO: Security events collected, new_events=2, total_events=2
INFO: Threat analysis complete, threat_level=medium

✅ Scenario Results:
   Threat Level: medium
   Events Processed: 2
   Response Actions: ['track_person', 'monitor']

🏆 Security Agent testing complete!

What Just Happened?​

  1. Aspire AppHost started all infrastructure services using Docker containers
  2. SPIRE established zero-trust identities for all workloads
  3. OPA loaded safety policies from /policies directory
  4. NATS started the CloudEvents message bus
  5. The Security Agent connected to simulated vendor systems and processed a security scenario

Next Steps​

Now that you have CitadelMesh running:

Learn the Basics​

Build Something​

Explore the Architecture​

Troubleshooting​

Dashboard won't start​

Error: Failed to bind to address

Solution: Port 5000 is in use. Kill the process:

# macOS/Linux
lsof -ti:5000 | xargs kill -9

# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

Services not starting​

Error: Docker daemon not running

Solution: Start Docker Desktop and wait for it to fully initialize.

Python dependencies failing​

Error: ModuleNotFoundError: No module named 'langgraph'

Solution: Ensure you're using Python 3.12+:

python --version  # Should be 3.12+
pip install --upgrade pip
pip install -r src/agents/requirements.txt

OPA policies not loading​

Error: Failed to load policy bundle

Solution: Check policy syntax:

# Validate Rego policies
docker run --rm -v $(pwd)/policies:/policies \
  openpolicyagent/opa test /policies

Common First-Time Questions​

Q: Do I need all the services running to develop?

A: No! You can start just what you need. See selective service startup.

Q: How do I debug an agent?

A: Use VS Code debugger with the Python agent. See Agent Testing.

Q: Can I use this without Kubernetes?

A: Yes! Use Docker Compose for simpler deployments. See Docker Compose Setup.

Q: How do I add a new vendor system?

A: Create an MCP adapter. See Creating Adapters for a step-by-step guide.

Support​

You're all set! Continue to Local Environment Setup to configure your development environment.