Docker Compose

Developer Reference

This page covers internal implementation details. It is not included in the User Guide.

Run the full Escher backend stack locally for development or single-machine deployment.

---

Port layout

Service	Port	Notes
SurrealDB	4000	Asset Store persistence layer
Asset Store	8000	Context Engine calls this
Context Engine	8001	ADK and Platform Framework call this
Gateway	8080	Desktop app connects here
Analysis Agent	8081	Gateway routes to this
Playbook Agent	8082	Gateway routes to this

---

Step 1 — SurrealDB

Option A — Use shared remote SurrealDB (recommended for development)

Configure v4-asset-store-go/.env with the shared remote connection string. Skip local SurrealDB setup.

Option B — Run SurrealDB locally

surreal start --bind 0.0.0.0:4000 --user root --pass root memory

Update v4-asset-store-go/.env:

SURREAL_URL=ws://localhost:4000/rpc
SURREAL_USER=root
SURREAL_PASS=root
SURREAL_NS=escher
SURREAL_DB=main

---

Step 2 — Asset Store

cd v4-asset-store-go
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# First time only — run schema migration
asset-store-migrate

# Start
uvicorn asset_store.app:app --host 0.0.0.0 --port 8000 --reload

Verify:

curl http://localhost:8000/health
# {"status":"ok"}

---

Step 3 — Context Engine

cd v4-context-engine
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Edit .env: set ASSET_STORE_URL=http://localhost:8000

uvicorn context_engine.main:app --host 0.0.0.0 --port 8001 --reload

Verify:

curl http://localhost:8001/health
# {"status":"ok"}

---

Step 4 — Register agents

cd v4-adk
source venv/bin/activate

# Register all built-in agents
adk register ./compliance-audit-agent/ --ce-url http://localhost:8001
adk register ./cost-query-agent/ --ce-url http://localhost:8001
adk register ./iam-security-agent/ --ce-url http://localhost:8001

---

Step 5 — Gateway and agents

The docker-compose.yml for the server-side services lives in the v3-escher-deployment repo root. It defines the Gateway, Analysis Agent, Playbook Agent, and Integrations Agent containers with environment variables pointing at the locally running Context Engine and Asset Store.

# From v3-escher-deployment — start all server services
docker-compose up gateway analysis-agent playbook-agent integrations-agent

The compose file reads from an .env file in the same directory:

# v3-escher-deployment/.env
CONTEXT_ENGINE_URL=http://host.docker.internal:8001
ASSET_STORE_URL=http://host.docker.internal:8000
ANTHROPIC_API_KEY=sk-ant-...
GATEWAY_PORT=8080
ANALYSIS_AGENT_PORT=8081
PLAYBOOK_AGENT_PORT=8082

TIP

host.docker.internal resolves to the host machine's IP from inside Docker containers on macOS and Windows. On Linux, use 172.17.0.1 (default Docker bridge) or add --add-host=host.docker.internal:host-gateway to each service in the compose file.

---

Health check all services

for port in 8000 8001 8080 8081; do
  echo "Port $port: $(curl -sf http://localhost:$port/health || echo 'FAILED')"
done

---

Next steps

• ECS — Production deployment on AWS
• ADK Reference — Register your own agents