Skip to main content

Concepts

Every other page assumes the ideas on this one. Read it once after the Quickstart.

Where things live​

LevelWhat it isManaged with
OrganizationYour 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
ProjectOne product or repo. Groups its stages.broods dev creates it, broods project
StageA 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/.

ResourceHelperWhat it doesGuide
AgentdefineAgentA model, a prompt, and everything the model may useAgents
SandboxdefineSandboxA Linux machine where the agent runs bash, Python and NodeSandboxes
WorkspacedefineWorkspacePersistent files and memory, mounted into a sandboxWorkspaces
MCP serverdefineMcpExternal tools the agent can callTools
SkilldefineSkillInstructions and scripts the agent loads only when neededSkills
ConnectiondefineSlackConnection, ...Credentials for one chat app installChannels
ChanneldefineSlackChannel, ...One room where the agent answers, with its own rulesChannel records
PolicydefinePolicyRules for which tools, files and subagents the agent may usePolicies
Cron jobdefineCronA scheduled runScheduling

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 permissionMode or the tool's needsApproval.

Credentials​

Use the narrowest credential that works. The three you meet first:

CredentialPrefixWho holds itWhat it can do
Runtime keybsk_Your app or frontendRun agents with publicAccess: true in its own stage. Nothing else.
Account keybask_Your backend, kept secretThe whole config plane, to create agents, crons and files at runtime
CLI loginbcli_broods login on your machineEverything 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. BroodsClient calls it with the runtime key.
  • The config plane manages resources through /v1/agents, /v1/crons, /v1/workspaces and the rest. broods dev calls it. So does BroodsAccountClient when 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.