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 HTTP services
for port in 8000 8001 8002 8003 8004 8005 8006 8007 8009 8010 8011; 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
Port 8010: agent-config-service
Port 8011: connector-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 Skills & Agents (agent-config-service)

Skills, routers, rules, personas, and agent definitions are owned by the agent-config-service and seeded through it — not the orchestration engine. (The legacy seed_skills.py tier registry was retired in R41 B0.) See the agent-config-service setup docs for its seeders.

4. Seed Checklist Templates

Checklist templates define the step-by-step workflow for each compliance domain. Template content is sourced from the installed pack manifests (packs/<name>/manifest.yaml), so the set you get depends on which packs are installed — out of the box these are the bundled Texas RRC packs:

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

This creates templates for the RRC vertical, including:

• 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
• plus the other installed packs (Form PR, flaring monitor, EPA OOOOb)

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. In the UI, new conversations use the seeded general and creator agents; the RRC Rule 37 / Rule 32 skills are reached through router selection (the RRC packs are the bundled first vertical, not separate pickers). The /execute API below still accepts an explicit agent_type for scripted/replay use.

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 an LLM provider key is set in .env (ANTHROPIC_API_KEY for the default anthropic/claude-sonnet-5)
• Check the orchestration engine logs for the specific error
• Verify skills are seeded in the agent-config-service