Local Setup

This guide walks through cloning the repository, starting infrastructure, installing dependencies, and launching all services.

1. Clone the Repository


git clone <your-repo-url> aegis
cd aegis

2. Configure Environment Variables

Copy the example environment file and add your API keys:


cp .env.example .env

Edit .env and set at minimum:


# Required for LLM calls
OPENAI_API_KEY=sk-your-key-here
 
# Everything else has working defaults for local dev

See the Environment Variables page for a complete reference.

3. Start Infrastructure

AEGIS requires three infrastructure services running in Docker:

PostgreSQL 15 with pgvector and Apache AGE extensions
Redis 7 for working memory and injection ledger
Kafka (Confluent 7.6.0) for async event publishing


docker compose up -d

Verify all containers are healthy:


docker compose ps

Expected output shows four containers running:


NAME                 IMAGE                        STATUS
aegis-postgres       aegis-postgres (custom)      Up (healthy)
aegis-operator-demo  postgres:15-alpine           Up (healthy)
aegis-redis          redis:7-alpine               Up (healthy)
aegis-kafka          confluentinc/cp-kafka:7.6.0  Up

The aegis-operator-demo container (host port 5433, database operator_demo) is the connector-framework dev fixture: a synthetic operator dataset with a aegis_ro SELECT-only role (probe passes) and a writable aegis_rw role (probe fails). See Connector Service.

The PostgreSQL container uses a custom Dockerfile that installs the pgvector and Apache AGE extensions. The init.sql script runs automatically on first startup to create the database schema, extensions, and the oilgas graph.

Verify Infrastructure Connectivity


# PostgreSQL
psql -h localhost -U aegis -d aegis -c "SELECT 1;"
# Password: aegis_local
 
# Redis
redis-cli ping
# Expected: PONG

4. Install Python Dependencies

Each Python service has its own pyproject.toml managed by Poetry. Install dependencies for each service:


# Core services
cd services/memory-service && poetry install && cd ../..
cd services/knowledge-graph-service && poetry install && cd ../..
cd services/approval-service && poetry install && cd ../..
 
# Application services
cd services/orchestration-engine && poetry install && cd ../..
cd services/ingestion-service && poetry install && cd ../..
cd services/compliance-monitor && poetry install && cd ../..
cd services/flaring-monitor && poetry install && cd ../..
 
# Auth + agent config
cd services/auth-service && poetry install && cd ../..
cd services/agent-config-service && poetry install && cd ../..
 
# Sandbox runner (jailed Python execution; unix socket, no TCP port)
cd services/sandbox-runner && poetry install && cd ../..

AEGIS is a domain-neutral compliance runtime. The 10 Python services plus the Go gateway are the platform; compliance domains ship as installable packs (packs/<name>/manifest.yaml). The bundled Texas RRC oil & gas packs are the first installed vertical, not the product itself.

Do not create a root-level pyproject.toml. Each service manages its own dependencies independently. The shared/ package is referenced as a path dependency in each service’s pyproject.toml.

5. Start All Services

The quickest way to start everything is the start-all script:


./infrastructure/scripts/start-all.sh

This script does the following in order:

Starts Docker infrastructure (docker compose up -d)
Starts core Python services (Memory, Knowledge Graph, Approval)
Starts application services (Orchestration, Ingestion, Compliance, Flaring)
Starts the Auth service and the Connector service
Builds and starts the Go API Gateway

On success, you will see:


[AEGIS] AEGIS Platform -- All services running

[AEGIS]   API Gateway:        http://localhost:8000
[AEGIS]   Orchestration:      http://localhost:8001
[AEGIS]   Memory:             http://localhost:8002
[AEGIS]   Knowledge Graph:    http://localhost:8003
[AEGIS]   Approval:           http://localhost:8004
[AEGIS]   Ingestion:          http://localhost:8005
[AEGIS]   Compliance:         http://localhost:8006
[AEGIS]   Flaring:            http://localhost:8007
[AEGIS]   Auth:               http://localhost:8009

[AEGIS]   Login:              email + password (provision via auth_service.create_user)
[AEGIS]   Stop:               ./infrastructure/scripts/start-all.sh stop

The checked-in start-all.sh boots the eight core Python services above plus the Go gateway. It does not yet launch the agent-config-service (port 8010, the runtime source of truth for skills/routers/rules/prompts/settings) or the sandbox-runner (jailed Python execution over a unix socket). Start those separately when you need them:


# agent-config-service (port 8010)
cd services/agent-config-service
poetry run uvicorn agent_config.main:app --reload --port 8010
 
# sandbox-runner (jailed Python execution over a unix socket — no TCP port)
# Privileged root component that spawns nsjail; normally only run on the box.
# Rarely needed for day-to-day local development.
cd services/sandbox-runner
poetry run python -m sandbox_runner.server

Starting Individual Services

If you want to run a single service for development (with hot reload):


cd services/orchestration-engine
poetry run uvicorn orchestration.main:app --reload --port 8001

Starting the API Gateway


cd services/api-gateway
go run ./cmd/gateway/

6. Start the Frontend

In a separate terminal:


cd frontend
npm install
npm run dev

The frontend starts on http://localhost:3000 and connects to the API gateway at localhost:8000.

7. Stop Everything


# Stop all backend services
./infrastructure/scripts/start-all.sh stop
 
# Stop infrastructure containers
docker compose down
 
# Or stop infrastructure AND delete data volumes
docker compose down -v

docker compose down -v deletes all persisted data (PostgreSQL, Redis, Kafka). Use this only when you want a completely fresh start.

Service Port Reference

Service	Port	Health Check
API Gateway	8000	`curl http://localhost:8000/health`
Orchestration Engine	8001	`curl http://localhost:8001/health`
Memory Service	8002	`curl http://localhost:8002/health`
Knowledge Graph Service	8003	`curl http://localhost:8003/health`
Approval Service	8004	`curl http://localhost:8004/health`
Ingestion Service	8005	`curl http://localhost:8005/health`
Compliance Monitor	8006	`curl http://localhost:8006/health`
Flaring Monitor	8007	`curl http://localhost:8007/health`
Auth Service	8009	`curl http://localhost:8009/health`
Agent Config Service	8010	`curl http://localhost:8010/health`
Connector Service	8011	`curl http://localhost:8011/health`
Sandbox Runner	unix socket	No TCP port (jailed Python execution)
Frontend	3000	Open in browser

All HTTP services expose a /health endpoint that returns {"status": "ok"}. The sandbox-runner is reached only over a local unix socket, not a port.