Deploying
How code in broods/ reaches a stage, how secrets get there, and how to run it from CI.
Development and production
| Command | Target | Pushes .env.local values | Watches |
|---|---|---|---|
broods dev | BROODS_STAGE, default development | yes | yes, plus live logs |
broods dev --once | same | yes | no |
broods deploy | production, or stages.deploy | no | no |
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 devandenv syncpush both kinds. env rmrefuses while a synced agent or sandbox still reads the variable.- To rotate a secret,
env setit again. Do not remove it first. broods devpushes referenced values from.env.localon every sync.broods deploydoes not, so a stale local value never reaches production by accident. Useenv setorenv sync --stage production.env synconly 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.
- 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.