Concepts
Every other page assumes the ideas on this one. Read it once after the Quickstart.
Where things live
| Level | What it is | Managed with |
|---|---|---|
| Organization | Your team. Members read, admins and owners change things. It runs on its owner's plan: one Pro covers all their orgs. Has the account key. | Dashboard, broods org |
| Project | One product or repo. Groups its stages. | broods dev creates it, broods project |
| Stage | A deploy target inside a project, such as development or production. Each has its own resources, environment variables and runtime key. | broods stage, --stage |
broods dev syncs to development. broods deploy syncs to production, or to the stages.deploy stage you set with defineBroods. Clone a stage with broods stage create staging --from development. See Deploying.
Resources
You declare resources in a broods/ folder with define* helpers. The CLI compiles them, syncs them to a stage, and generates typed references in broods/_generated/.
| Resource | Helper | What it does | Guide |
|---|---|---|---|
| Agent | defineAgent | A model, a prompt, and everything the model may use | Agents |
| Sandbox | defineSandbox | A Linux machine where the agent runs bash, Python and Node | Sandboxes |
| Workspace | defineWorkspace | Persistent files and memory, mounted into a sandbox | Workspaces |
| MCP server | defineMcp | External tools the agent can call | Tools |
| Skill | defineSkill | Instructions and scripts the agent loads only when needed | Skills |
| Connection | defineSlackConnection, ... | Credentials for one chat app install | Channels |
| Channel | defineSlackChannel, ... | One room where the agent answers, with its own rules | Channel records |
| Policy | definePolicy | Rules for which tools, files and subagents the agent may use | Policies |
| Cron job | defineCron | A scheduled run | Scheduling |
Secrets never go in these files. env("NAME") is a reference that the server resolves from the stage's encrypted environment variables. See Deploying.
A run
Every request to an agent is a run on a conversation.
- A conversation is identified by a
conversationKey. Runs on the same key share history. Channels derive the key from the chat or thread, so each Slack thread is its own conversation. - A run streams back over SSE or WebSocket, or runs in the background and you poll it.
- One conversation runs one turn at a time. A message sent while it is busy steers the running turn by default. See Conversations.
- Each model step can call tools. Some tools need approval first, depending on the sandbox
permissionModeor the tool'sneedsApproval.
Credentials
Use the narrowest credential that works. The three you meet first:
| Credential | Prefix | Who holds it | What it can do |
|---|---|---|---|
| Runtime key | bsk_ | Your app or frontend | Run agents with publicAccess: true in its own stage. Nothing else. |
| Account key | bask_ | Your backend, kept secret | The whole config plane, to create agents, crons and files at runtime |
| CLI login | bcli_ | broods login on your machine | Everything the CLI does and the account API, for org owners and admins, except rotating the account key |
broods dev and broods deploy write the runtime key to .env.local as BROODS_API_KEY. The account key is shown once, when your organization is provisioned. Rotate it under Org Settings, API Access. Project keys, scoped account keys, role sessions and stage tickets are in Security.
Config plane and runtime
Two kinds of API sit behind the same URL.
- The runtime runs agents through
POST /v1/runs, the WebSocket and channel webhooks.BroodsClientcalls it with the runtime key. - The config plane manages resources through
/v1/agents,/v1/crons,/v1/workspacesand the rest.broods devcalls it. So doesBroodsAccountClientwhen your app creates an agent per customer at runtime.
The code in broods/ and the config plane describe the same resources. Anything you can declare, you can also create through the API.