Environment Variables

NimbleBrain reads several environment variables for authentication, server binding, and runtime behavior. This page lists every supported variable with its purpose, default, and precedence.

Variable reference

Model providers

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	Yes (for Anthropic slots)	—	Anthropic API key. Can also be set via `providers.anthropic.apiKey` in `nimblebrain.json`.
`OPENAI_API_KEY`	Yes (for OpenAI slots)	—	OpenAI API key. Can also be set via `providers.openai.apiKey`.
`GOOGLE_GENERATIVE_AI_API_KEY`	Yes (for Google slots)	—	Google Gemini API key. Can also be set via `providers.google.apiKey`.

Runtime

Variable	Required	Default	Description
`NB_WORK_DIR`	No	`~/.nimblebrain`	Working directory for runtime state. Takes precedence over the config file and `--workdir`.
`PORT`	No	`27247`	HTTP server port. Overridden by `--port` CLI flag.
`ALLOWED_ORIGINS`	No	—	Comma-separated list of allowed CORS origins. Only relevant when auth is enabled.
`NB_CHAT_RATE_LIMIT`	No	`20`	Chat requests per minute per user.
`NB_TOOL_RATE_LIMIT`	No	`60`	Tool calls per minute per user.
`NB_TIMEZONE`	No	—	Default IANA timezone (e.g. `America/Los_Angeles`) for time-aware features.
`NB_API_URL`	Recommended (production)	`http://localhost:27247`	Public origin of the platform’s API. Used to build the OAuth callback URL surfaced to vendors. Must match the URL registered with each OAuth app’s redirect_uri allow-list.
`NB_WEB_URL`	No	falls back to `NB_API_URL`, then the request origin	Public origin of the web app. Used to build post-OAuth redirect targets back to the SPA. Only needed when the API and web are served from different origins.
`NB_HOST_URL`	No	`http://localhost:27247`	Public host URL passed to bundle subprocesses (used by automation executors and similar). Distinct from `NB_API_URL` — the OAuth callback URL is derived from `NB_API_URL`, not this.
`NB_REGISTRIES`	No	—	JSON array of registry configs that overrides the persisted `registries.json` for the lifetime of the process. Adds custom `static` / `mpak` / `mcp` registries without touching pod filesystem. The locked bundled-static registry is preserved automatically. See Connectors Catalog → Operator override.
`MCP_MAX_SESSIONS`	No	`100`	Max concurrent MCP sessions on `/mcp`. New initialize returns `429` once reached. Non-positive / non-integer values are rejected with a warning and the default is used. Sized in tandem with `MCP_SESSION_TTL_SECONDS`: longer TTLs hold more sessions in memory before they’re swept, so a fleet of 100 connectors held open all day will keep this cap pegged. Raise the cap or shorten the TTL if you have more concurrent connectors than the default headroom.
`MCP_SESSION_TTL_SECONDS`	No	`28800` (8 h)	MCP session inactivity TTL in seconds. Each request resets the clock — actively-used sessions never expire. Non-positive / non-integer values are rejected with a warning and the default is used. Also configurable via `sessionStore.ttlSeconds` in `nimblebrain.json`.

Auth & identity

Variable	Required	Default	Description
`NB_API_KEY`	No	—	API authentication key. When set, all HTTP endpoints (except health and login) require a valid Bearer token or session cookie. Minimum 8 characters.
`WORKOS_API_KEY`	When `auth.adapter: "workos"` in `instance.json`	—	WorkOS API key. Can also be set via `instance.json → auth.apiKey`.
`TURNSTILE_SECRET_KEY`	No	—	Cloudflare Turnstile secret for CAPTCHA on auth endpoints.
`NB_INTERNAL_TOKEN`	No	—	Shared secret for service-to-service calls. Never forwarded to bundle subprocesses.

Composio aggregator

Required only when the catalog contains any auth: composio entries (Gmail, Outlook, …). See the Composio operator guide for end-to-end setup.

Variable	Required	Default	Description
`COMPOSIO_API_KEY`	When the catalog contains `auth: composio` entries	—	Platform-wide Composio API key. Read once at startup. Without it, install of any `auth: composio` entry returns `500 composio_unconfigured`.
`COMPOSIO_<TOOLKIT>_AUTH_CONFIG_ID`	One per `auth: composio` entry	—	The `ac_…` id from the Composio dashboard for this toolkit’s auth config. The variable name is declared by the catalog entry’s `composio.authConfigEnv`. Example: `COMPOSIO_GMAIL_AUTH_CONFIG_ID=ac_xxx`.
`COMPOSIO_API_BASE_URL`	No	`https://backend.composio.dev`	Override the Composio SDK base URL (self-hosted Composio, staging). Must be `http(s)`.
`NB_TENANT_ID`	When running multi-tenant pods that share a Composio account	—	Per-pod tenant identifier. Prepended to the wsId so two tenants’ workspaces never collide in Composio’s namespace. Single-tenant deployments can omit it.

Telemetry

Variable	Required	Default	Description
`NB_TELEMETRY_DISABLED`	No	—	Set to `1` to disable anonymous usage telemetry.
`DO_NOT_TRACK`	No	—	Standard opt-out signal. Set to `1` to disable telemetry. Equivalent to `NB_TELEMETRY_DISABLED=1`.
`POSTHOG_API_KEY`	No	—	Override the built-in PostHog key. Rarely needed.

ANTHROPIC_API_KEY

The Anthropic API key used for all LLM calls. You can set it in the environment or in the model.apiKey field of nimblebrain.json. The environment variable is the recommended approach for production.

export ANTHROPIC_API_KEY=sk-ant-api03-...

If both the environment variable and the config field are set, the config field takes precedence.

NB_API_KEY

When set, NimbleBrain requires authentication on all API endpoints except /v1/health, /v1/bundles/health, and POST /v1/auth/login.

export NB_API_KEY=your-secret-key-here

Requirements:

Minimum 8 characters. The server throws an error at startup if the key is shorter.
Keys shorter than 16 characters produce a warning recommending a longer key for production use.

Authentication uses constant-time comparison to prevent timing attacks. Clients authenticate with either:

A Bearer token in the Authorization header
An nb_session HttpOnly cookie set by POST /v1/auth/login

When NB_API_KEY is not set, the server runs in dev mode with no authentication and Access-Control-Allow-Origin: *.

NB_API_URL

The public origin of the platform’s API. Used to build the OAuth callback URL that the platform sends to vendors:

${NB_API_URL}/v1/mcp-auth/callback

Each OAuth app registered with a vendor (Asana, HubSpot, Gmail, …) must list this exact URL in its redirect_uri allow-list. Mismatch surfaces as a vendor-side redirect_uri does not match error at the moment a user clicks Connect — long after the admin has configured the OAuth app, which makes the failure mode confusing.

export NB_API_URL=https://nimblebrain.acme.com

The Set up modal in the UI shows the resolved redirect URI with a Copy button — the operator should paste that exact string into the vendor portal.

In dev (bun run dev) the default http://localhost:27247 is correct without setting the variable. In production, always set this explicitly. Pointing it at localhost, an internal cluster service name, or a stale staging URL will produce confusing OAuth failures that look like vendor outages.

NB_WORK_DIR

Sets the working directory where NimbleBrain stores all runtime state.

export NB_WORK_DIR=/data/nimblebrain

The working directory contains:

nimblebrain.json — Config file (if no --config flag is set)
conversations/ — JSONL conversation files (when using JSONL store)
logs/ — Structured JSONL logs
skills/ — Global skill files
cache/ — Bundle cache

Precedence: NB_WORK_DIR env var > workDir in config file > --workdir flag > command default (~/.nimblebrain for nb serve, ./.nimblebrain for nb dev)

ALLOWED_ORIGINS

Controls which origins can make cross-origin requests when NB_API_KEY is set.

export ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com

Behavior depends on the combination of NB_API_KEY and ALLOWED_ORIGINS:

NB_API_KEY	ALLOWED_ORIGINS	CORS behavior
Not set	—	`Access-Control-Allow-Origin: *` (dev mode)
Set	Not set	Same-origin only (no CORS header sent)
Set	Set	Only listed origins get `Access-Control-Allow-Origin` with `Access-Control-Allow-Credentials: true`

Separate multiple origins with commas. Whitespace around origins is trimmed.

Telemetry variables

Two environment variables disable anonymous telemetry. Either one is sufficient.

# Either of these disables telemetry
export NB_TELEMETRY_DISABLED=1
export DO_NOT_TRACK=1

DO_NOT_TRACK follows the Console Do Not Track standard. You can also disable telemetry via:

telemetry.enabled: false in nimblebrain.json
nb telemetry off CLI command

Precedence summary

When the same setting can be configured in multiple places, this is the resolution order (highest priority first):

Setting	CLI flag	Env var	Config file	Default
Working directory	`--workdir`	`NB_WORK_DIR` (beats all)	`workDir`	`~/.nimblebrain`
Model (legacy)	`--model`	—	`defaultModel`	— (use `models.default`)
Port	`--port`	`PORT`	`http.port`	`27247`
API key	—	`NB_API_KEY`	—	None (no auth)
Anthropic key	—	`ANTHROPIC_API_KEY`	`providers.anthropic.apiKey`	—
Telemetry	`nb telemetry off`	`NB_TELEMETRY_DISABLED` / `DO_NOT_TRACK`	`telemetry.enabled`	Enabled

Example: production environment

A typical production setup with all relevant variables:

export ANTHROPIC_API_KEY=sk-ant-api03-...
export NB_API_KEY=$(openssl rand -hex 32)
export NB_WORK_DIR=/data/nimblebrain
export ALLOWED_ORIGINS=https://app.example.com
export NB_TELEMETRY_DISABLED=1