Configure

.env in the checkout is the only place the stack is configured. docker compose up reads it; the operator app shows each setting's state and takes none. After a change, restart:

docker compose up --detach --wait

Required

./setup.sh writes these four and keeps them on later runs (Install).

Variable	Value
STATE_ROOT	An absolute path on the Docker host where the stack keeps its state. OpenSandbox mounts each workspace by that path, so a relative one is refused
SECRETS_MASTER_KEY	32 random bytes, as hex or base64. It encrypts every stored credential: connector logins, organisation model keys, secrets. .env holds its only copy; a lost key loses them. The orchestrator refuses to start without it and refuses the all-zero key
POSTGRES_PASSWORD	The database password, generated
OPENSANDBOX_API_KEY	The key the orchestrator and the sandbox server share, generated

The Compose file derives the rest of the server's environment from these (DATABASE_URL, OPENSANDBOX_URL, NOTES_ROOT, WORKSPACE_ROOT, ATTACHMENTS_ROOT, SANDBOX_IMAGE, SANDBOX_IMAGE_LITE); you do not set them.

Integrations

An integration is a credential the box holds for everyone on it, as opposed to an organisation's own model key, connection, or secret. Each is optional and is on once every variable it requires has a value. The registry is apps/orchestrator/src/instance/integrations.ts; Admin, Platform keys lists each one with its state (on, off, or incomplete when some of its variables are set), what it switches on, and which variables are set, never a value. A screen that depends on a missing integration says which variables would switch it on.

Integration	Variables	Switches on	Without it
OpenRouter	OPENROUTER_API_KEY	OpenRouter models for an organisation with no OpenRouter key of its own	The models stay selectable. For an organisation with no key either, a banner above every page says no model key is set and names the two ways to give one, the picker marks them No OpenRouter key yet, and a run fails at its first model call with OPENROUTER_API_KEY is not set
DeepInfra	DEEPINFRA_API_KEY	DeepInfra models for an organisation with no DeepInfra key of its own	As for OpenRouter
Web search	TAVILY_API_KEY	The tavily_search tool	The tool is left out of every run, and Tools lists it as not offered with the variable to set
Group routing	TYPESAFE_API_KEY, and TYPESAFE_MODEL to tune it	Recipient and history selection in group chat, beyond tag rules	Tag rules and the last 10 messages
GitHub App	GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET	The GitHub connector and a guild's repositories	Tools marks the connector Not set up, names the missing variables, and disables Connect
Google connectors	GMAIL_OAUTH_CLIENT_ID, GMAIL_OAUTH_CLIENT_SECRET	The Gmail and Drive connectors	As for the GitHub App
Error reporting	SENTRY_DSN	Errors and traces sent to Sentry	Structured logs only (Operate)

A key reaches the server through .env alone: the Compose file passes the file with env_file, so a variable exported in the shell does not reach the container. Model keys an organisation sets for itself live under Settings, Model keys and resolve before the instance's.

Connectors that sign in with OAuth return to <PUBLIC_BASE_URL>/api/mcp/oauth/callback, or to the loopback address when PUBLIC_BASE_URL is empty; register that URI on the OAuth client or GitHub App you configure (Remote access).

Reaching the box

Variable	Default	Role
ORCHESTRATOR_PORT	8080	The loopback port the operator app is published on
AUTH_MODE	compat-cookie	How a request becomes a user. compat-cookie: whoever reaches the port is the operator. trusted-header: an authenticating proxy in front sends each person's email
PUBLIC_BASE_URL	empty	The address the box is reached at from elsewhere. The server answers requests for a loopback host or this one
TRUSTED_PROXY_SECRET		The secret the proxy sends in X-Guilds-Proxy-Secret; required by trusted-header
TRUSTED_HEADER_EMAIL	X-Forwarded-Email	The header the proxy sends the email in
OPERATOR_EMAIL		Your own email, which boot gives the box's first user; required by trusted-header

Remote access covers the two ways to reach the box from another machine.

Limits

Variable	Default	Role
MAX_CONCURRENT_GENERATIONS	0	Generations running at once across the whole box; 0 is no ceiling. Each organisation's own cap applies under it

Error reporting

Variable	Default	Role
SENTRY_DSN		Switches Sentry on
SENTRY_ENVIRONMENT	development	The environment tag on each event
SENTRY_TRACES_SAMPLE_RATE	1.0	The share of requests traced, 0 to 1

Development

Read by the development stack and the contracts, not by the shipped one (Development): MODEL_CONTRACT_MODEL, DOCS_LLM_MODEL, DOCS_EMBEDDING_MODEL, DOCS_EMBEDDING_DIM, LIGHTRAG_API_KEY, LIGHTRAG_URL.