1 server --api-only + 1 controller + N sandbox-hosted worker
PostgreSQL + Redis
Production, sandbox scaling, dedicated control plane
Legacy Single Workspace
1 server --workspace <path>
PostgreSQL; Redis optional
Old-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.
# Terminal 1 — Full local stack (PostgreSQL + Redis + MinIO + oah-api + oah-controller + oah-compose-scaler + oah-sandbox)
export OPENAI_API_KEY=sk-...
pnpmlocal:up
# Terminal 3 — WebUI
pnpmdev:web
# Optional — terminal TUI
pnpmdev:cli----base-urlhttp://127.0.0.1:8787tui
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:
/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.
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.
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 controllerServiceMonitor 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
Frontend proxy target (when backend is not at the default address)
http://127.0.0.1:8787
OAH_DOCKER_HOST_ALIAS
Hostname used from containers to reach host-local services
host.docker.internal
OAH_DOCKER_BUILD_BASE_IMAGE
Node builder base image for local Compose builds
node:24-alpine
OAH_DOCKER_RUNTIME_BASE_IMAGE
Runtime base image for local Compose builds
alpine:3.22
OAH_DOCKER_RUST_BASE_IMAGE
Rust builder base image for local native helper builds
rust: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: