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, 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_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, 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.
| 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_LINEAR_MCP_URL | Override the Linear connector MCP host, installed while Linear is connected (default https://brainbase-linear-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.
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, 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.
| 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_LINEAR_CLIENT_SECRET | Linear OAuth app client secret for agent connect linear and agent surface linear connect / reconnect. Overridden by --client-secret. |
BRAINBASE_LINEAR_WEBHOOK_SIGNING_SECRET | Linear webhook signing secret for the same commands. Overridden by --webhook-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. |
CI | Any non-empty value forces non-interactive mode, the same as BRAINBASE_NON_INTERACTIVE=1. Most CI providers set it for you. |
BRAINBASE_RUN_ENTRYPOINT | Set to 1 to make agent pull execute the agent entrypoint (equivalent to passing --run-entrypoint). |
BRAINBASE_MCP_CHECK_TIMEOUT_MS | How 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
| Variable | Purpose |
|---|---|
BRAINBASE_HOME | Override the local config dir (default ~/.brainbase). |
CODEX_HOME | Codex global root, used by the codex harness (default ~/.codex). |
QWEN_HOME | Global root for the qwen-code harness (default ~/.qwen). |
OPENCODE_HOME | Global root for the opencode harness (default ~/.opencode). |
OPENCLAW_HOME | Global root for the openclaw harness (default ~/.openclaw). |
CURSOR_HOME | Global root for the cursor harness (default ~/.cursor). |
FACTORY_HOME | Global root for the factory harness (default ~/.factory). |
QODER_HOME | Global root for the qoder harness (default ~/.qoder). |
PI_CODING_AGENT_DIR | Global root for the pi harness (default ~/.pi/agent). |
BRAINBASE_DEBUG | Set to print full stack traces on error. |
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.