Skip to main content

Configuration reference

Every resource in a Broods project is a define* call exported from a file in broods/. broods dev and broods deploy compile them into a manifest, sync it to a stage, and write typed references to broods/_generated/. This page lists every helper and its fields. The guides explain when to use each one.

Project layout​

my-project/
broods/
index.ts # resource definitions, any number of files
_generated/ # written by broods dev / deploy
api.ts # typed references for the SDK
support-flow/ # a skill bundle
SKILL.md
.env.local # local secrets and CLI settings, never commit

defineBroods​

Optional project defaults, exported as the default export. CLI flags and .env.local override them.

FieldDescription
projectProject name
stages{ dev, deploy } stage names for broods dev and broods deploy
dashboardUrlWhere broods login opens the browser and deep links point
baseUrlBroods API base URL. Defaults to the one discovered at login
import { defineBroods } from "broods";

export default defineBroods({
project: "my-project",
stages: { dev: "development", deploy: "production" },
});

env​

env("NAME") is a reference to a stage environment variable that the server resolves. Use it for every secret. Never use process.env in resource files, because it bakes your local value into the deployed config.

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

Names are uppercase letters, digits and underscores. A sync fails, and writes nothing, when a referenced name has no value on the stage. Set values with broods env set, or let broods dev push them from .env.local. In a plain string, such as an MCP header, write "Bearer ${NAME}" instead. env() returns an object, so a template literal around it sends [object Object].

defineAgent​

The agent's model, instructions, tools, and what it can reach. See Agents.

FieldDescription
nameUnique per stage. Required
descriptionShown to parent agents choosing a subagent
providerCredentials per model provider. See providers
modelprovider, modelId, call settings, reasoning, providerOptions, output
transcriptionSpeech-to-text for inbound audio: provider and modelId, both optional. See voice transcription
agentsystem prompt and maxTurn, the steps per turn. Default 30, 0 for no cap
harnessA defineHarness() value to replace the built-in loop
toolsProvider-executed tools, keyed by the provider's tool name
mcpMCP servers to enable, keyed by server name
connectionsChannel connections the agent answers on
sandboxesSandboxes it can use. The first is the default
workspacesWorkspaces it mounts, with optional per-workspace sandbox
subagentenabled, allowed, context, mode, stream, visibility, model
skillsenabled, allowed skill resources
scheduler{ enabled: true } gives the agent scheduling tools
browser{ enabled: true } gives the agent browse. The first sandbox is a lambda sandbox with image: "obscura" and allow-all, or a machine sandbox with obscura installed
sessionpruning.enabled, autoCompaction.enabled, autoCompaction.maxContextLength
hooksCode hook callbacks and webhooks for lifecycle events
policiesPolicies that gate the agent. Each carries its own mode
publicAccessOpen the agent to the runtime key. Default false
allowRunOverridesLet runtime-key callers send system and model overrides. Default false
import { defineAgent, env } from "broods";

export const myAgent = defineAgent({
name: "my-agent",
provider: { openai: { apiKey: env("OPENAI_API_KEY") } },
model: { provider: "openai", modelId: "gpt-5.5", reasoning: "medium" },
agent: { system: "You are a helpful assistant.", maxTurn: 20 },
sandboxes: [lambdaSandbox],
workspaces: [notes, { workspace: docs, sandbox: null }],
publicAccess: true,
});

model​

FieldDescription
provider, modelIdWhich model to call
temperature, topP, topK, presencePenalty, frequencyPenalty, maxOutputTokens, seed, stopSequencesAI SDK call settings
timeoutAI SDK timeout: milliseconds, or totalMs, stepMs, firstChunkMs, chunkMs, toolMs, tools. See Timeouts
maxRetriesAI SDK retries, default 5. A 429 waits as long as the provider asks, read from its headers or its error text, up to about 60s per retry
reasoningprovider-default, none, minimal, low, medium, high, xhigh
providerOptionsProvider-specific options. They win over reasoning when both set thinking. Refused with config.harness
outputStructured output as { type: "object", schema }, array, choice, json or text, with optional name and description

The provider-specific thinking keys are OpenAI providerOptions.openai.reasoningEffort, Anthropic providerOptions.anthropic.thinking, Google providerOptions.google.thinkingConfig, MiniMax providerOptions.anthropic.thinking. When a model does not support a level, the run logs a model.step.warnings event.

model: {
provider: "google",
modelId: "gemini-3-flash",
output: {
type: "object",
name: "analysis",
schema: {
type: "object",
properties: { summary: { type: "string" }, confidence: { type: "number" } },
required: ["summary", "confidence"],
},
},
},

Model providers​

Every Vercel AI SDK language model provider works, plus any OpenAI-compatible endpoint through custom. Each needs an apiKey, and other settings pass through to the provider's AI SDK factory. chatgpt is the exception: it runs on the account's chatgpt connection and takes no settings. The provider keys and the bedrock, vertex, custom and chatgpt specifics are in Agents. When a custom server reports no reasoning token count, Broods estimates it.

tools and mcp​

tools holds provider-executed tools, imported from the provider's AI SDK package. Broods flags sit beside them.

FlagDescription
enabledfalse disables the tool
needsApprovalAsk before each call. Refused on channel turns
asyncRun a slow local tool in the background

mcp enables registered MCP servers by name. Each entry takes enabled, needsApproval for every tool of that server, and the headers and oauth secrets to resolve.

import { google } from "@ai-sdk/google";

tools: {
googleSearch: google.tools.googleSearch({ searchTypes: { webSearch: {} } }),
urlContext: { ...google.tools.urlContext({}), needsApproval: true },
},
mcp: { [search.name]: { enabled: true } },

See Tools.

workspaces and sandboxes​

sandboxes lists sandbox resources. The first runs bash when no workspace is attached, backs every workspace without its own sandbox, and hosts a harness. The model reaches the others by name. Each sandbox may appear once, and only the first may also back a workspace.

workspaces entries are a workspace resource, or { workspace, sandbox }:

sandbox valueResult
omittedUses the agent's first sandbox. Read-only if there is none
a sandboxUses that sandbox and its permissionMode
nullRead-only, read straight from storage with no compute

subagent​

FieldDefaultDescription
enabledfalseGives the agent run_subagent
allowed[]Agents it may dispatch. Empty means one-shot virtual subagents only
context"new""inherited" passes the parent's messages to the child
mode"persistent""ephemeral" keeps child conversations in memory only
streamfalsePublish child stream parts for WebSocket attach
visibility"result"What the parent sees, full, result or none
modelparent'sModel for virtual subagents, merged over the parent's model

See Subagents.

hooks​

The code hooks are onStart, onStepFinish, onToolCall, onToolResult, onFinish, onApproval, onError, onSubagentFinish, onMessageReceived, onMessageSending. hooks.webhooks is a list of { enabled, url, secret, events }. See Code hooks and Lifecycle webhooks.

defineHarness​

Replaces the built-in agent loop with Claude Code, Codex, Deep Agents, OpenCode or Pi, running on the agent's first sandbox. Omit harness to use the built-in loop.

FieldDescription
typeclaude-code, codex, deepagents, opencode, pi. Required
permissionModeallow-reads, allow-edits, allow-all. Codex needs allow-all
activeToolsOnly these adapter built-ins and MCP tools
inactiveToolsHide these adapter built-ins and MCP tools
startupTimeoutMsHow long to wait for the harness to start
webSearchCodex only
debug{ enabled, level, subsystems } for adapter debug logs. level is error, warn, info, debug or trace
HarnessModel providersTool approvalTool filtering
Claude Codeanthropic, vercelyesyes
Codexcustom, openai, vercelnono
Deep Agentsanthropic, vercelyesauto-rejection
OpenCodeanthropic, openai, vercelyesauto-rejection
Piits own catalog, keys from the configured provideryesyes
  • The first sandbox must be persistent and use the sandbox or lambda provider.
  • Every harness gets the agent's MCP servers and skills. The adapter's own question tool is off. Agents ask through ask_questions.
  • Policies and structured output are not supported yet.
  • The <workspace> prompt is dropped, since the adapter ships its own file tools. Structured memory still applies.
  • Steering sent before a turn starts is folded into its prompt. Steering sent during a turn runs as the next turn.
  • Codex is the only harness with webSearch. Broods checkpoints the harness's native session after each turn, so the next request continues it.
import { defineAgent, defineHarness, defineSandbox, env } from "broods";

export const runner = defineSandbox({
name: "codex-runner",
provider: "sandbox",
persistent: true,
network: { mode: "allow-all" },
onCreate: ["bun install"],
});

export const codingAgent = defineAgent({
name: "coding-agent",
harness: defineHarness({ type: "codex", permissionMode: "allow-all" }),
sandboxes: [runner],
provider: { openai: { apiKey: env("OPENAI_API_KEY") } },
model: { provider: "openai", modelId: "gpt-5.5" },
});

defineSandbox​

Compute where bash and the file tools run. See Sandboxes.

FieldDefaultDescription
providerrequiredsandbox, lambda, daytona, e2b, vercel, cloudflare, worker, machine, custom
permissionModeaskask, edit or bypass
networkdeny-all{ mode, allowDomains?, allowCidrs? }, mode allow-all, deny-all or restricted
timeout30Seconds per call, max 600, or 60 on worker
sizeprovidertiny, xsmall, small, medium, large
imagelambda only: obscura or browser platform image variant. With snapshot, the variant it was built from. Not with fallbackProvider
snapshotproviderImage or snapshot to boot from, in the provider's format. See Images
persistentfalseKeep one long-lived machine per workspace or agent
lifecycleidleTimeoutSeconds, default 900, and maxLifetimeSeconds
onCreate, onResumeSetup commands. Persistent sandboxes only
fallbackProviderSecond provider when the first is out of capacity. Ephemeral only
envVarsVariables for every run. Values may be env("NAME")
runtimesAdvisory allow-list of bash, python, node
outputLimitBytes65536Output kept per call
optionsProvider settings, plus reservationKey to share a persistent machine. On lambda, cloudflare and worker, only workspaceRoot and reservationKey

custom runs bash on your own server through one HTTP contract, named by options.endpoint; what it accepts and refuses is on Your own server.

export const lambdaSandbox = defineSandbox({
name: "lambda-sandbox",
provider: "lambda",
network: { mode: "deny-all" },
permissionMode: "ask",
timeout: 60,
});

defineWorkspace​

Persistent files, mounted into a sandbox. See Workspaces.

FieldDefaultDescription
storage{ provider: "s3" }Managed bucket, your own with bucket, region, prefix, endpoint, auth, or { provider: "disk" } on a persistent worker sandbox. See Disk workspaces
partitioned"conversation" lets channels split the workspace per conversation, "agent" gives each agent its own
harnessworkspace.enabled for the workspace prompt, memory.enabled for structured memory. Both on by default
export const notes = defineWorkspace({
name: "notes",
storage: { provider: "s3" },
});

defineSkill​

An instruction bundle the agent loads when needed. path is a folder under broods/ with a SKILL.md. See Skills.

export const supportFlow = defineSkill({
name: "support-flow",
path: "support-flow",
});

export const myAgent = defineAgent({
name: "my-agent",
skills: { enabled: true, allowed: [supportFlow] },
});

defineMcp​

An MCP server whose tools the agent sees as <name>__<tool>. Give exactly one of url, handler or sandbox. See Tools.

FieldDescription
name1 to 32 lowercase letters, digits or hyphens, starting with a letter
urlExternal server over stateless HTTP. Public host, no redirects
handlerHosted server built with createMcpHandler from @modelcontextprotocol/server, bundled by the CLI
sandboxA machine sandbox whose daemon runs the stdio server of the same name, or a persistent lambda sandbox
commandArgv of the stdio server, such as ["obscura", "mcp"]. Required on a lambda sandbox
headersRequest headers. A credential header must be a ${NAME} ref, optionally after a scheme: "Bearer ${NAME}", "${NAME}"
oauth{ clientId, clientSecret, refreshToken, tokenUrl? } for expiring tokens. No Authorization header alongside
allowedToolsTools to register. Omit for all
runtimehandler only. "auto" (default) runs it on Cloudflare Workers when it builds for them; "lambda" never. See Where a hosted server runs
export const search = defineMcp({
name: "search",
url: "https://mcp.example.com/mcp",
headers: { Authorization: "Bearer ${SEARCH_TOKEN}" },
});

definePolicy​

Authorization rules for agents, attached through policies on an agent or channel. See Policies.

FieldDescription
modeenforce blocks denied actions and fails closed. audit, the default, only logs
rules{ id, effect: "allow" | "deny", actions, resources?, conditions? }
  • Actions are agent.invoke, tool.call, workspace.read, workspace.write, workspace.exec, subagent.run, skill.load.
  • Resource selectors are toolNames, mcpIds, workspaceIds, workspaceNames, filePaths, subagentIds, skillPaths.
  • Conditions are { attribute, operator, value }, with operators equals, notEquals, in, notIn, prefix, contains. Attributes include project, stage, agentId, channel, channelId, userId, userRoles, toolName, mcpId, filePath, sandboxPermissionMode, and tool input as tool.input.<field>.
  • A deny beats an allow. In enforce mode, anything without a matching allow is denied.
  • A filePaths entry is a workspace-relative prefix such as secrets/. A deny on it also blocks a grep or glob rooted above it, including the workspace root.
export const guard = definePolicy({
name: "workspace-guard",
mode: "enforce",
rules: [
{ id: "allow-read", effect: "allow", actions: ["workspace.read"] },
{
id: "deny-secrets",
effect: "deny",
actions: ["workspace.read", "workspace.write"],
resources: { filePaths: ["secrets/"] },
},
],
});

export const myAgent = defineAgent({ name: "my-agent", policies: [guard] });

defineCron​

Runs an agent on a schedule. Give input or events. See Scheduling.

FieldDescription
agentAgent resource or name. Required
scheduleExpressioncron(...), rate(...) or at(...). Required
input / eventsOne text message, or full model messages
timezoneIANA name. Default UTC
conversationKeyConversation to run in. Default cron:<cronId>
statusactive or paused
descriptionFree text
export const dailyDigest = defineCron({
name: "daily-digest",
agent: myAgent,
input: "Summarize today's activity.",
scheduleExpression: "cron(0 9 * * ? *)",
timezone: "Europe/Amsterdam",
});

Connections and channels​

A connection holds one app's credentials. A channel names one room on that connection and the rules for it. Agents list connections in connections.

ProviderConnectionChannelRoom field
TelegramdefineTelegramConnectiondefineTelegramChannelchatId
SlackdefineSlackConnectiondefineSlackChannelchannelId
DiscorddefineDiscordConnectiondefineDiscordChannelchannelId
GitHubdefineGitHubConnectiondefineGitHubChannelrepo
LineardefineLinearConnectiondefineLinearChannelteam
PancakedefinePancakeConnectiondefinePancakeChannelconversationId
ZalodefineZaloConnectiondefineZaloChannelchatId
WhatsAppdefineWhatsAppConnectiondefineWhatsAppChannelwaId
TeamsdefineTeamsConnectiondefineTeamsChannelchannelId
Google ChatdefineGoogleChatConnectiondefineGoogleChatChannelspaceName
TwiliodefineTwilioConnectiondefineTwilioChannelfrom
InstagramdefineInstagramConnectiondefineInstagramChanneligsid
MessengerdefineMessengerConnectiondefineMessengerChannelpsid

Every connection also takes allowedChannelIds, where ["*"] answers everywhere, allowedUserIds, partition and trace. Channels take agents, instructions, workspaces, policies, denyTools, partition, sandboxImages, tagRoles, and replyIn on Slack. Provider fields are on each channel page. The optional teamId, guildId, botId, phoneNumberId and phoneNumber tie a channel to one team, guild, bot or number; without one it applies on all of them.

Validation​

broods dev and broods deploy check the project before anything reaches a stage:

  • Unknown agent keys fail with a suggestion, such as workspace: for workspaces:.
  • Duplicate resource names fail.
  • Every env("NAME") needs a stored value on the stage.
  • Skill folders need a SKILL.md.
  • Hosted MCP bundles must build as ESM and export a fetch-style handler.
  • Workspace storage is s3 (default) or disk.
  • The old sandbox agent key fails. List sandboxes in sandboxes. A stored agent that still carries sandbox refuses to run until you resync.
  • A connection with no declared channels and no allowedChannelIds fails. "*" as a channel id fails.

Generated references​

import { BroodsClient, signUserToken } from "broods";
import { api } from "./broods/_generated/api";

const client = new BroodsClient({
userToken: await signUserToken({ userId: "me" }),
});
await client.run(api.agents.myAgent, { input: "Hello" });

api.agents, api.channels, api.workspaces, api.sandboxes and the other maps hold the deployed ids. See the SDK reference. Every resource also maps to the raw account API, documented in the API reference.