Reference

Environment variables

Environment variables let you point the CLI at a different backend, relocate its state, or authenticate without an interactive login. All are optional.

Hosts

Variable	Purpose
`BRAINBASE_WEB_URL`	Override the web app URL used by `login` (default `https://app.brainbaselabs.com`).
`BRAINBASE_CONTROL_PLANE_URL`	Override the MAS control-plane host. The CLI appends `/v2/cli` (default host `https://api.brainbaselabs.com`).
`BRAINBASE_API_URL`	Legacy API host override. When no control-plane override is set, control-plane requests use its `/api/cli` surface. It is also the fallback override for registry and model-proxy traffic.
`BRAINBASE_REGISTRY_URL`	Override the registry API host independently.
`BRAINBASE_PROXY_URL`	Override the model-proxy host used when harness tracking is enabled.

Host resolution

Agent and orchestration control-plane operations resolve their base URL in this order:

BRAINBASE_CONTROL_PLANE_URL + /v2/cli.
Legacy BRAINBASE_API_URL + /api/cli.
https://api.brainbaselabs.com/v2/cli.

BRAINBASE_CONTROL_PLANE_URL wins when both variables are set. Declarative machine_kind / default_model writes, orchestration creation, and schedule-trigger writes require the MAS /v2/cli control plane; the legacy KLS /api/cli surface cannot perform them.

Registry requests resolve BRAINBASE_REGISTRY_URL, then legacy BRAINBASE_API_URL, then the server stored by brainbase login, then https://api.v1.brainbaselabs.com.

Model-proxy requests use the same order, with BRAINBASE_PROXY_URL as the first choice instead of BRAINBASE_REGISTRY_URL. This separation lets you point CLI control traffic at MAS without rerouting harness model traffic.

Built-in MCP overrides

The CLI installs a set of built-in MCP servers alongside an agent's own MCPs. Orchestration is always installed; memory and browser are on unless the agent turns them off; Slack, meeting and GitHub appear only while the agent has that connection active — run agent connections to see which do. Each resolves its base URL from the variable below — the supported way to point a built-in at staging or at a self-hosted deployment.

Each value is a base origin, not a full endpoint. The CLI appends the per-thread path itself, producing <base>/t/${BRAINBASE_THREAD_ID}/mcp — the placeholder stays literal in the generated config and is resolved by the harness when it connects. Passing a complete URL therefore doubles the path.

Variable	Purpose
`BRAINBASE_MEMORY_MCP_URL`	Override the per-agent memory MCP host (default `https://brainbase-memory-mcp.onrender.com`).
`BRAINBASE_BROWSER_MCP_URL`	Override the headless browser MCP host (default `https://brainbase-browser-mcp.onrender.com`).
`BRAINBASE_SLACK_MCP_URL`	Override the Slack connector MCP host (default `https://brainbase-slack-mcp.onrender.com`).
`BRAINBASE_MEETING_MCP_URL`	Override the meeting connector MCP host (default `https://meeting.mcp.brainbaselabs.com`).
`BRAINBASE_GITHUB_MCP_URL`	Override the GitHub connector MCP host (default `https://brainbase-github-mcp.onrender.com`).
`BRAINBASE_ORCHESTRATION_MCP_URL`	Override the orchestration MCP host, which exposes one `create_task_for_<recipient>` tool per outgoing edge (default `https://brainbase-orchestration-mcp.onrender.com`).

These are read when the CLI writes harness MCP config — agent pull, agent unpack, sync, and first install — and the resolved URL is written into the generated .mcp.json / mcp.json. Setting or unsetting one therefore has no effect on an agent you have already pulled; re-run brainbase agent pull to rewrite the config. Trailing slashes are stripped, and an empty value counts as unset — it falls back to the default rather than clearing the host.

An override receives the agent's token

Every built-in MCP entry authenticates as Authorization: Bearer ${BRAINBASE_TOKEN}, and the CLI does not validate the host you supply. Whatever URL you set is handed the agent's token when the harness connects, so point these only at hosts you trust.

Authentication

Variable	Purpose
`BRAINBASE_TOKEN`	A long-lived PAT (`bbpat_…`). Overrides `~/.brainbase/token.json` and the browser session.
`BRAINBASE_SKIP_AUTH`	Set to `1` to bypass the auth gate for local development.

Integration credentials

Read by agent connect slack. They exist so a script never has to put a credential in argv, where any process on the machine can read it through ps and where a shell records it in history. A flag still wins if you pass one; piped stdin is checked next when neither is set.

Variable	Purpose
`BRAINBASE_SLACK_BOT_TOKEN`	Slack bot token (`xoxb-…`) for `agent connect slack`. Overridden by `--bot-token`.
`BRAINBASE_SLACK_SIGNING_SECRET`	Slack signing secret for `agent connect slack`. Overridden by `--signing-secret`.
`BRAINBASE_STDIN_TIMEOUT_MS`	How long a piped stdin may stay silent before `agent connect` stops waiting (default `5000`). Raise it for a slow secret manager. Clamped to 100ms–10min, because `setTimeout` wraps above 2³¹ and an unclamped large value would time out almost immediately. A silence after some bytes have arrived is an error rather than a short read — the command refuses instead of sending half a credential.

CI & automation

Variable	Purpose
`BRAINBASE_NON_INTERACTIVE`	Set to `1` to force non-interactive mode, even inside a real terminal. Ordinary prompts auto-resolve to their defaults instead of waiting for input; destructive commands instead refuse and name `--yes`, exactly as if no terminal were attached — see destructive commands. For CI and agent-driven runs.
`BRAINBASE_RUN_ENTRYPOINT`	Set to `1` to make `agent pull` execute the agent entrypoint (equivalent to passing `--run-entrypoint`).

State & debugging

Variable	Purpose
`BRAINBASE_HOME`	Override the local config dir (default `~/.brainbase`).
`CODEX_HOME`	Codex global root, used by the `codex` harness (default `~/.codex`).
`BRAINBASE_DEBUG`	Set to print full stack traces on error.

Credential precedence

Precedence depends on which API the command talks to. On the control plane path (agent, orchestration, link, sync): BRAINBASE_TOKEN env, then the ~/.brainbase/auth.json JWT — token.json is not consulted here. On the registry path (template, skill, token): BRAINBASE_TOKEN env, then the auth.json JWT, then the ~/.brainbase/token.json PAT (a live login session outranks a stored PAT). See Authentication.