Prerequisites

Minimum versions required for local development.

Requirement	Minimum version
Docker + Docker Compose	24.x
Node.js	20 LTS
Python	3.12
PostgreSQL	16
Redis	7

Local Development (Docker Compose)

Start the full stack locally in five steps.

bash

1. Clone and configure

git clone https://github.com/your-org/aegissovereign.git
cd aegissovereign
cp .env.example .env   # edit as needed

bash

2–4. Start services, migrate, and run the API

1docker compose up -d postgres redis
2
3cd backend
4pip install -e ".[dev]"
5alembic upgrade head
6
7uvicorn app.main:app --reload --port 8000

bash

5. Start the frontend

npm install
npm run dev   # http://localhost:5173

Dev Login Accounts

With VITE_DEV_AUTH=true (default in .env.example), the login page shows a Dev Login form. Three built-in accounts cover all roles.

Email	Role
`ops@dev.local`	`ops` — deploy models, approve HITL, manage clusters
`dev@dev.local`	`dev` — create models, run agents, view audit log
`legal@dev.local`	`legal` — approve GitOps manifests, view compliance reports

Production Deployment (Helm)

The Helm pre-upgrade hook automatically runs alembic upgrade head before any application pod rolls.

bash

Helm install

1helm upgrade --install aegissovereign helm/sovereign-gateway \
2  --namespace aegissovereign \
3  --create-namespace \
4  --values helm/sovereign-gateway/values.yaml \
5  --values helm/sovereign-gateway/values-production.yaml \
6  --set global.platformHost=sovereign.yourcompany.com \
7  --set ingress.tls.certManager.acmeEmail=ops@yourcompany.com \
8  --wait --timeout 10m

Starting Celery Workers (AI Agents)

The four AI Governance Agents run as Celery tasks. Without workers running, model registration will not trigger the CompliancePipeline Agent, incidents will not fire notifications, and remediation suggestions will not be generated. Start both a worker and the beat scheduler.

bash

Local development — two terminals

1# Terminal 1 — task worker
2cd backend
3celery -A app.celery_app worker --loglevel=info -Q aegissovereign
4
5# Terminal 2 — beat scheduler (weekly governance report + drift scans)
6celery -A app.celery_app beat --loglevel=info

bash

Docker Compose (add to compose.yml)

1celery-worker:
2  build: ./backend
3  command: celery -A app.celery_app worker --loglevel=info -Q aegissovereign
4  env_file: .env
5  depends_on: [postgres, redis]
6
7celery-beat:
8  build: ./backend
9  command: celery -A app.celery_app beat --loglevel=info
10  env_file: .env
11  depends_on: [postgres, redis]

MCP Server Quick Setup

The MCP Server connects Claude Code or Claude Desktop to your Aegis Sovereign workspace. It runs as a local stdio process — no inbound ports required.

bash

Install and configure

1# Create a .env file for the MCP server
2cat > ~/.aegissovereign-mcp.env <<EOF
3AEGISSOVEREIGN_BASE_URL=https://sovereign.yourcompany.com
4AEGISSOVEREIGN_API_KEY=pat_your_ops_token_here
5AEGISSOVEREIGN_WORKSPACE_ID=ws_prod_abc123
6EOF

json

Claude Desktop — ~/.config/claude/claude_desktop_config.json

1{
2  "mcpServers": {
3    "aegissovereign": {
4      "command": "npx",
5      "args": ["-y", "@aegissovereign/mcp-server"],
6      "env": {
7        "AEGISSOVEREIGN_BASE_URL": "https://sovereign.yourcompany.com",
8        "AEGISSOVEREIGN_API_KEY": "pat_your_ops_token_here",
9        "AEGISSOVEREIGN_WORKSPACE_ID": "ws_prod_abc123"
10      }
11    }
12  }
13}