Environment variables#
Every supported variable. Values go in .env.local, which is not committed.
Operator access and identity#
| Variable | Required | Default | Effect |
|---|---|---|---|
BLACKBOX_OPERATOR_TOKEN |
No, unless binding beyond loopback | Unset | Requires Authorization: Bearer or x-blackbox-operator-token on Director pages and application APIs |
BLACKBOX_WORLD_ID |
No | wld_ridgeport for migrated stores |
Asserts the expected world identity; never rebinds a store silently |
BLACKBOX_BIND_HOST |
No | 127.0.0.1 |
Bind address. A non-loopback value requires an operator token |
BLACKBOX_CONFIG_DIR |
Required for a service installation | Interactive user profile | Absolute directory for provider settings and the stored device token |
BLACKBOX_DATA_DIR |
No | Application data/ |
Where world state is written |
Provenance#
| Variable | Required | Effect |
|---|---|---|
BLACKBOX_COMMIT_SHA |
For Docker | Records the commit the image was built from |
BLACKBOX_SOURCE_SHA256 |
For Docker | Records the source fingerprint, produced by npm run --silent source:fingerprint |
World host#
These are used by the Windows host service, not by a development run.
| Variable | Required | Effect |
|---|---|---|
BLACKBOX_HOST_CONTROL_TOKEN |
In production | Authorises the loopback graceful-stop endpoint. At least 32 random bytes, unpadded base64url. Keep separate from the operator token |
BLACKBOX_HOST_OPERATOR_TOKEN |
By the Windows host | Forwarded to Node as BLACKBOX_OPERATOR_TOKEN |
BLACKBOX_HOST_COMMIT_SHA |
By the Windows host | Immutable release provenance |
BLACKBOX_HOST_SOURCE_SHA256 |
By the Windows host | Immutable release provenance |
BLACKBOX_HOST_BASE_URL |
No | http://127.0.0.1:4287 |
The service-writable config directory must not contain the Windows host control JSON. The installer requires that file under a separate protected parent.
Model providers#
| Provider | Key | Overrides |
|---|---|---|
| OpenAI-compatible | OPENAI_API_KEY |
OPENAI_BASE_URL, OPENAI_MODEL |
| Anthropic | ANTHROPIC_API_KEY |
ANTHROPIC_BASE_URL, ANTHROPIC_MODEL |
| MiniMax | MINIMAX_API_KEY |
MINIMAX_BASE_URL, MINIMAX_MODEL |
| OpenRouter | OPENROUTER_API_KEY |
OPENROUTER_BASE_URL, OPENROUTER_MODEL, OPENROUTER_HTTP_REFERER, OPENROUTER_X_TITLE |
| Ollama | None | OLLAMA_BASE_URL, OLLAMA_MODEL |
A blank key means residents using that provider fail on their own turn with a runner error. The run continues, and mock and Ollama residents are unaffected.
Not for normal operation#
Several variables exist to support the test and gate suites — forcing mock runners, restricting evaluation to mock only, pinning data roots, and guarding the operator's real store during browser tests. They are not part of the supported operating surface and are not documented here as configuration. Do not set them against a real store.