Skip to main content

Deploying

How code in broods/ reaches a stage, how secrets get there, and how to run it from CI.

Development and production​

CommandTargetPushes .env.local valuesWatches
broods devBROODS_STAGE, default developmentyesyes, plus live logs
broods dev --oncesameyesno
broods deployproduction, or stages.deploynono

Both commands compile broods/, validate it, sync it, regenerate broods/_generated/, and write the runtime key to .env.local as BROODS_API_KEY. When the stage has no user token signing secret yet they also mint one and write it as BROODS_USER_TOKEN_SECRET; a stage that already has one keeps it, and the CLI warns when this checkout does not hold it (details). In CI (CI set) deploy writes neither. A broken config fails before anything is written.

deploy ignores BROODS_STAGE. After broods stage use staging, broods deploy still writes to production, or to the stage defineBroods({ stages: { deploy } }) names. Pass --stage staging to deploy elsewhere.

Preview first with broods diff. It compares your code with the stage, including environment variables that differ from .env.local.

Removing resources​

When the stage holds resources your code no longer declares, broods dev lists them and asks about each one. It deletes only those you answer yes to. A no is remembered for the session, so it does not ask again and keeps that resource. broods deploy never deletes unless you pass --prune. A prune fails if a policy it would remove is still used by an agent or channel record. It only removes skills, hooks and MCP servers this stage created, and cron jobs code declared, never ones an agent scheduled at runtime, and only once the deploy is accepted.

Stored source​

Every broods dev and broods deploy also stores the stage's source: the text files in broods/ plus package.json and bun.lock. Dot files (.env, .env.local), _generated/, node_modules/ and links are never sent. With or without GitHub, the stage keeps its newest source and the 19 before it, which is what the dashboard's agent edits and what a revert goes back to. A source over 400 files or 2 MB still deploys, with a warning, and the stage keeps its previous source.

The sync answers manifestHash, a hash of the stage's manifest as broods diff compares it. It changes only when the diff would show something, so a second deploy of the same code answers the same hash.

Stages​

broods stage list
broods stage create staging --from development # copies agents, MCP servers, canvas and env vars
broods stage use staging # sets BROODS_STAGE and refreshes BROODS_API_KEY
broods dev # sync your code into it

development and production are reserved names. Other stage names must be lowercase letters, digits and dashes, such as staging or qa-2, because they appear in URLs.

Cloning copies secret values. Removing a secret later means removing it from both stages.

Secrets and environment variables​

Reference secrets with env("NAME"). The stage stores the value encrypted and the server resolves it at run time.

provider: { openai: { apiKey: env("OPENAI_API_KEY") } },

Never use process.env.OPENAI_API_KEY in broods/. That bakes your local value into the synced config.

broods env set OPENAI_API_KEY # prompts for the value
echo "$VALUE" | broods env set OPENAI_API_KEY # or pipe it
broods env list # names only
broods env get OPENAI_API_KEY # reveals the value, audited
broods env rm OPENAI_API_KEY
broods env sync # push every referenced env("NAME") from .env.local
  • Names are uppercase letters, digits and _, start with a letter, and are at most 64 characters, the same as account env vars.
  • Every env("NAME"), and every ${NAME} in an MCP server header, must have a value on the stage, or the sync fails and names the missing variables. broods dev and env sync push both kinds.
  • env rm refuses while a synced agent or sandbox still reads the variable.
  • To rotate a secret, env set it again. Do not remove it first.
  • broods dev pushes referenced values from .env.local on every sync. broods deploy does not, so a stale local value never reaches production by accident. Use env set or env sync --stage production.
  • env sync only touches names your code references, never deletes, and reports names that live only on the stage.

The runtime key​

Each stage has one runtime key, bsk_..., that your app uses to run agents. broods dev and broods deploy write it to .env.local as BROODS_API_KEY. broods deploy --rotate-key mints a new one and invalidates the old one.

The key only reaches agents in its own stage that set publicAccess: true. It cannot read logs or change config. See Security.

Where a command acts​

Server, organization, project and stage together decide where a command writes. Run broods whoami when in doubt. The full rules, including shell exports winning over .env.local, are in the CLI reference.

Deploying from CI​

On GitHub, link the repo and Broods writes the workflow and secrets for you. For any other CI:

Create a project key (bpdk_...) for the project and stage in the dashboard. It can sync only that stage. It can set and list environment variables but never read them, and it cannot replace skills or hooks another stage manages.

.github/workflows/deploy.yaml
- run: bunx broods deploy
env:
BROODS_TOKEN: ${{ secrets.BROODS_DEPLOY_KEY }}
BROODS_BASE_URL: https://gateway.broods.app
BROODS_PROJECT: my-agents

BROODS_TOKEN holds the project key. With BROODS_BASE_URL it replaces a stored login. Set production secrets with broods env set from a trusted machine, or from CI with an org admin login.

Checking a deployment​

broods agent list # name, public or private, model, deploy status
broods agent get support # model, sandboxes, workspaces, tools, channels, webhooks
broods run support "ping" | cat # one plain-text round trip
broods logs --limit 100 # recent logs, then live

See the CLI reference for every command.