Docs navigation
Agent

Secrets

Secrets are environment variables and credentials available to an agent at runtime. Use them when tools, entrypoints, functions, or integrations need private values that should not appear in prompts, playbooks, or committed files.

How to use secrets
  1. 01Open the agent's Secrets area.
  2. 02Click Add secret.
  3. 03Enter a key (uppercase letters, digits, and underscores, starting with a letter) and the secret value.
  4. 04Save your changes.

Add a secret

Add secrets from the agent sidebar when you want the cloud runtime to inject them into the agent's sandbox. Saved values are never shown again, in the app or through the API; to change one, type a new value over it. The agent reads them through the normal environment-variable interface for its runtime, such as process.env.LINEAR_API_KEY.

Keys must match ^[A-Z][A-Z0-9_]*$: uppercase letters, digits, and underscores, starting with a letter. A small set of names the platform sets in every sandbox is reserved and is never injected from secrets, even if you save one: platform variables such as BRAINBASE_TOKEN, BRAINBASE_TASK_ID, BRAINBASE_AGENT_ID, BRAINBASE_API_URL, and BRAINBASE_SHARED_DIR, along with BB_TASK_KEY, MEDIA_API_KEY, PROXY_BASE_URL, and IS_SANDBOX. Use your own prefix for custom values. Model-provider overrides such as ANTHROPIC_BASE_URL and OPENAI_BASE_URL are not reserved.

An agent can also inherit secrets from the orchestration it belongs to (an agent can be a member of only one orchestration at a time). Inherited keys appear on this page with the orchestration they come from, and an agent-level secret of the same name overrides them — see Orchestration Secrets.

What secrets are for

  • API keys: Tokens for internal services or third-party APIs.
  • Configuration: Private base URLs, tenant IDs, or account-specific settings.
  • Entrypoint setup: Tokens or registry credentials needed while installing dependencies.
  • Function runtime: Values custom functions need without hard-coding them.
Never commit secret values
The CLI stores local secrets in .brainbase/secrets.env, which is gitignored. Do not put real secret values in brainbase.agent.yaml, playbooks, instructions, memory, or example files.

When to add a secret

Add a secret when a value is private, environment-specific, or likely to rotate. Reference the secret by key from the tool, entrypoint, or function that needs it.

Best practices

  • Use clear uppercase keys like LINEAR_API_KEY or CRM_BASE_URL, and avoid the BRAINBASE_ prefix the platform uses for its own variables.
  • Keep keys unique; duplicate keys cannot be saved.
  • Rotate secrets when people leave a team or credentials are exposed.
  • Use the smallest-scoped credential that lets the agent complete its task.
  • Avoid pasting secret values into instructions, playbooks, or memory.
  • Remove secrets that are no longer used by any tool.