Skip to main content

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​

PathPackageJob
apps/edge@broods/edgeRoute table that generates the Traefik config: path split, per-address limits, CORS
apps/gateway@broods/gatewayAgent, observability, terminal and machine WebSockets
apps/core@broods/coreAgent harness: runs, channel webhooks, crons, tools, sandboxes. Holds sst.config.ts
packages/convex@broods/convexConfig plane, CLI sync, every table, the crons component
apps/dashboard@broods/dashboardNext.js UI on Convex, as a WorkOS user
packages/broodsbroodsPublished CLI and TypeScript SDK
packages/ai-sdk-sandbox@broods/ai-sdk-sandboxAI SDK Harness sandbox adapter: how an external harness runs its shell on a Broods sandbox
apps/discord-forwarder@broods/discord-forwarderOne Discord Gateway socket per bot token, single replica
apps/lambdanone, plain .mjsHosted MCP runner and the sandbox log forwarder
apps/cloudflare-mcp@broods/cloudflare-mcpHosted MCP runtime on Workers, same contract as the Lambda runner
apps/cloudflare-sandbox@broods/cloudflare-sandboxBridge Worker behind the cloudflare sandbox provider
apps/cloudflare-worker@broods/cloudflare-workerWorker behind the worker sandbox provider: bash in a V8 isolate, files in R2
apps/docs@broods/docsThis site and docs/api-reference/openapi.yaml
packages/demosnot a workspaceRunnable demos against a deployed core
verificationnot a workspaceLean 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​

WhereWhat runs thereShipped by
Hetzner k3sTraefik, core, gateway, dashboard, discord-forwarder, OPA, Convex, NATS, observabilityImage build, then rollout.yaml into ../infra Helm
Convex backendsSchema and functions, prod and devdeploy-convex.yaml on push to main or dev
AWS, per SST stageBuckets, mcp-runner, MicroVM roles and log forwarder, sandbox VPC, IAMdeploy.yaml, sst deploy
CloudflareHosted MCP Worker per stage, production includeddeploy.yaml, sst deploy runs wrangler
CloudflareSandbox bridge Worker per stage and its Container imagedeploy.yaml, sst deploy runs wrangler
CloudflareV8 Worker sandbox per stage and its R2 bucketdeploy.yaml, sst deploy runs wrangler
S3 + CloudFrontThis docs sitedeploy-docs.yaml
  • Dev and production share the cluster as separate releases (core-dev next to core). 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_URL and CLOUDFLARE_MCP_API_KEY; other bundles stay on Lambda.
  • MicroVM images are built by ../lambda-sanbdox CI, 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 touchingRead
Request paths, run lifecycle, stateArchitecture
Anything that admits a messageQueue and steer
A chat platformChannels
Tools, MCP, hooksTools and MCP, subagents
Compute and filesSandboxes, storage
Credentials, encryption, untrusted codeSecurity
Logs, traces, metricsObservability
Deploying or running itSelf-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 install at the root. Scripts live in each package.json.
  • Before calling a change done: the workspace's bun run check (types, plus lint for the dashboard) and the root bun run format (oxfmt). Never raw tsc.
  • Lint is oxlint, one .oxlintrc.json at the root. Root bun run check runs the type-aware bun run lint:types, and any lint error fails CI.
  • Convex schema or function change: bun run --filter @broods/convex codegen and commit the generated diff.
  • End to end without cloud: bun run local:up, then bun 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 in packages/broods and the focused tests together.

Extending Broods​

Add a chat command​

Core handles chat commands such as /new, /compact and /queue before the agent sees the message.

  1. Add an entry to commands in apps/core/src/shared/commands.ts with aliases, a description and an execute that returns the reply text. Optional: discord.names, the Discord slash command names that run it.
  2. Use only the channel-agnostic ChannelActions interface. No channel-specific imports.
  3. A command that touches history must hold the conversation lease. /new takes it and is refused while busy. /compact sets queued: true, so the drain loop runs it under the lease after the current turn. See queue and steer.