Environment variables

Every environment variable bap-engine reads.

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.

See also

• Architecture — what each var affects.
• Deploy — production setup.
• Health — ORCH_HEALTH_* and ORCH_RESTART_* tuning.
• Security — ORCH_MASTER_KEY rotation.