Documentation Index
Fetch the complete documentation index at: https://septemberai.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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. |
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). |
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 also
