Internals overview
For people who work on Broods itself: contributors, self-hosters and operators. Building agents on Broods? Start at the user docs.
What is in the repo
One Bun workspaces monorepo, one product. Traefik is the door, the gateway owns the sockets, core owns runtime truth, Convex owns config and persistence, and the dashboard and CLI are two clients of the same config plane.
Service architecture
| Path | Package | Job |
|---|---|---|
apps/edge | @broods/edge | Route table that generates the Traefik config: path split, per-address limits, CORS |
apps/gateway | @broods/gateway | Agent, observability, terminal and machine WebSockets |
apps/core | @broods/core | Agent harness: runs, channel webhooks, crons, tools, sandboxes. Holds sst.config.ts |
packages/convex | @broods/convex | Config plane, CLI sync, every table, the crons component |
apps/dashboard | @broods/dashboard | Next.js UI on Convex, as a WorkOS user |
packages/broods | broods | Published CLI and TypeScript SDK |
packages/ai-sdk-sandbox | @broods/ai-sdk-sandbox | AI SDK Harness sandbox adapter: how an external harness runs its shell on a Broods sandbox |
apps/discord-forwarder | @broods/discord-forwarder | One Discord Gateway socket per bot token, single replica |
apps/lambda | none, plain .mjs | Hosted MCP runner and the sandbox log forwarder |
apps/cloudflare-mcp | @broods/cloudflare-mcp | Hosted MCP runtime on Workers, same contract as the Lambda runner |
apps/cloudflare-sandbox | @broods/cloudflare-sandbox | Bridge Worker behind the cloudflare sandbox provider |
apps/cloudflare-worker | @broods/cloudflare-worker | Worker behind the worker sandbox provider: bash in a V8 isolate, files in R2 |
apps/docs | @broods/docs | This site and docs/api-reference/openapi.yaml |
packages/demos | not a workspace | Runnable demos against a deployed core |
verification | not a workspace | Lean 4 models of routing, the run lifecycle and CLI sync |
Sibling repos next to the checkout: ../infra (k8s cluster and VMs, keep sst.config.ts naming aligned with it) and ../lambda-sanbdox (the Rust server in the MicroVM image behind the lambda provider).
Deployment
| Where | What runs there | Shipped by |
|---|---|---|
| Hetzner k3s | Traefik, core, gateway, dashboard, discord-forwarder, OPA, Convex, NATS, observability | Image build, then rollout.yaml into ../infra Helm |
| Convex backends | Schema and functions, prod and dev | deploy-convex.yaml on push to main or dev |
| AWS, per SST stage | Buckets, mcp-runner, MicroVM roles and log forwarder, sandbox VPC, IAM | deploy.yaml, sst deploy |
| Cloudflare | Hosted MCP Worker per stage, production included | deploy.yaml, sst deploy runs wrangler |
| Cloudflare | Sandbox bridge Worker per stage and its Container image | deploy.yaml, sst deploy runs wrangler |
| Cloudflare | V8 Worker sandbox per stage and its R2 bucket | deploy.yaml, sst deploy runs wrangler |
| S3 + CloudFront | This docs site | deploy-docs.yaml |
- Dev and production share the cluster as separate releases (
core-devnext tocore). The discord-forwarder is one release for both planes, because one bot token holds one socket. - Every stage, production included, gets the hosted MCP Workers runtime. Core sends a Workers-safe bundle there once infra sets that stage's
CLOUDFLARE_MCP_URLandCLOUDFLARE_MCP_API_KEY; other bundles stay on Lambda. - MicroVM images are built by
../lambda-sanbdoxCI, not SST.
Pods, namespaces and replicas: Operations. How a commit reaches each box: CI/CD. Running the same shape yourself: self-hosting.
Where to start reading
| You are touching | Read |
|---|---|
| Request paths, run lifecycle, state | Architecture |
| Anything that admits a message | Queue and steer |
| A chat platform | Channels |
| Tools, MCP, hooks | Tools and MCP, subagents |
| Compute and files | Sandboxes, storage |
| Credentials, encryption, untrusted code | Security |
| Logs, traces, metrics | Observability |
| Deploying or running it | Self-hosting, operations, CI/CD |
Each workspace has its own AGENTS.md with the gotchas for that folder. Read it before changing that workspace.
Contributor workflow
bun installat the root. Scripts live in eachpackage.json.- Before calling a change done: the workspace's
bun run check(types, plus lint for the dashboard) and the rootbun run format(oxfmt). Never rawtsc. - Lint is oxlint, one
.oxlintrc.jsonat the root. Rootbun run checkruns the type-awarebun run lint:types, and any lint error fails CI. - Convex schema or function change:
bun run --filter @broods/convex codegenand commit the generated diff. - End to end without cloud:
bun run local:up, thenbun run local:verify. - React is pinned per app package, never at the root.
- Breaking storage change: no compat shim. Reset and recreate the affected accounts or resources.
- A public contract change moves
openapi.yaml, the docs,packages/demos, the SDK inpackages/broodsand the focused tests together.
Extending Broods
- Built-in tool: tools and MCP. Most integrations should be an MCP server instead.
- Channel: channels.
Add a chat command
Core handles chat commands such as /new, /compact and /queue before the agent sees the message.
- Add an entry to
commandsinapps/core/src/shared/commands.tswithaliases, adescriptionand anexecutethat returns the reply text. Optional:discord.names, the Discord slash command names that run it. - Use only the channel-agnostic
ChannelActionsinterface. No channel-specific imports. - A command that touches history must hold the conversation lease.
/newtakes it and is refused while busy./compactsetsqueued: true, so the drain loop runs it under the lease after the current turn. See queue and steer.