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 three containers running:


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

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
cd services/auth-service && poetry install && cd ../..

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
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]   Dev Login:          admin@aegis.local / aegis-dev-admin
[AEGIS]   Stop:               ./infrastructure/scripts/start-all.sh stop

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`
Frontend	3000	Open in browser

All services expose a /health endpoint that returns {"status": "ok"}.