Skip to content
ModeProcessesDependenciesWhen to use
API + Worker combined1 serverPostgreSQL; Redis optionalLocal dev, PoC, single-node
API + Controller + Sandbox split1 server --api-only + 1 controller + N sandbox-hosted workerPostgreSQL + RedisProduction, sandbox scaling, dedicated control plane
Legacy Single Workspace1 server --workspace <path>PostgreSQL; Redis optionalOld-script compatibility and internal tests

tip Not sure which to pick? For enterprise/platform deployments, start with combined mode. For personal local use, prefer the OAP daemon plus oah tui. Legacy Single Workspace mode is only kept for old scripts.


Three terminals, simplest path:

Terminal window
# Terminal 1 — Full local stack (PostgreSQL + Redis + MinIO + oah-api + oah-controller + oah-compose-scaler + oah-sandbox)
export OPENAI_API_KEY=sk-...
pnpm local:up
# Terminal 3 — WebUI
pnpm dev:web
# Optional — terminal TUI
pnpm dev:cli -- --base-url http://127.0.0.1:8787 tui

pnpm local:up defaults to OAH_HOME, then ~/.openagentharness; when config is missing it seeds config/server.docker.yaml, runtimes, and the default model file from template/deploy-root. Set OAH_DEPLOY_ROOT and copy the template only when you want a separately managed team/deployment asset root.

WebUI default address: http://localhost:5174

The TUI connects to the same local API: http://127.0.0.1:8787

info Run pnpm install before the first start.

info Local API token auth is optional, and OAP daemon plus the Docker split stack use the same rule: by default no token is required; set OAH_LOCAL_API_TOKEN, or set OAH_LOCAL_API_AUTH=1 so the launcher generates/reuses ${OAH_HOME:-$HOME/.openagentharness}/run/token, then non-public API requests must send Authorization: Bearer <token>. Example:

Terminal window
export OAH_LOCAL_API_AUTH=1
pnpm local:up
TOKEN="$(cat "${OAH_HOME:-$HOME/.openagentharness}/run/token")"
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/api/v1/workspaces
pnpm dev:cli -- --base-url http://127.0.0.1:8787 --token "$TOKEN" tui

/healthz, /readyz, /metrics, and /api/v1/system/profile stay public for probes and client profile discovery.

info The local split stack keeps active workspace copies in oah-sandbox and flushes them through the object-storage backing store. oah-api is only the API ingress and router; it does not mount a persistent workspace volume.


For production or production-like environments. Requires Redis.

Terminal window
# Terminal 1 — Local infrastructure
docker compose -f docker-compose.local.yml up -d postgres redis minio
# Terminal 2 — API only (`oah-api`)
pnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/index.ts -- --config ./server.example.yaml --api-only
# Terminal 3 — Controller (`oah-controller`)
pnpm exec tsx --tsconfig ./apps/controller/tsconfig.json ./apps/controller/src/index.ts -- --config ./server.example.yaml
# Terminal 4 — Standalone worker (typically hosted inside `oah-sandbox`, can run multiple instances)
pnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/worker.ts -- --config ./server.example.yaml
# Terminal 5 — WebUI
pnpm dev:web
# Optional — terminal TUI
pnpm dev:cli -- --base-url http://127.0.0.1:8787 tui

oah-api handles HTTP ingress and owner routing. oah-controller handles the control plane. Standalone workers typically run inside oah-sandbox or E2B sandboxes, consume the Redis queue, and execute runs.

Both the WebUI and the TUI access system capabilities through oah-api; the TUI is especially convenient from a server or local shell when switching workspaces/sessions and watching streaming output.

The repository now includes a minimal Kubernetes split-deployment skeleton:

Apply them in order:

Terminal window
kubectl apply -f ./deploy/kubernetes/namespace.yaml
kubectl apply -f ./deploy/kubernetes/storage-secret.example.yaml
kubectl apply -f ./deploy/kubernetes/configmap.example.yaml
kubectl apply -f ./deploy/kubernetes/controller-rbac.yaml
kubectl apply -f ./deploy/kubernetes/api-server.yaml
kubectl apply -f ./deploy/kubernetes/worker.yaml
kubectl apply -f ./deploy/kubernetes/controller.yaml

Or install the same split-deployment skeleton via Helm:

Terminal window
helm upgrade --install oah ./deploy/charts/open-agent-harness \
--namespace open-agent-harness \
--create-namespace \
--set image.repository=ghcr.io/open-agent-harness/open-agent-harness \
--set image.tag=latest

If you do not want to assemble values from scratch, you can also start from a shipped environment example:

Terminal window
helm upgrade --install oah ./deploy/charts/open-agent-harness \
--namespace open-agent-harness \
--create-namespace \
-f ./deploy/charts/open-agent-harness/examples/staging.values.yaml

The repository now also includes a minimal GHCR publishing path for production images:

Terminal window
git push origin master

Notes:

  • .github/workflows/publish-image.yml builds the production Dockerfile on master and v* tags
  • By default it publishes to ghcr.io/<repo-owner>/open-agent-harness
  • If you need a different package path, set the GitHub repository variable OAH_IMAGE_NAME
  • If you want to match the repository’s shipped example manifests/chart defaults, set OAH_IMAGE_NAME=open-agent-harness/open-agent-harness

This baseline already includes:

  • Separate Deployments for oah-api, oah-sandbox, and oah-controller
  • oah-api does not need a workspace volume; oah-sandbox owns writable active workspace copies, ideally paired with object-storage backing for idle / drain flushes
  • A dedicated ClusterIP Service for controller exposing /healthz, /readyz, /snapshot, and /metrics
  • Kubernetes Lease based leader election for controller
  • Replica reconciliation through the Kubernetes workload /scale subresource for oah-sandbox, with optional target discovery via label_selector; the target supports Deployment and StatefulSet
  • The shipped server.yaml examples set sandbox.provider=self_hosted and route sandbox requests through the oah-sandbox-internal headless service
  • The default sandbox fleet keeps warm_empty_count: 1 empty sandbox ready; ownerless workspaces reuse existing sandboxes while CPU, memory, and disk are below threshold, then fall back to the warm empty sandbox when any resource crosses the threshold
  • controller-rbac.yaml now includes the leases, deployments, deployments/scale, statefulsets, and statefulsets/scale permissions needed for leader election, label-selector discovery, and replica reconciliation
  • Automatic scale-down is now enabled when safety conditions are met; the real scale-down guardrail comes from controller health probes against standalone worker /healthz
  • Standalone workers now enter a drain phase on shutdown so readiness drops before the current run is allowed to finish
  • Drain now also flushes and evicts idle workspace copies and blocks new object-store materialization from starting
  • All three Deployments now declare explicit rollout strategy settings; oah-api / oah-sandbox use maxUnavailable: 0, and oah-sandbox keeps a longer terminationGracePeriodSeconds window so drain has time to converge
  • The controller Service ships with basic prometheus.io/* scrape annotations; fuller ServiceMonitor / Prometheus Operator integration is still better handled in production overlays or Helm charts
  • The repository also ships controller-servicemonitor.example.yaml as a Prometheus Operator example; it is intentionally not included in the default kustomization.yaml
  • The repository now also ships a directly usable Prometheus Operator kustomization: deploy/kustomization.yaml It layers deploy/controller-servicemonitor.yaml on top of the base deploy/kubernetes skeleton, so Prometheus Operator users can enable the controller ServiceMonitor with kubectl apply -k ./deploy
  • The repository now also ships a minimal Helm chart so the split deployment, RBAC, ConfigMap, and optional ServiceMonitor can be managed together by Helm
  • The Helm chart now also supports existing ConfigMaps, PVC-backed workspace volumes for oah-sandbox, and per-component resources / securityContext / envFrom / scheduling settings
  • Production deployments should enable object-storage backing store and explicitly size worker.workspaceVolume, ephemeral-storage, worker.diskReadiness.threshold, and worker.workspacePolicy.*; see docs/production-readiness.md
  • The Helm chart now also supports PodDisruptionBudget, topologySpreadConstraints, priorityClassName, and direct oah-api Ingress generation
  • The chart directory now also ships dev / staging / prod values examples, so teams can start from environment-specific presets instead of building everything from scratch
  • The repository now also ships a production Dockerfile and minimal GHCR publishing workflow, so the K8S manifests/chart are no longer assuming some external image pipeline already exists
  • The GHCR workflow now also emits sbom/provenance and performs Cosign keyless signing

This mode is kept as a compatibility path for old scripts and internal tests. For personal local use, prefer the OAP daemon and oah tui.

Terminal window
pnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/index.ts -- \
--workspace /absolute/path/to/workspace \
--model-dir /absolute/path/to/models \
--default-model openai-default

Optional flags:

FlagDescription
--tool-dir <path>Platform tool directory
--skill-dir <path>Platform skill directory
--host <addr>Listen address, defaults to 127.0.0.1
--port <num>Listen port, defaults to 8787

warning In single workspace mode, workspace management endpoints (POST /workspaces, DELETE /workspaces/:id, etc.) are disabled.


After starting the server, verify status with these endpoints:

EndpointPurposeExpected response
GET /healthzLiveness check{ "status": "ok" }
GET /readyzReadiness check (includes dependencies){ "status": "ready" }, returns 503 if not ready
Terminal window
curl http://127.0.0.1:8787/healthz
curl http://127.0.0.1:8787/readyz

Additional checks:

  • Server logs print the active runtime mode (API + embedded worker / API only / standalone worker)
  • After sending a message, the run progresses past queued
  • In split mode, worker logs show queue consumption

VariableDescriptionExample
DATABASE_URLPostgreSQL connection stringpostgres://oah:oah@127.0.0.1:5432/open_agent_harness
REDIS_URLRedis connection stringredis://127.0.0.1:6379
OAH_WEB_PROXY_TARGETFrontend proxy target (when backend is not at the default address)http://127.0.0.1:8787
OAH_DOCKER_HOST_ALIASHostname used from containers to reach host-local serviceshost.docker.internal
OAH_DOCKER_BUILD_BASE_IMAGENode builder base image for local Compose buildsnode:24-alpine
OAH_DOCKER_RUNTIME_BASE_IMAGERuntime base image for local Compose buildsalpine:3.22
OAH_DOCKER_RUST_BASE_IMAGERust builder base image for local native helper buildsrust:1.95-alpine

Reference environment variables in server.yaml with ${env.DATABASE_URL} syntax.

If OAH itself runs inside Docker while an HTTP MCP server runs on the host machine:

  • MCP configs may still use http://127.0.0.1:PORT/... or http://localhost:PORT/...
  • OAH rewrites those loopback URLs to a host-reachable address inside the container
  • the default alias is host.docker.internal
  • override it with OAH_DOCKER_HOST_ALIAS when needed

The local docker-compose.local.yml already injects host.docker.internal:host-gateway for oah-api, oah-controller, oah-compose-scaler, and oah-sandbox, so the default alias also works on Linux in the local stack.

pnpm local:up prefetches the preferred Alpine-family base images and passes Node builder, runtime, and Rust native builder build args into Compose. If you override these manually, set OAH_DOCKER_BUILD_BASE_IMAGE, OAH_DOCKER_RUNTIME_BASE_IMAGE, and OAH_DOCKER_RUST_BASE_IMAGE together; overriding only the first two does not affect the native Rust build stage.

When using containers started by docker-compose.local.yml, the default connection strings are:

storage:
postgres_url: postgres://oah:oah@127.0.0.1:5432/open_agent_harness
redis_url: redis://127.0.0.1:6379