Skip to content

Server Configuration

Configuration format: YAML. Default filename: server.yaml.


server:
host: 0.0.0.0 # Listen address
port: 8787 # Listen port
storage: {}
# postgres_url: ${env.DATABASE_URL} # Optional; falls back to local SQLite shadow storage when omitted
# redis_url: ${env.REDIS_URL} # Optional; runs execute inline in the API process when omitted
sandbox:
provider: embedded # embedded | self_hosted | e2b
# fleet:
# min_count: 1
# max_count: 32
# warm_empty_count: 1
# resource_cpu_pressure_threshold: 0.8
# resource_memory_pressure_threshold: 0.8
# max_workspaces_per_sandbox: 32
# ownerless_pool: shared # shared | dedicated
# self_hosted:
# base_url: http://oah-sandbox:8787/internal/v1
# e2b:
# base_url: https://api.e2b.dev
# api_key: ${env.E2B_API_KEY}
paths:
workspace_dir: /srv/openharness/workspaces # Project workspace root
runtime_state_dir: /srv/openharness/.openharness # Runtime-private state root
runtime_dir: /srv/openharness/runtimes # Workspace runtime directory
model_dir: /srv/openharness/models # Platform model directory
tool_dir: /srv/openharness/tools # Platform tool directory
skill_dir: /srv/openharness/skills # Platform skill directory
workers:
embedded:
min_count: 2 # Minimum worker count in API + embedded worker mode
max_count: 4 # Upper bound for light local autoscaling
scale_interval_ms: 1000 # Scaling check interval
idle_ttl_ms: 30000 # How long surplus workers may stay idle before cleanup
scale_up_window: 2 # Consecutive high-pressure samples required before scale-up
scale_down_window: 2 # Consecutive low-pressure samples required before scale-down
cooldown_ms: 1000 # Minimum cooldown between scaling actions
reserved_capacity_for_subagent: 1 # Spare capacity reserved for subagent backlog
llm:
default_model: openai-default # Default model name (must exist in model_dir)

info Use ${env.VAR_NAME} syntax to reference environment variables.

tip Neither storage.postgres_url nor storage.redis_url is mandatory. Omitting PostgreSQL falls back to local SQLite shadow persistence; omitting Redis keeps run execution inline in the current API process.


FieldTypeDefaultDescription
hoststring127.0.0.1Listen address
portnumber8787Listen port
FieldTypeRequiredDescription
postgres_urlstringNoPostgreSQL connection string. Workspaces without serviceName use this database directly; once serviceName is set, the default database keeps only the workspace/session/run routing index while runtime truth is routed to a sibling derived database name (for example OAH-acme). When omitted, OAH falls back to local SQLite shadow persistence.
redis_urlstringNoRedis connection string. Used for queues, locks, rate limiting, and SSE event fanout.

tip Without PostgreSQL, workspace/session/run persistence falls back to local SQLite shadow state. That is fine for single-node development, but it is not a shared source of truth for multi-instance deployments.

tip Without Redis, runs execute in-process on the API server (suitable for local dev). With Redis, multiple worker instances can consume the queue.

FieldTypeDescription
providerstringCurrently only s3-compatible object storage is supported
bucketstringTarget bucket
regionstringObject storage region
endpointstringOptional custom S3/OSS/MinIO endpoint
access_keystringOptional access credential
secret_keystringOptional access credential
session_tokenstringOptional temporary credential
force_path_stylebooleanWhether to force path-style URLs
workspace_backing_store.enabledbooleanEnables managed workspace object-storage backing. Active workspace writes still flush only on idle / drain / delete
workspace_backing_store.key_prefixstringObject-storage key prefix used for workspace backing
mirrors.pathsstring[]Readonly prefixes mirrored locally. Supports runtime / model / tool / skill
mirrors.sync_on_bootbooleanWhether mirrored prefixes should be pulled from object storage on startup
mirrors.sync_on_changebooleanWhether mirrored readonly prefixes are polled for changes. This does not live-sync active workspace writes
mirrors.poll_interval_msnumberMirror poll interval
mirrors.key_prefixes.*objectObject-storage key prefix mapping for each readonly mirrored path
managed_paths / key_prefixes.* / sync_on_*legacyBackward-compatible legacy fields; prefer workspace_backing_store and mirrors for new configs. Loading them emits a deprecation warning

tip runtime / model / tool / skill in mirrors.paths are still mirrored through ObjectStorageMirrorController on boot and on change polling.

tip workspace_backing_store only controls managed workspace externalRef / backing-store semantics. Active workspace writes do not flush on every change; they flush through the workspace materialization idle / drain lifecycle.

Production workers should also set:

Env varDescription
OAH_WORKER_DISK_METRICS_PATHMounted path used for worker lease disk-usage reporting
OAH_WORKER_DISK_READINESS_THRESHOLDWorker /readyz returns worker_disk_pressure above this local disk usage ratio
OAH_OBJECT_STORAGE_SYNC_MAX_OBJECTSMaximum object count allowed for one workspace/object-store sync
OAH_OBJECT_STORAGE_SYNC_MAX_BYTESMaximum total bytes allowed for one workspace/object-store sync
OAH_OBJECT_STORAGE_SYNC_MAX_FILE_BYTESMaximum single-file size allowed for object-store sync
FieldTypeDescription
providerstringSandbox provider. Supports embedded, self_hosted, and e2b. Defaults to embedded. embedded means the worker is hosted inside oah-api; self_hosted / e2b mean a standalone worker runs inside a real sandbox.
fleet.min_countnumberMinimum sandbox count the controller should maintain for self-hosted / e2b providers. Defaults to 1 for remote providers and 0 for embedded.
fleet.max_countnumberMaximum sandbox count the controller may target. Defaults to 64.
fleet.warm_empty_countnumberExtra empty sandboxes to keep warm so new workspaces can bind quickly at any time. Defaults to 1 for remote providers and 0 for embedded.
fleet.resource_cpu_pressure_thresholdnumberSandbox resource pressure threshold. Ownerless workspaces prefer an empty sandbox when CPU load ratio exceeds this value. Defaults to 0.8.
fleet.resource_memory_pressure_thresholdnumberSandbox memory pressure threshold. Ownerless workspaces prefer an empty sandbox when memory used ratio exceeds this value. Defaults to 0.8.
fleet.resource_disk_pressure_thresholdnumberSandbox disk pressure threshold. Ownerless workspaces prefer an empty sandbox when disk used ratio exceeds this value, and the controller reserves extra migration headroom. Defaults to 0.85.
fleet.max_workspaces_per_sandboxnumberCapacity limit for how many workspaces a single real sandbox should carry. Defaults to 32.
fleet.ownerless_poolstringHow workspaces without ownerId are grouped into sandboxes. shared uses a shared pool; dedicated gives each workspace its own sandbox.
self_hosted.base_urlstringRequired when provider=self_hosted. Base /internal/v1 URL exposed by the sandbox-resident standalone worker.
self_hosted.headersobjectOptional static headers attached to remote self-hosted sandbox requests.
e2b.base_urlstringOptional when provider=e2b. Overrides the native E2B API base URL; legacy /internal/v1-style URLs are normalized automatically.
e2b.api_keystringOptional. When set, OAH sends it as Authorization: Bearer <key> on e2b requests.
e2b.domainstringOptional. Overrides the E2B sandbox domain.
e2b.templatestringOptional. Selects the E2B template used when creating sandboxes.
e2b.timeout_msnumberOptional. Timeout for sandbox create / resolve operations.
e2b.request_timeout_msnumberOptional. Timeout for individual E2B HTTP requests.
e2b.headersobjectOptional static headers attached to e2b requests.

tip OAH keeps the external /sandboxes API stable. Switching sandbox.provider changes only the server-side sandbox backend wiring; the Web app, OpenAPI clients, and runtime callers do not need to change their request shape.

tip The /sandboxes surface, the /workspace root, and sandbox-scoped file / command semantics are intentionally kept this way to stay compatible with E2B. Treat them as a deliberate contract, not as a temporary legacy shim that should default back to /workspaces. The /workspaces API itself still remains in place for workspace metadata, catalog, and lifecycle concerns.

tip self_hosted and e2b share the same execution semantics: oah-api routes workspaces into a real sandbox, while the standalone worker inside that sandbox owns the live workspace copy, local file state, and command execution context.

tip The controller now treats sandbox fleet demand as a first-class signal: the same ownerId prefers the same real sandbox, while ownerless workspaces use a shared pool by default. Ownerless workspaces first reuse existing sandboxes whose CPU, memory, and disk are below threshold; when any resource crosses the threshold, placement falls back to the empty sandboxes reserved by warm_empty_count.

tip Starting with the current version, createSession asynchronously prewarms the target workspace after the session is created. With a remote sandbox provider, that eagerly binds the workspace to a sandbox; with workspace materialization enabled, it also prepares the active workspace copy ahead of the first user message. Combined with the remote-provider default fleet.warm_empty_count = 1, this removes most first-message cold-start latency, although very large first-time materializations can still dominate.

tip sandbox is a host-layer concept, not a project-layer concept. One sandbox may carry multiple active workspaces. It answers “where does the worker run?”, while a workspace answers “which project and capability set is being executed?”

FieldTypeDescription
workspace_dirstringProject workspace root directory
runtime_state_dirstringRuntime-private state root for SQLite shadow data, archive exports, and legacy materialization state. Defaults to dirname(workspace_dir)/.openharness
runtime_dirstringWorkspace runtime directory
model_dirstringPlatform model definition directory
tool_dirstringPlatform tool source directory, primarily used for runtime imports and shared single-workspace sources
skill_dirstringPlatform skill source directory, primarily used for runtime imports and shared single-workspace sources
FieldTypeDescription
materialization.idle_ttl_msnumberHow long an active workspace copy may stay idle before flush / cleanup is considered. Default 900000.
materialization.maintenance_interval_msnumberBackground maintenance interval for workspace materialization. Default 5000.

tip workspace.materialization primarily affects object-storage backing stores, remote sandboxes, and active workspace-copy lifecycle timing. It does not change the declarative workspace capability model.

FieldTypeDescription
default_modelstringDefault model name. Must exist in model_dir. Resolved to platform/<name> at runtime.
FieldTypeDescription
embedded.min_countnumberMinimum always-on worker count in API + embedded worker mode.
embedded.max_countnumberMaximum embedded worker count under queue pressure.
embedded.scale_interval_msnumberRebalance interval for the embedded worker pool.
embedded.idle_ttl_msnumberHow long surplus embedded workers may stay idle before cleanup.
embedded.scale_up_windownumberConsecutive high-pressure samples required before scaling up.
embedded.scale_down_windownumberConsecutive low-pressure samples required before scaling down.
embedded.cooldown_msnumberCooldown between embedded worker scaling actions.
embedded.reserved_capacity_for_subagentnumberMinimum spare embedded capacity reserved for subagent backlog.
standalone.min_replicasnumberMinimum sandbox replicas the controller may keep for standalone workers. Set 0 to allow scale-to-zero when idle.
standalone.max_replicasnumberMaximum sandbox replicas the controller may target for standalone workers.
standalone.ready_sessions_per_capacity_unitnumberQueue-density target used by the controller when translating observed worker capacity into sandbox replica demand.
standalone.reserved_capacity_for_subagentnumberMinimum observed execution capacity reserved for subagent backlog.
standalone.slots_per_podnumberLegacy compatibility field. The controller no longer uses this static value to size sandbox replicas and instead relies on worker-reported observed capacity.
controller.scale_interval_msnumberHow often the controller samples backlog / worker-registry state and recomputes desired replicas.
controller.scale_up_windownumberConsecutive high-pressure samples required before scaling up.
controller.scale_down_windownumberConsecutive low-pressure samples required before scaling down.
controller.cooldown_msnumberCooldown between controller scaling actions.
controller.scale_up_busy_ratio_thresholdnumberBusy-ratio threshold in the range 0..1 that may trigger extra scale-up.
controller.scale_up_max_ready_age_msnumberAllows scale-up when the oldest schedulable ready session exceeds this age.
controller.leader_election.typestringLeader-election type for the controller. Supports noop and kubernetes.
controller.leader_election.kubernetes.*objectKubernetes lease settings such as namespace, lease name, API URL, token file, CA file, skip TLS verify, and identity.
controller.scale_target.typestringScale-target backend. Supports noop, kubernetes, and docker_compose.
controller.scale_target.allow_scale_downbooleanWhether the controller may actively scale down replicas.
controller.scale_target.kubernetes.*objectKubernetes workload /scale target settings such as namespace, workload kind/name, legacy deployment, statefulset, label selector, API URL, token file, CA file, and skip TLS verify.
controller.scale_target.docker_compose.*objectLocal Docker Compose scaling settings such as compose file, project name, service, command, plus optional remote executor endpoint, auth token, and timeout.

tip The controller boundary is now explicitly sandbox-only. How many threads, slots, or processes run inside a sandbox is owned by the worker runtime itself; the controller only consumes the observed capacity those workers publish and turns it into sandbox replica and placement decisions.


ObjectRoleActive execution location
workspace_dirworkspace source / managed rootNot always
runtime_state_direngine-private state rootNo
runtime_dirinitialization source for new workspacesNo
Active Workspace Copyactive execution copy of a workspaceYes

Read them like this:

  • workspace_dir answers “which workspaces exist”
  • runtime_dir answers “how a new workspace is initialized”
  • sandbox answers “where the current run executes”
  • runtime_state_dir answers “where engine-private state lives”

Each direct subdirectory is treated as one project workspace. Only first-level subdirectories are scanned. This directory should hold workspace source roots only and should not be relied on as an engine-internal state root.

In embedded mode, active execution often happens directly against the local workspace. In self_hosted / e2b, the active execution copy is usually materialized into the owner sandbox, so workspace_dir behaves more like a managed source root than the final execution location.

Stores runtime-private state, including:

  • SQLite shadow history.db
  • Archive export output
  • Legacy object-store materialization state

The default is dirname(workspace_dir)/.openharness, which keeps the live workspace root separate from internal runtime state. If you want this state to survive container restarts, mount it to durable writable storage explicitly.

Stores workspace runtime templates. When creating a new workspace via POST /workspaces, a runtime from this directory is used as the initialization source. Runtimes are never loaded as active workspaces at runtime.

runtime_dir does not participate in run execution and never holds the active execution copy of a workspace. It only answers “how do we initialize a workspace?”, not “where is it currently running?”

For the files inside a runtime template, such as .openharness/settings.yaml, prompts.yaml, and agents/*.md, see the Runtime configuration guide. This page only describes where the server reads templates from and how they relate to workspace roots, sandboxes, and runtime state.

Recursively scans *.yaml files in the directory. File format matches workspace .openharness/models/*.yaml. Loaded models appear as platform/<name> in the model catalog.

First-time OAH_HOME initialization includes models/openai-default.yaml, matching the default llm.default_model: openai-default. The template file does not store a key; local usage usually only needs OPENAI_API_KEY in the daemon environment, or you can add key: ${env.OPENAI_API_KEY} explicitly.

Example (model_dir/openai-default.yaml):

openai-default:
provider: openai
key: ${env.OPENAI_API_KEY}
name: gpt-5

Platform-level tool source directory. Its structure should match workspace .openharness/tools (settings.yaml + servers/*). In the current implementation it is primarily used as the import source for runtime imports.tools, and as a shared source in single-workspace mode.

tip When OAH runs inside Docker, HTTP MCP servers configured with http://127.0.0.1:... or http://localhost:... are rewritten at runtime to a host-reachable alias. The default alias is host.docker.internal. Override it with OAH_DOCKER_HOST_ALIAS if needed.

Platform-level skill source directory. In the current implementation it is primarily used as the import source for runtime imports.skills, and as a shared source in single-workspace mode.

warning Contents of tool_dir and skill_dir are primarily imported during runtime initialization. At runtime, workspaces use only capabilities declared in their own .openharness directory, plus any content already copied into that workspace during initialization.


ModeCommandDescription
API + embedded workerpnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/index.ts -- --config server.yamlSmallest deployment. One oah-api process directly hosts the embedded worker.
API onlypnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/index.ts -- --config server.yaml --api-onlyStarts oah-api only. Typically paired with oah-controller and oah-sandbox.
Standalone workerpnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/worker.ts -- --config server.yamlStandalone worker, typically running inside a self-hosted or E2B sandbox.

In addition to YAML config, the server also reads a set of runtime environment variables for recovery, worker-pool behavior, and diagnostics.

VariableDefaultDescription
OAH_RUN_HEARTBEAT_INTERVAL_MS5000Interval for run heartbeat writes while a run is active.
OAH_STALE_RUN_TIMEOUT_MS120000Duration without a run heartbeat before stale-run recovery starts. LAN or remote-worker deployments can increase this further, for example 300000.
OAH_STALE_RUN_RECOVERY_STRATEGYrequeue_running with Redis, otherwise failStale-run recovery strategy. Supports fail, requeue_running, and requeue_all.
OAH_STALE_RUN_RECOVERY_MAX_ATTEMPTS1Maximum number of automatic requeue attempts per run.
VariableDefaultDescription
OAH_EMBEDDED_WORKER_MIN2 with Redis, otherwise 1Minimum embedded worker instances; standalone worker processes always keep at least 1.
OAH_EMBEDDED_WORKER_MAXSame as OAH_EMBEDDED_WORKER_MINMaximum embedded worker instances.
OAH_EMBEDDED_WORKER_SCALE_INTERVAL_MS5000Embedded worker pool rebalance interval.
OAH_EMBEDDED_WORKER_READY_SESSIONS_PER_CAPACITY_UNIT1Target ready-session density per observed execution-capacity unit.
OAH_EMBEDDED_WORKER_SCALE_UP_COOLDOWN_MS1000Scale-up cooldown.
OAH_EMBEDDED_WORKER_SCALE_DOWN_COOLDOWN_MS15000Scale-down cooldown.
OAH_EMBEDDED_WORKER_SCALE_UP_SAMPLE_SIZE2Consecutive high-pressure samples required before scaling up.
OAH_EMBEDDED_WORKER_SCALE_DOWN_SAMPLE_SIZE3Consecutive low-pressure samples required before scaling down.
OAH_EMBEDDED_WORKER_SCALE_UP_BUSY_RATIO_PERCENT75Busy-ratio threshold that may unlock extra scale-up when combined with queue age.
OAH_EMBEDDED_WORKER_SCALE_UP_MAX_READY_AGE_MS2000Allows age-driven scale-up once the oldest schedulable session waits longer than this.
OAH_EMBEDDED_WORKER_RESERVED_CAPACITY_FOR_SUBAGENT1Extra spare capacity reserved when subagent backlog appears; may be set to 0.
VariableDefaultDescription
OAH_HISTORY_EVENT_RETENTION_DAYS7Retention window for historical events in PostgreSQL mode.
OAH_STORAGE_ADMIN_POSTGRES_OVERVIEW_COUNTScachedPostgres table row-count mode for storage overview: cached, exact, estimated, or skip.
OAH_STORAGE_ADMIN_POSTGRES_OVERVIEW_COUNT_TTL_MS30000Postgres overview table row-count cache TTL in cached mode, capped at one hour.
OAH_STORAGE_ADMIN_POSTGRES_DEEP_OFFSET_LIMIT10000Maximum offset allowed for storage table browsing before callers must use the returned nextCursor for keyset pagination.
OAH_STORAGE_ADMIN_ALLOW_FULL_ROW_SEARCHunsetWhen set, allows Postgres full-row search without searchMode=full_row; by default callers must opt in explicitly.
OAH_STORAGE_ADMIN_REDIS_OVERVIEW_KEY_LIMIT200Maximum number of Redis session queue / lock / event keys scanned and returned per category in storage overview, capped at 10000; responses include truncated flags when the cap is reached.
OAH_METADATA_RETENTION_ENABLEDtrue for worker/embedded worker processes, false for API-onlyEnables Postgres metadata retention cleanup; this should normally run on workers so API-only stays light.
OAH_METADATA_RETENTION_INTERVAL_MS3600000Postgres metadata retention interval, with a 1-minute minimum.
OAH_METADATA_RETENTION_BATCH_LIMIT1000Maximum deleted rows per metadata category per retention pass, capped at 10000.
OAH_SESSION_EVENT_RETENTION_DAYS14Retention window for Postgres session_events; set to 0 to disable this category.
OAH_RUN_RETENTION_DAYS0Retention window for ended runs and their cascaded detail rows; disabled by default and only active when set to a positive value.
OAH_POSTGRES_ARCHIVE_MAX_COMPONENT_ROWSsee per-category defaultsShared upper bound for each detail category while constructing deleted workspace/session archives, preventing a single archive from growing unbounded in memory.
OAH_POSTGRES_ARCHIVE_MAX_SESSIONS10000Maximum sessions per Postgres archive.
OAH_POSTGRES_ARCHIVE_MAX_RUNS50000Maximum runs per Postgres archive.
OAH_POSTGRES_ARCHIVE_MAX_MESSAGES100000Maximum messages per Postgres archive.
OAH_POSTGRES_ARCHIVE_MAX_RUNTIME_MESSAGES100000Maximum runtime messages per Postgres archive.
OAH_POSTGRES_ARCHIVE_MAX_RUN_STEPS100000Maximum run steps per Postgres archive.
OAH_POSTGRES_ARCHIVE_MAX_TOOL_CALLS100000Maximum tool calls per Postgres archive.
OAH_POSTGRES_ARCHIVE_MAX_HOOK_RUNS100000Maximum hook runs per Postgres archive.
OAH_POSTGRES_ARCHIVE_MAX_ARTIFACTS100000Maximum artifacts per Postgres archive.
OAH_POSTGRES_ARCHIVE_PAYLOAD_DIRruntime_state_dir/archive-payloadsExternal payload directory for Postgres deleted workspace/session archive details; new archives keep only a lightweight reference in the archives table.
OAH_ARCHIVE_EXPORT_BUNDLE_RETENTION_DAYSunsetRetention window for exported SQLite archive bundle files; the exporter supports this policy and leaves bundle files untouched when unset.
OAH_RUNTIME_DEBUGunsetMirrors runtime debug logs to stdout when set.
OAH_DOCKER_HOST_ALIAShost.docker.internalHost alias used when OAH runs inside Docker and an HTTP MCP server is configured with a loopback URL such as 127.0.0.1 or localhost.

tip With Redis plus API + embedded worker, OAH defaults to at least 2 embedded workers and performs lightweight scaling based on the gap between ready queue pressure and available worker capacity. scale_up_window, scale_down_window, and cooldown_ms still gate each action. If subagent backlog appears, the pool first tries to restore reserved_capacity_for_subagent so parent runs are less likely to be starved by normal backlog.

tip OAH_DOCKER_HOST_ALIAS is mainly for the case where containerized OAH needs to reach an HTTP MCP server running on the host machine. The local docker-compose.local.yml already injects host.docker.internal:host-gateway, so the default works in most setups.


JSON Schema: schemas/server-config.schema.json