Orchestration Secrets
An orchestration secret is defined once on the orchestration and injected as an environment variable into every member agent's sandbox at runtime, alongside that agent's own secrets. Use one when several agents in the same process need the same credential — a GITHUB_TOKEN, a shared API key — instead of pasting it into each agent.
- 01Open the orchestration's Secrets page.
- 02Click Add secret.
- 03Enter an uppercase key and the secret value.
- 04Save your changes. The value is hidden from then on; only the key name is shown.
How inheritance works
- Every member inherits: Each agent in the orchestration receives the orchestration's secrets in its sandbox environment, on top of its own.
- Read the normal way: The agent reads them through the usual environment-variable interface for its runtime, such as
process.env.GITHUB_TOKEN. - Write-only values: After a value is saved, no page, API response, or CLI command returns it again. Only key names come back.
- Encrypted at rest: Orchestration secrets are stored encrypted at rest.
Key names and access
| Rule | Detail |
|---|---|
| Key format | Uppercase, starting with a letter: ^[A-Z][A-Z0-9_]*$. GITHUB_TOKEN is valid, github-token is not. |
| Reserved names | The platform's own provisioning keys (for example BRAINBASE_TOKEN, BB_TASK_KEY, MEDIA_API_KEY) are rejected, so an orchestration secret cannot shadow them. |
| Who can write | A credential that can publish — a bbpat_ personal access token with the publish scope, an OAuth-connected MCP client, or a signed-in session — plus membership in the orchestration's group. A credential scoped to a single agent or task, such as one planted inside a running sandbox, is always refused, even with publish. |
Overrides and conflicts
An agent's own secret always wins. If an agent defines a key with the same name as one of its orchestration's, the agent's value is the one injected. The agent's Secrets page lists inherited keys with the orchestration they come from and an Override action, which writes an agent-level value of that name. brainbase agent status also lists inherited keys by name, flags a conflicting key, and marks an overridden one inline.
brainbase agent status — shows the conflict until you set an agent-level value for that key.When changes take effect
- Adding or rotating a secret: Applies the next time the member starts up in a fresh sandbox. Work already running keeps the environment it started with.
- Removing a secret: The key stops being injected the next time the member starts up in a fresh sandbox.
- Removing an agent from the orchestration: The agent loses access to the inherited keys the next time it starts up in a fresh sandbox.
Local runs
Inherited secrets are a cloud-runtime feature. brainbase agent pull writes only the agent's own secrets to .brainbase/secrets.env, so inherited keys are not in that file and are not available to a local brainbase run — set them yourself in your local environment when you need them. brainbase agent push replaces the agent's own secrets from that file; it never touches the orchestration's.