Docs navigation
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

VariablePurpose
BRAINBASE_WEB_URLOverride the web app URL used by login, by the console links agent create, agent list --json, link and status print, and by the commands that call the web app directly — integrations and the provider operations of agent surface (GitHub and Linear setup, phone search, purchase and release). Default https://app.brainbaselabs.com; after a login, the console you logged in through.
BRAINBASE_CONTROL_PLANE_URLOverride the MAS control-plane host. The CLI appends /v2/cli (default host https://api.brainbaselabs.com).
BRAINBASE_API_URLLegacy 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_URLOverride the registry API host independently.
BRAINBASE_PROXY_URLOverride 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:

  1. BRAINBASE_CONTROL_PLANE_URL + /v2/cli.
  2. Legacy BRAINBASE_API_URL + /api/cli.
  3. 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, GitHub and Linear 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.

VariablePurpose
BRAINBASE_MEMORY_MCP_URLOverride the per-agent memory MCP host (default https://brainbase-memory-mcp.onrender.com).
BRAINBASE_BROWSER_MCP_URLOverride the headless browser MCP host (default https://brainbase-browser-mcp.onrender.com).
BRAINBASE_SLACK_MCP_URLOverride the Slack connector MCP host (default https://brainbase-slack-mcp.onrender.com).
BRAINBASE_MEETING_MCP_URLOverride the meeting connector MCP host (default https://meeting.mcp.brainbaselabs.com).
BRAINBASE_GITHUB_MCP_URLOverride the GitHub connector MCP host (default https://brainbase-github-mcp.onrender.com).
BRAINBASE_LINEAR_MCP_URLOverride the Linear connector MCP host, installed while Linear is connected (default https://brainbase-linear-mcp.onrender.com).
BRAINBASE_ORCHESTRATION_MCP_URLOverride 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

VariablePurpose
BRAINBASE_TOKENA long-lived PAT (bbpat_…). Overrides ~/.brainbase/token.json and the browser session.
BRAINBASE_SKIP_AUTHSet to 1 to bypass the auth gate for local development.

Integration credentials

Read by agent connect slack, agent connect linear, and the matching agent surface actions. 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.

VariablePurpose
BRAINBASE_SLACK_BOT_TOKENSlack bot token (xoxb-…) for agent connect slack. Overridden by --bot-token.
BRAINBASE_SLACK_SIGNING_SECRETSlack signing secret for agent connect slack. Overridden by --signing-secret.
BRAINBASE_LINEAR_CLIENT_SECRETLinear OAuth app client secret for agent connect linear and agent surface linear connect / reconnect. Overridden by --client-secret.
BRAINBASE_LINEAR_WEBHOOK_SIGNING_SECRETLinear webhook signing secret for the same commands. Overridden by --webhook-signing-secret.
BRAINBASE_STDIN_TIMEOUT_MSHow 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

VariablePurpose
BRAINBASE_NON_INTERACTIVESet 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.
CIAny non-empty value forces non-interactive mode, the same as BRAINBASE_NON_INTERACTIVE=1. Most CI providers set it for you.
BRAINBASE_RUN_ENTRYPOINTSet to 1 to make agent pull execute the agent entrypoint (equivalent to passing --run-entrypoint).
BRAINBASE_MCP_CHECK_TIMEOUT_MSHow long mcp check waits on each server before counting it unreachable (default 8000). A value that is not a positive number falls back to the default.

State & debugging

VariablePurpose
BRAINBASE_HOMEOverride the local config dir (default ~/.brainbase).
CODEX_HOMECodex global root, used by the codex harness (default ~/.codex).
QWEN_HOMEGlobal root for the qwen-code harness (default ~/.qwen).
OPENCODE_HOMEGlobal root for the opencode harness (default ~/.opencode).
OPENCLAW_HOMEGlobal root for the openclaw harness (default ~/.openclaw).
CURSOR_HOMEGlobal root for the cursor harness (default ~/.cursor).
FACTORY_HOMEGlobal root for the factory harness (default ~/.factory).
QODER_HOMEGlobal root for the qoder harness (default ~/.qoder).
PI_CODING_AGENT_DIRGlobal root for the pi harness (default ~/.pi/agent).
BRAINBASE_DEBUGSet to print full stack traces on error.
Credential precedence
Every authenticated command uses BRAINBASE_TOKEN first, then a valid or renewable session in ~/.brainbase/auth.json, then a usable PAT in ~/.brainbase/token.json. A saved PAT with a different account id is refused. See Authentication.