Docker Deployment

This is a self-hosting guide. The hosted product at https://www.orcapods.ai needs none of this: sign in and go.

Compose Stack Overview

The root docker-compose.yml is profile-driven:

Profile	Purpose
`real`	SeaweedFS plus the mode-specific agent-worker sidecars on host ports `7071`, `7072`, `7073`, `7074`
`poly`	Capability-matched runners plus mode-specific and `MODE=all` agent-worker sidecars
`stack`	Full two-conductor, two-runner backend behind nginx on `localhost:8080`
`all`	SeaweedFS plus the mode-specific agent-worker sidecars, used for ad-hoc local testing

make dev is an alias for make stack.

Full Backend Stack

make dev

This starts:

Service	Role
`<storage-service>`	Local S3-compatible artifact store
`<storage-service>-init`	Creates the `agent-artifacts` bucket
`<pi-sidecar>`	Pi agent-worker sidecar, `MODE=pi`, port `7074`
`<claude-sidecar>`	Claude sidecar, `MODE=claude`, port `7071`
`<codex-sidecar>`	Codex sidecar, `MODE=codex`, port `7072`
`<vercel-sidecar>`	Vercel agent-worker sidecar, `MODE=vercel`, port `7073`
`vfs`	VFS service, host port `18080`
`e2b-bridge`	E2B sandbox bridge, host port `17090`
`<runner-1>`, `<runner-2>`	Stateful runners, each advertising `pi,claude,codex,vercel`
`<conductor-1>`, `<conductor-2>`	Stateless control plane replicas
`nginx`	Load balances conductor traffic on `localhost:8080`

The dashboard is not containerized by the stack. Run it separately:

make frontend
# http://localhost:5173

Building Images

docker build -t orca/conductor -f docker/Dockerfile.conductor .
docker build -t orca/runner -f docker/Dockerfile.runner .
docker build -t orca/mcp-bridge -f docker/Dockerfile.mcp-bridge .
docker build -t orca/agent-worker -f agent-worker/Dockerfile ./agent-worker

For normal local development, prefer:

make dev

Compose builds the required images for the selected profile.

MCP Bridge

The standalone mcp-bridge service is the deployment boundary for Composio credentials and traffic. It listens on port 8091 by default, serves GET /healthz, exposes a bearer-gated GET /metrics, and accepts bridge operations only on its signed internal API. Configure it with:

Variable	Requirement
`MCP_BRIDGE_INTERNAL_SIGNING_KEY_CURRENT`	Required base64-encoded HMAC key that decodes to at least 32 bytes
`MCP_BRIDGE_INTERNAL_SIGNING_KEY_PREVIOUS`	Optional previous signing key during rotation
`COMPOSIO_API_KEY`	Composio platform key owned by this service
`COMPOSIO_BASE_URL`	Optional Composio backend override
`COMPOSIO_SUBJECT_PEPPER`	Required base64 pepper for deriving opaque tenant subjects
`METRICS_AUTH_TOKEN`	Bearer token for `/metrics`; when unset, metrics returns `401`
`REDIS_URL`	Required shared nonce store; must be a valid `redis://` or `rediss://` URL
`PORT` or `MCP_BRIDGE_PORT`	Listen port; defaults to `8091`

The service fails startup when the current signing key is missing, malformed, or too short, when COMPOSIO_SUBJECT_PEPPER is unset, or when REDIS_URL is unset or not a valid redis:///rediss:// URL. There is no in-memory nonce-store fallback. Use docker/railway-mcp-bridge.toml as the Railway deployment reference.

Shared Storage

All compose profiles inherit the same S3-compatible storage environment:

AWS_ENDPOINT_URL_S3: "http://<storage-service>:8333"
AWS_REGION: "us-east-1"
AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID}"
AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY}"
S3_BUCKET: "agent-artifacts"
S3_FORCE_PATH_STYLE: "true"

Host access uses http://localhost:8333. The Makefile has storage helpers:

make storage-up
make storage-smoke
make storage-ls
make storage-smoke-tools

Stack Configuration

The stack profile uses two runners and two conductors:

<runner-1>:
  profiles: ["stack"]
  environment:
    RUNNER_PORT: "7070"
    RUNNER_BASE_URL: "http://<runner-1>:7070"
    RUNNER_CAPABILITIES: "pi,claude,codex,vercel"
    PI_SIDECAR_URL: "http://<pi-sidecar>:7074"
    CLAUDE_SIDECAR_URL: "http://<claude-sidecar>:7071"
    CODEX_SIDECAR_URL: "http://<codex-sidecar>:7072"
    VERCEL_SIDECAR_URL: "http://<vercel-sidecar>:7073"

<conductor-1>:
  profiles: ["stack"]
  environment:
    CONDUCTOR_PORT: "8080"
    RUNNER_URLS: "http://<runner-1>:7070,http://<runner-2>:7070"

nginx:
  profiles: ["stack"]
  ports:
    - "8080:80"

Both conductors are stateless and can route any session because session IDs include the owning runner hash.

Specialized Poly Topology

Use the poly profile when you want capability-aware routing across runner shapes:

Runner	Capabilities	Agent-worker
`runner-pi`	`pi`	`<pi-sidecar>:7074`
`runner-claude`	`claude`	`<claude-sidecar>:7071`
`runner-codex`	`codex`	`<codex-sidecar>:7072`
`runner-vercel`	`vercel`	`<vercel-sidecar>:7073`
`runner-poly`	`pi,claude,codex,vercel`	`<all-runtimes-sidecar>:7070`

docker compose --profile poly up --build

This is useful for testing that the conductor pod routes each profile runtime only to capable runners.

Environment File

Create .env at the repo root for provider keys:

ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
OPENAI_API_KEY=${OPENAI_API_KEY}
GOOGLE_GENERATIVE_AI_API_KEY=${GOOGLE_GENERATIVE_AI_API_KEY}
TAVILY_API_KEY=${TAVILY_API_KEY}

The stack profile also requires these to be set in .env:

CLERK_JWKS_URL=${CLERK_JWKS_URL}
CHAT_GATEWAY_SIGNING_KEY_CURRENT=${CHAT_GATEWAY_SIGNING_KEY_CURRENT}
VFS_INTERNAL_SIGNING_KEY_CURRENT=${VFS_INTERNAL_SIGNING_KEY_CURRENT}
VFS_AUTH_TOKEN=${VFS_AUTH_TOKEN}

CLERK_JWKS_URL is enforced at compose parse time: the conductor services refuse to start without it. CHAT_GATEWAY_SIGNING_KEY_CURRENT and VFS_INTERNAL_SIGNING_KEY_CURRENT are read by the conductor and vfs service for their internal signing planes, and VFS_AUTH_TOKEN gates bearer auth on the vfs service. Docker Compose loads .env automatically.

Health Checks

# Conductor through nginx
curl http://localhost:8080/healthz

# Runners exposed by the stack profile
curl http://localhost:17070/healthz
curl http://localhost:17071/healthz

# Agent-worker services exposed by the real/stack profiles
curl http://localhost:7071/health
curl http://localhost:7072/health
curl http://localhost:7073/health
curl http://localhost:7074/health

# Storage
curl http://localhost:8333/

/healthz returns text ok. The SeaweedFS S3 root may return 403 without credentials; that still means the service is reachable.

Logs

docker compose logs -f
docker compose logs -f <conductor-1>
docker compose logs --tail=100 <runner-1>

Go services use Zap structured logs. Agent-worker processes write JSON-ish logs from Node.

nginx Configuration

The repository nginx config proxies all traffic to the conductor pod and disables stream buffering:

upstream conductors {
    least_conn;
    server <conductor-1>:8080 max_fails=2 fail_timeout=5s;
    server <conductor-2>:8080 max_fails=2 fail_timeout=5s;
}

server {
    listen 80;
    location / {
        proxy_pass http://conductors;
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

This keeps /api/runs/{id}/stream, /api/workflows/runs/{id}/stream, and runner NDJSON streams usable through the proxy.

Scaling Notes

To add a runner:

Give it a stable, unique RUNNER_BASE_URL.
Set accurate RUNNER_CAPABILITIES.
Add that same URL to every conductor’s RUNNER_URLS.

Existing sessions stay on their original runner. New sessions are round-robined across runners that advertise the profile runtime.

Get Started

Core Concepts

Guides

Runbooks

Docker Deployment

Compose Stack Overview

Full Backend Stack

Building Images

MCP Bridge

Shared Storage

Stack Configuration

Specialized Poly Topology

Environment File

Health Checks

Logs

nginx Configuration

Scaling Notes

​Compose Stack Overview

​Full Backend Stack

​Building Images

​MCP Bridge

​Shared Storage

​Stack Configuration

​Specialized Poly Topology

​Environment File

​Health Checks

​Logs

​nginx Configuration

​Scaling Notes

Compose Stack Overview

Full Backend Stack

Building Images

MCP Bridge

Shared Storage

Stack Configuration

Specialized Poly Topology

Environment File

Health Checks

Logs

nginx Configuration

Scaling Notes