> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](../health) 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:

```bash theme={null}
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](../quickstart) for the full walk-through.

## See also

* [Architecture](../architecture) — what each var affects.
* [Deploy](../deploy) — production setup.
* [Health](../health) — `ORCH_HEALTH_*` and `ORCH_RESTART_*` tuning.
* [Security](../security) — `ORCH_MASTER_KEY` rotation.