Environment variables

bap-engine’s settings are loaded from environment variables prefixed ORCH_* (Pydantic BaseSettings). LLM provider keys (LLM_API_KEY, OPENAI_API_KEY, etc.) aren’t ORCH_-prefixed because they’re forwarded to engine containers; the orchestrator just passes them through.

Required

Name	Type	Purpose
`ORCH_DATABASE_URL`	str	PostgreSQL connection string. Format: `postgresql://user:password@host:port/database`.
`ORCH_MASTER_KEY`	str	Fernet key (base64 32 bytes) used to encrypt engine API keys at rest. Lose this and every engine key is unrecoverable.
`ORCH_ADMIN_KEY`	str	Admin key for `/products/register` and `/products/{id}/policy`. Use a strong random string.

Engine provider keys (passed through)

The orchestrator forwards these to engine containers — it doesn’t read them itself. Engines need them to talk to LLM providers.

Name	Required	Purpose
`LLM_API_KEY`	yes	Primary LLM provider key. Must match `llm_provider` in the engine’s `engine.yaml`.
`OPENAI_API_KEY`	yes	OpenAI key. Always required — the engine uses it for embeddings regardless of chat provider.
`ANTHROPIC_API_KEY`	no	Anthropic key. Optional unless `LLM_API_KEY` is Anthropic.
`GEMINI_API_KEY`	no	Google Gemini key. Optional unless Gemini is the LLM provider.

These are forwarded only if listed in ORCH_ENGINE_ENV_PASSTHROUGH.

Orchestrator configuration

Name	Default	Purpose
`ORCH_ENGINE_IMAGE`	`september-engine:latest`	Docker image tag for engine containers. Pin a specific version in production.
`ORCH_ENGINE_BACKEND`	`docker`	`docker` (production) or `subprocess` (dev).
`ORCH_ENGINE_ENV_PASSTHROUGH`	(empty)	Comma-separated env var names to forward. Typical: `LLM_API_KEY,OPENAI_API_KEY,ANTHROPIC_API_KEY,GEMINI_API_KEY`.
`ORCH_ENGINE_NETWORK`	`engine_net`	Docker network the orchestrator and engine containers share.
`ORCH_PORT_MIN`	`9001`	Lower bound of the engine port range.
`ORCH_PORT_MAX`	`9999`	Upper bound.
`ORCH_CATALOG_MOUNT_PATH`	`./catalog`	Host path mounted into engines as `/catalog` (read-only).
`ORCH_DATA_ROOT_PATH`	`./engine-data`	Host path under which engine brain volumes live.
`ORCH_HOST`	`127.0.0.1`	Listen address. Use `0.0.0.0` in production behind a reverse proxy.
`ORCH_PORT`	`8000`	Listen port.

Health and recovery

Name	Default	Purpose
`ORCH_HEALTH_CHECK_INTERVAL_S`	`30`	Seconds between health-check sweeps over the running fleet.
`ORCH_HEALTH_CHECK_TIMEOUT_S`	`10`	Per-probe HTTP timeout. Should be < interval.
`ORCH_HEALTH_MAX_FAILURES`	`3`	Consecutive failed probes before marking an engine `failed`.
`ORCH_RESTART_BACKOFF_BASE_S`	`5`	First retry delay. Doubles each attempt.
`ORCH_RESTART_BACKOFF_MAX_S`	`300`	Cap on backoff (5 minutes).
`ORCH_RESTART_MAX_ATTEMPTS`	`8`	Give up auto-restart after this many failures.
`ORCH_BOOT_TIMEOUT_S`	`60`	Maximum seconds to wait for a new engine’s `/health` after provisioning.
`ORCH_IDLE_SLEEP_THRESHOLD_S`	`3600`	Seconds since `last_health_at` before marking an engine `sleeping` (1 hour).

See Health and auto-restart for tuning by use case.

Build-time only

Name	Purpose
`GITHUB_TOKEN`	GitHub PAT with read access to `septemberai/engine`. Required at image build time only — to `pip install` the engine package from the private repo. Don’t bake into the image; pass as a build-time secret.

Conventions

Booleans are not used in orchestrator settings — most knobs are ints or strings. The engine’s "true" / "false" convention applies to engine vars, which the orchestrator forwards as-is.
Paths are absolute when crossing the orchestrator-to-Docker boundary; relative paths get resolved against the orchestrator’s working directory.
Secrets never go in code or images. Inject from your secret manager at runtime.

Local-dev shortcut

For the local quickstart, this minimal .env works:

ORCH_DATABASE_URL=postgresql://orch_user:orch_local_dev@postgres:5432/orchestrator
ORCH_MASTER_KEY=<fernet key>
ORCH_ADMIN_KEY=dev-admin-key
ORCH_ENGINE_IMAGE=september-engine:2.3.0
ORCH_ENGINE_BACKEND=docker
ORCH_ENGINE_ENV_PASSTHROUGH=LLM_API_KEY,OPENAI_API_KEY,ANTHROPIC_API_KEY,GEMINI_API_KEY
LLM_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...

See Quickstart for the full walk-through.

Architecture

BAP Engine

Engineering

Environment variables

Required

Engine provider keys (passed through)

Orchestrator configuration

Health and recovery

Build-time only

Conventions

Local-dev shortcut

See also

​Required

​Engine provider keys (passed through)

​Orchestrator configuration

​Health and recovery

​Build-time only

​Conventions

​Local-dev shortcut

​See also

Required

Engine provider keys (passed through)

Orchestrator configuration

Health and recovery

Build-time only

Conventions

Local-dev shortcut

See also