First Run

After completing the Local Setup, follow these steps to seed data, verify services, and open the UI.

1. Verify All Services Are Running

Check the health of every service:

# Quick health check for all services
for port in 8000 8001 8002 8003 8004 8005 8006 8007 8009; do
  echo -n "Port $port: "
  curl -s http://localhost:$port/health | python3 -c "import sys,json; print(json.load(sys.stdin)['service'])" 2>/dev/null || echo "DOWN"
done

Expected output:

Port 8000: api-gateway
Port 8001: orchestration-engine
Port 8002: memory-service
Port 8003: knowledge-graph-service
Port 8004: approval-service
Port 8005: ingestion-service
Port 8006: compliance-monitor
Port 8007: flaring-monitor
Port 8009: auth-service

2. Seed the Knowledge Graph

The knowledge graph starts empty. Load the sample Permian Basin dataset (operators, fields, leases, wells, facilities, pipelines, and their relationships):

curl -X POST http://localhost:8003/seed

This creates a realistic development dataset:

• 2 operators: Permian Basin Energy LLC, Basin Midstream Partners
• 3 fields: Spraberry (Trend Area), Delaware Basin, Howard County
• 2 formations: Spraberry, Wolfcamp A
• 4 leases across the fields
• 12 wells across 4 wellpads with Form PR production data
• 4 facilities: tank battery, compressor, separator, central processing facility
• 3 pipeline routes including a cross-field connector
• 2 infrastructure projects: gathering system, processing plant
• Full edge relationships (LOCATED_IN, OPERATED_BY, OFFSET_TO, PRODUCES_TO, etc.)

3. Seed the Skill Registry

Skills define what the AI agents can do. Seed the skill registry and agent definitions:

cd services/orchestration-engine
poetry run python -m orchestration.seed_skills

This populates the skills and agents tables with:

• Rule 37 skills: spacing-calculation, offset-well-analysis, rule37-filing-assembly, good-cause-narrative
• Rule 32 skills: flaring-volume-calc, gas-analysis, rule32-filing-assembly, emissions-estimate
• Checklist-item skills: 35 specialized skills mapped to specific checklist steps
• 4 agent definitions: Rule 37 agent, Rule 32 agent, Compliance Monitor, Flaring Compliance Monitor

4. Seed Checklist Templates

Checklist templates define the step-by-step workflow for each compliance domain:

cd services/orchestration-engine
poetry run python -m orchestration.seed_checklists

This creates templates for:

• Rule 37 Spacing Exception (11 items): exception type determination, field rule lookup, offset well identification, service list, waiver tracking, Form W-1 population, good cause narrative, plat preparation, pre-filing review, filing assembly, post-filing tracking
• Rule 32 Flaring Exception (10 items): volume assessment, authorization check, gas analysis, justification narrative, Form R-32 population, technology assessment, infrastructure timeline, EPA compliance, pre-filing review, filing assembly

5. Seed Compliance Rules

cd services/orchestration-engine
poetry run python -m orchestration.seed_rules

This loads the regulatory rules that the compliance assessment engine uses, including Rule 37 spacing standards, Rule 32 flaring thresholds, and related RRC regulations.

6. Open the Frontend

Open http://localhost:3000  in your browser.

Login

Use the development login to authenticate:

Email:    admin@aegis.local
Password: aegis-dev-admin

This authenticates as the seeded bootstrap admin with admin, operator, and reviewer roles.

The login flow works as follows:

1. The login page sends the email and password to the auth service (POST /auth/token)
2. The auth service verifies the password (bcrypt) and returns a JWT token (valid for 24 hours)
3. The JWT is stored in an httpOnly cookie
4. All subsequent API calls attach the token as Authorization: Bearer {token}

7. Test Agent Execution

You can test agent execution via the conversations UI or directly via the API.

Via the API (curl)

# Get a JWT token
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@aegis.local", "password": "aegis-dev-admin"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
 
# Execute a Rule 37 query
curl -X POST http://localhost:8000/api/v1/agents/rule37-agent/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "conversation_id": "test-conv-001",
    "agent_id": "rule37-agent",
    "agent_type": "rule_37",
    "message": "I need to file a Rule 37 spacing exception for well API 42-329-12345."
  }'

Via SSE Streaming

The streaming endpoint sends node-by-node events as the LangGraph pipeline executes:

curl -N "http://localhost:8000/api/v1/agents/rule37-agent/stream/test-conv-002?message=What%20are%20the%20spacing%20requirements%20for%20Rule%2037%3F&agent_id=rule37-agent&agent_type=rule_37" \
  -H "Authorization: Bearer $TOKEN"

Troubleshooting

Service fails to start

Check the logs for the specific service. Common issues:

• PostgreSQL not ready: Wait for the health check to pass (docker compose ps)
• Port already in use: Kill the process on the conflicting port (lsof -ti:8001 | xargs kill)
• Missing dependencies: Run poetry install in the service directory

Knowledge graph seed fails

If the AGE extension is not loaded, the seed will fail. Verify AGE is available:

psql -h localhost -U aegis -d aegis -c "LOAD 'age'; SET search_path = ag_catalog; SELECT * FROM ag_graph;"
# Password: aegis_local

Agent execution returns an error

• Check that OPENAI_API_KEY is set in .env
• Check the orchestration engine logs for the specific error
• Verify the skill registry is seeded (run seed_skills if needed)