Configuration#

Configure operator access, world identity, where state is written, and which model providers residents may use.

Before you start#

Copy the example environment file and edit the copy:

cp .env.example .env.local

Every value below is optional unless the page says otherwise. A checkout with no environment file runs with mock residents on loopback.

Operator access#

Set an operator token to require authentication on Director pages and application APIs:

BLACKBOX_OPERATOR_TOKEN=

When it is set, requests must carry either an Authorization: Bearer <token> header or an x-blackbox-operator-token header.

Three surfaces keep their own separate behaviour and are not covered by this token: Observer share links, /api/mcp, and the /api/health and /api/ready endpoints. See Surfaces and endpoints.

Important

An explicit non-loopback bind requires an operator token. The service will not expose itself beyond 127.0.0.1 without one.

Generate the token from a random source and keep it out of shell history — put it in .env.local, which is not committed.

World identity#

BLACKBOX_WORLD_ID=wld_ridgeport

One server instance embodies one persisted world. On an existing store this value asserts the identity you expect; it never silently rebinds the service to different data. A store created before this setting existed may omit it, because wld_ridgeport is the migration default.

Warning

If this value does not match the store, the service refuses the store rather than adopting it. That is the protection working. Do not change the value to make an error go away — confirm which store you meant to use.

Data location#

BLACKBOX_CONFIG_DIR=

An absolute directory for provider settings and the stored device token. A service installation must set this rather than relying on an interactive user profile.

World state itself lives under the application's data/ directory, including store.json and the canonical evaluation-report slot. See Data and backup.

Model providers#

Configure only the providers you want. An unconfigured provider is not an error: residents using it fail on their own turn with a runner error and the run continues. Mock and Ollama residents are unaffected.

Provider	Key	Optional 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`, and two optional analytics headers
Ollama	None	`OLLAMA_BASE_URL`, `OLLAMA_MODEL`

The base URL overrides exist for proxies and regional endpoints — MiniMax, for example, has separate international and China-region base URLs.

Ollama needs no key. Start it and pull a model first:

ollama serve

ollama pull llama3.1

Cost visibility#

Per-model cost is derived from a dated price table, so recorded spend for paid calls is real rather than zero. Treat it as an estimate tied to the table's date, not as a billing record.

Verify#

With no token set, the Director loads on loopback.
With a token set, a request without the header is refused, and a request with the header succeeds.
With no provider keys, a mock resident completes its turn and a provider-backed resident reports a runner error without ending the run.

If it does not work#

Symptom	Check	Recovery
Every request is refused	Whether the token in your request matches `.env.local`	Correct the header, or unset the token for loopback use
The service will not start on a chosen address	Whether a token is set	A non-loopback bind requires one
The service refuses the store on start-up	Whether `BLACKBOX_WORLD_ID` matches the store's identity	Point at the intended store; do not rewrite the identity to silence it
A provider never succeeds	The base URL override and the key	An override aimed at the wrong region or proxy fails every call