Skip to content
AgentCTX

Docker Deployment

Docker Deployment

Section titled “Docker Deployment”

AgentCTX provides a Docker Compose setup that runs the full platform stack: TypeScript gateway, SurrealDB, NATS messaging, a mock MCP backend, and the Rust HTTP gateway.

Quick Start

Section titled “Quick Start”
Terminal window
git clone https://github.com/ryan-haver/agentctx.git
cd agentctx
docker compose up -d --build --wait

Services

Section titled “Services”
ServiceImagePortPurpose
surrealdbsurrealdb/surrealdb:v38000Database (documents, vectors, graph, live queries)
surrealdb-initalpine:3.20—Schema bootstrapping (loads 10 .surql files, then exits)
natsnats:latest4222, 8222Message bus (JetStream, pub/sub, monitoring)
mock-mcpnode:22-alpine3200Mock MCP backend (echo tool for development/testing)
agentctxCustom (Dockerfile)3100TypeScript gateway (MCP + SSE + middleware pipeline)
ctx-gatewayCustom (Rust)8420Rust HTTP gateway (LLM traffic interception)

Health Check

Section titled “Health Check”

After starting, verify all services are healthy:

Terminal window
curl http://localhost:3100/health
# {"ok": true}

Environment Variables

Section titled “Environment Variables”

Configure via .env or environment variables:

VariableDefaultDescription
SURREAL_URLws://surrealdb:8000SurrealDB connection URL
SURREAL_USERrootSurrealDB username
SURREAL_PASSrootSurrealDB password
SURREAL_NSagentctxSurrealDB namespace
SURREAL_DBmainSurrealDB database
NATS_URLnats://nats:4222NATS connection URL
NATS_MONITOR_URLhttp://nats:8222NATS monitoring endpoint
MOCK_MCP_URLhttp://mock-mcp:3200Mock MCP backend URL
NODE_ENVproductionNode.js environment
USE_RUST_SIDECARfalseRoute translations through Rust native addon
CTX_GATEWAY_PORT8420Rust gateway listen port
ANTHROPIC_API_KEY—API key for Anthropic (optional, for LLM plane)
OPENAI_API_KEY—API key for OpenAI (optional, for LLM plane)

Production Considerations

Section titled “Production Considerations”

Persistence

Section titled “Persistence”

Add volumes for data persistence:

volumes:
  surrealdb_data:
services:
  surrealdb:
    volumes:
      - surrealdb_data:/data

Scaling

Section titled “Scaling”
  • The gateway is stateless — run multiple instances behind a load balancer
  • SurrealDB supports clustering for high availability
  • NATS supports clustering and superclusters for federation

Security

Section titled “Security”
  • Change default SurrealDB credentials
  • Enable mTLS between services
  • Use 1Password integration for secrets management (OP_SERVICE_ACCOUNT_TOKEN)

See Also

Section titled “See Also”