Self-hosting
Run Broods on your own AWS account and cluster. Most users should use the managed service at gateway.broods.app instead, see the quickstart; the CLI and SDK work the same against either. To try the stack on one machine first, skip to Run it locally. Day-two work is in operations.
What you deploy
| Piece | Source | Runs as |
|---|---|---|
| AWS data plane | apps/core/sst.config.ts | SST deploy into your AWS account |
| Convex backend | packages/convex | Convex Cloud, or the self-hosted convex-backend image |
| core | apps/core/Dockerfile | Container, port 3000, cluster-internal |
| Traefik | upstream, config from apps/edge | The only public door |
| gateway | apps/gateway/Dockerfile | Container, port 3000, behind Traefik |
| dashboard | apps/dashboard/Dockerfile | Container, port 3000 |
| NATS with JetStream | upstream | For WebSocket runs and live logs |
| OPA | upstream, with apps/core/opa/broods_authz.rego | For agent policies |
| OTel collector, Loki, Tempo | upstream | Optional. Log and trace history |
| discord-forwarder | apps/discord-forwarder/Dockerfile | Optional, one replica. Discord agents only |
| cloudflare-mcp | apps/cloudflare-mcp | Optional Worker. Hosted MCP off Lambda |
| cloudflare-sandbox | apps/cloudflare-sandbox | Optional Worker. The cloudflare sandbox provider |
| cloudflare-worker | apps/cloudflare-worker | Optional Worker. The worker sandbox provider |
Images are published to ghcr.io/beeblastco/broods-{core,gateway,dashboard,discord-forwarder}, or build them from the repo root with docker build -f apps/core/Dockerfile ..
Setup order
Each step needs values from the one before it.
Prerequisites
- Bun at the version in
.bun-version. - An AWS account with credentials that can create S3, IAM, Lambda, EC2 networking and CloudWatch resources.
- A Kubernetes cluster or any container host.
- A Convex deployment, Cloud or self-hosted.
- No identity provider. A self-hosted dashboard signs the admin in with
ADMIN_ACCOUNT_SECRET.
1. Deploy the AWS data plane
bun install --ignore-scripts
cp apps/core/.env.example apps/core/.env # fill it in
cd apps/core
bun run deploy # build, then sst deploy
sst.config.ts reads only these. Runtime secrets are not SST secrets.
| Variable | Required | Notes |
|---|---|---|
AWS_ACCOUNT_ID | yes | Role ARNs, bucket policies, resource names |
PROJECT_NAME | yes | Name prefix <stage>-<project>-<service>-<account>-<region>; production stages drop <stage>- |
PROJECT_OWNER_EMAIL | yes | Resource tags |
AWS_REGION | CI only | Defaults to eu-west-1 locally |
AWS_PROFILE | local | Ignored when CI is set |
SST_STAGE | yes | dev, production-eu-west-1, ... production and production-* are production |
CONVEX_URL | yes | The deploy fails without it |
CONVEX_DEPLOY_KEY | yes | Deploy key, or the self-hosted admin key |
OTEL_EXPORTER_OTLP_ENDPOINT | no | Collector for the sandbox log forwarder. Default https://otel.beeblast.co, so set it |
OTEL_EXPORTER_OTLP_HEADERS | no | Authorization=Basic .... Unset skips the sandbox log forwarder; MicroVM logs stay in CloudWatch |
MCP_TENANT_ISOLATION | no | true creates the hosted MCP Lambda in per-tenant mode. AWS must enable tenancy first; cannot change later |
SANDBOX_IMAGE_READY | no | true imports the existing sandbox ECR repo instead of creating it |
Stack outputs:
| Output | Feeds |
|---|---|
filesystemBucketName | core and Convex FILESYSTEM_BUCKET_NAME |
skillsBucketName | core and Convex SKILLS_BUCKET_NAME |
toolBundlesBucketName | core and Convex TOOL_BUNDLES_BUCKET_NAME |
toolRunnerFunctionName | core TOOL_RUNNER_FUNCTION_NAME |
microvmExecutionRoleArn, microvmEgressNetworkConnectorArn | core MICROVM_EXECUTION_ROLE_ARN, MICROVM_EGRESS_NETWORK_CONNECTOR_ARN |
microvmArtifactsBucketName, microvmBuildRoleArn | Convex MICROVM_ARTIFACTS_BUCKET_NAME, MICROVM_BUILD_ROLE_ARN |
coreRuntimeUserName | aws iam create-access-key --user-name <name>, the key for core |
convexAwsRoleArn | Convex CONVEX_AWS_ROLE_ARN |
convexBootstrapUserName | mint the key for Convex AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY |
cloudflareWorkers | the cloudflare-mcp, sandbox bridge and V8 Worker names, when the deploy had CLOUDFLARE_API_TOKEN |
Fixed names, not outputs: SANDBOX_MOUNT_ROLE_ARN is the role <stage>-<project>-sandbox-s3mount-<account>-<region> (no <stage>- on production), and MICROVM_LOG_GROUP_NAME is /broods/<stage>/microvms. Production stages retain and protect their buckets. Add every long-lived stage to .github/workflows/drift-cleanup.yaml, see CI/CD.
2. Configure and deploy Convex
From packages/convex, set each with bunx convex env set NAME value:
| Variable | Required | Notes |
|---|---|---|
ACCOUNT_CONFIG_ENCRYPTION_SECRET | yes | Same as core. Comma-separated list |
ADMIN_ACCOUNT_SECRET | yes | Same as core |
SERVICE_AUTH_SECRET | yes | Same as core |
STAGE_TICKET_SECRET | yes | Same as core |
ANALYTICS_ID_SECRET | no | Same as core. Keys the dashboard's PostHog user id; unset leaves it anonymous per browser |
BROODS_ACCOUNT_MANAGE_URL | yes | Core's in-cluster URL, such as http://core.<ns>.svc.cluster.local. Never the public host |
AWS_REGION | yes | The data plane region |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY | yes | The bootstrap user's key. It can only assume ConvexAwsRole |
CONVEX_AWS_ROLE_ARN | yes | convexAwsRoleArn output |
CONVEX_AWS_EXTERNAL_ID | no | Default broods-convex |
FILESYSTEM_BUCKET_NAME, SKILLS_BUCKET_NAME, TOOL_BUNDLES_BUCKET_NAME | yes | Stack outputs |
MICROVM_ARTIFACTS_BUCKET_NAME, MICROVM_BUILD_ROLE_ARN | no | Refused as a workspace's own bucket or role |
ALLOW_PRIVATE_STORAGE_ENDPOINTS | no | true accepts a private workspace storage.endpoint, such as MinIO. Set the same on core |
BROODS_AUTH_PROVIDER | yes | self-host for the dashboard's admin session, workos for the managed login |
BROODS_SESSION_JWKS | dashboard | Public half of BROODS_SESSION_SIGNING_KEY, see dashboard |
BROODS_MODEL_PRICES | no | Your token rates for the Usage tab, see model prices |
BROODS_MODEL_PRICES_URL | no | A models.dev-format catalogue to crawl hourly. Unset fetches nothing |
WORKOS_API_KEY, WORKOS_CLIENT_ID, WORKOS_WEBHOOK_SECRET | no | The managed service's login. Leave unset |
CHATGPT_PLAN_ENABLED | no | true lets the managed service offer chatgpt connections. Self-hosted offers them always |
DASHBOARD_ORIGIN | billing | Allowed origin for Stripe return URLs |
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET | no | Billing |
STRIPE_PRO_PRICE_ID | no | Monthly Pro price, with 2 developer seats; Upgrade bills it |
STRIPE_SEAT_PRICE_ID | no | Monthly price of one seat past Pro's 2; Upgrade and Add seat bill it |
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY | GitHub | Your GitHub App, see GitHub App. All six or none |
GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_WEBHOOK_SECRET | GitHub | Same App |
BROODS_AGENT_URL, BROODS_AGENT_ID | no | The agent behind the dashboard's Broods agent dock: its endpoint URL and id. Unset keeps the dock on its built-in planner |
BROODS_AGENT_RUNTIME_KEY, BROODS_AGENT_USER_TOKEN_SECRET | no | That stage's bsk_ key and bsig_ signing secret. The dock asks as the signed-in user, in that user's own conversations |
Then deploy the functions, before core:
cd packages/convex
CONVEX_DEPLOY_KEY=... bun run deploy
# self-hosted backend instead:
CONVEX_SELF_HOSTED_URL=https://convex.example.com CONVEX_SELF_HOSTED_ADMIN_KEY=... bun run deploy
Model prices
The Usage tab prices tokens from rates an hourly cron stores. The managed cloud crawls models.dev; a self-hosted deployment fetches nothing unless you set BROODS_MODEL_PRICES_URL, since most cannot reach the internet. Point it at https://models.dev/api.json if yours can, or at a copy inside your network. A provider the catalogue stops listing keeps its last rates; unsetting the URL clears them.
Set your own rates, such as negotiated prices or a custom endpoint, as JSON in BROODS_MODEL_PRICES: agent provider, then model id, then USD per million tokens for input, output and optionally cacheRead and cacheWrite. They win over the catalogue on that model and its dated snapshots, and a cache rate you leave out is the catalogue's, else your input rate. They are stored before the catalogue is fetched, so an unreachable URL never holds them back.
bunx convex env set BROODS_MODEL_PRICES '{"custom":{"gpt-oss-120b":{"input":0.1,"output":0.5}},"anthropic":{"claude-sonnet-5-5":{"input":1.8,"output":9}}}'
A malformed value fails the crawl with the reason in the Convex logs. Removing a rate from the variable removes it on the next crawl.
GitHub App
Repo links (GitHub) need a GitHub App of your own. Without one the dashboard hides the GitHub starts. Register it under your GitHub organization's Developer settings:
| Setting | Value |
|---|---|
| Callback URL | {dashboard}/github/callback |
| Request user authorization (OAuth) during installation | on |
| Webhook URL | {CONVEX_SITE_URL}/github/webhook |
| Repository permissions | Administration, Contents, Environments, Pull requests, Secrets, Workflows: read and write. Actions, Metadata: read |
| Organization permissions | Members: read, so Broods connects only orgs the user is an admin of |
| Subscribe to events | Workflow run, Repository |
The App receives installation events without a subscription. Generate a private key and a client secret, then set the six GITHUB_APP_* variables. GITHUB_APP_PRIVATE_KEY takes the PEM as GitHub hands it, newlines escaped as \n or not. GITHUB_API_URL and GITHUB_WEB_URL point at GitHub Enterprise Server instead of github.com. The code is in packages/convex/github.ts.
3. Shared services
| Service | Needed for | Notes |
|---|---|---|
| NATS with JetStream | WebSocket runs, live logs | Core creates WS_RESPONSES_<env> and OBSERVABILITY_<env> on first use, <env> being DEPLOYMENT_ENVIRONMENT, so stages can share one server. nats:// or tls:// in-cluster, wss:// or ws:// from outside |
| OPA | agent policies | Load apps/core/opa/broods_authz.rego. Core posts to /v1/data/broods/authz/decision |
| OTel, Loki, Tempo | history, optional | Core exports to OTEL_EXPORTER_OTLP_ENDPOINT; the gateway reads LOKI_URL and TEMPO_URL |
Without the OTel stack the dashboard shows only the live window NATS keeps.
4. Run the containers
Every image listens on port 3000 and answers GET /healthz.
core
Refuses to start without SERVICE_AUTH_SECRET, STAGE_TICKET_SECRET, TERMINAL_TICKET_SECRET and MEDIA_TICKET_SECRET. Keep it cluster-internal and at one replica.
| Variable | Required | Notes |
|---|---|---|
CONVEX_URL, CONVEX_DEPLOY_KEY | yes | Deploy key or self-hosted admin key |
ACCOUNT_CONFIG_ENCRYPTION_SECRET | yes | Same as Convex. See service secrets |
SERVICE_AUTH_SECRET, STAGE_TICKET_SECRET | yes | Same as Convex |
TERMINAL_TICKET_SECRET, MEDIA_TICKET_SECRET | yes | Comma-separated lists |
ADMIN_ACCOUNT_SECRET | no | Enables POST /v1/accounts |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION | yes | The core runtime user's key |
FILESYSTEM_BUCKET_NAME, SKILLS_BUCKET_NAME, TOOL_BUNDLES_BUCKET_NAME, TOOL_RUNNER_FUNCTION_NAME | yes | Stack outputs |
PUBLIC_BASE_URL | yes | The public host. Sandbox job callbacks and status URLs use it |
WORKOS_AUTHKIT_DOMAIN | no | The AuthKit domain that signs MCP clients in at /mcp. In WorkOS, turn on Client ID Metadata Documents and Dynamic Client Registration, and add <PUBLIC_BASE_URL>/mcp as a resource indicator. Unset, /mcp takes keys only |
BROODS_DASHBOARD_URL | no | The dashboard a run's trace link opens. Defaults to https://dashboard.broods.app |
SANDBOX_MOUNT_ROLE_ARN | for mounts | Role assumed for prefix-scoped workspace mount credentials |
MICROVM_IMAGE_IDENTIFIER, MICROVM_EXECUTION_ROLE_ARN, MICROVM_LOG_GROUP_NAME, MICROVM_EGRESS_NETWORK_CONNECTOR_ARN | for lambda sandboxes | Without the connector, deny-all MicroVMs fail to launch |
WORKDIR_URL, WORKDIR_API_KEY | for sandbox | The workdir control plane |
CLOUDFLARE_SANDBOX_URL, CLOUDFLARE_SANDBOX_API_KEY | for cloudflare | See Cloudflare sandbox bridge |
CLOUDFLARE_WORKER_URL, CLOUDFLARE_WORKER_API_KEY | for worker | See Cloudflare V8 Worker |
APPLY_SANDBOX | for the dashboard's Apply | A sandbox config as JSON ({"provider":"lambda","network":{"mode":"allow-all"}}), always run persistent. Apply deploys approved files from it; it needs bun and the network, so not worker. Unset, Apply answers 503 |
CLOUDFLARE_MCP_URL, CLOUDFLARE_MCP_API_KEY | for Cloudflare MCP | See Cloudflare MCP runtime |
DAYTONA_API_KEY, DAYTONA_API_URL, DAYTONA_ORGANIZATION_ID, DAYTONA_TARGET; E2B_API_KEY; VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_ID | no | Fallbacks for sandbox configs that omit their own |
ENABLE_WEBSOCKET, NATS_URL, NATS_TOKEN | for WebSocket | ENABLE_WEBSOCKET=true needs NATS_URL; NATS_URL needs DEPLOYMENT_ENVIRONMENT |
OPA_BASE_URL, OPA_API_TOKEN | for policies | Default http://127.0.0.1:8181 |
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, SERVICE_NAME, DEPLOYMENT_ENVIRONMENT | no | No endpoint means no export |
POSTHOG_API_KEY, POSTHOG_HOST | no | Anonymous PostHog AI traces + Logs. Unset either means no export |
ANALYTICS_ID_SECRET | no | Same as Convex. Keys AI session ids; unset means none |
ENABLE_DIRECT_API | no | Default true. false turns POST /v1/runs off |
ALLOW_PRIVATE_STORAGE_ENDPOINTS | no | Same as on Convex |
Tuning knobs, with defaults: REQUEST_TIMEOUT_BUDGET_MS 600000, WORKER_TIMEOUT_BUDGET_MS 600000, MAX_INPROCESS_WORKERS 8, MODEL_FIRST_CHUNK_TIMEOUT_MS 300000, MODEL_CHUNK_TIMEOUT_MS 300000, SHUTDOWN_DEADLINE_MS 25000, MCP_BATCH_WINDOW_MS, MCP_BATCH_MAX, ISOLATE_POOL, ISOLATE_WORKER_POOL_SIZE 4, ISOLATE_MEMORY_LIMIT_MB, ISOLATE_RUNNER_TIMEOUT_SECONDS, SANDBOX_SWEEP_INTERVAL_SECONDS 3600, and the WORKSPACE_SANDBOX_* limits in apps/core/src/shared/sandbox.ts. What they do is in operations.
Model and tool API keys are never deployment-wide. Accounts set them in agent config or as stage env vars.
Traefik
Generate the file-provider config from the route table: the three upstreams, then the hostnames your dashboard is served from (*. for subdomains; default is the broods.app ones and localhost).
bun run --filter @broods/edge generate file \
http://core:3000 https://your-deployment.convex.site http://gateway:3000 \
agents.example.com localhost > edge.yaml
- Load it with
--providers.file.filename=edge.yamlon an entry point namedweb, with TLS in front. - Set the same hostnames in the gateway's
GATEWAY_ALLOWED_ORIGINS. - Regenerate on every upgrade: a missing route lands on the wrong upstream.
- The file config has no per-address rate limits. The managed ones are the
rateLimitmiddlewares inapps/edge/src/traefik.ts.
gateway
Stateless; scale it with replicas.
| Variable | Required | Notes |
|---|---|---|
BROODS_CORE_URL | yes | Core's URL, for socket token checks, agent runs and the machine relay |
TERMINAL_TICKET_SECRET | yes | Same list as core |
NATS_URL, NATS_TOKEN, DEPLOYMENT_ENVIRONMENT | for WebSocket and logs | Connected on first use. DEPLOYMENT_ENVIRONMENT must equal core's, or no replay ever matches |
LOKI_URL, TEMPO_URL | no | Log and trace history |
GATEWAY_ALLOWED_ORIGINS | no | WebSocket origin allow list. Default broods.app, *.broods.app, localhost, 127.0.0.1 |
GATEWAY_MAX_CONNECTIONS, GATEWAY_MAX_PAYLOAD_BYTES, GATEWAY_BACKPRESSURE_BYTES, GATEWAY_IDLE_TIMEOUT_SECONDS, GATEWAY_RUN_START_TIMEOUT_MS | no | Per-pod limits. See apps/gateway/.env.example |
GATEWAY_AUTH_FAILURES_PER_MINUTE | no | Failed socket logins per client address. Default 20 |
dashboard
| Variable | When | Notes |
|---|---|---|
NEXT_PUBLIC_CONVEX_URL | build time | Your Convex URL |
NEXT_PUBLIC_BROODS_BASE_URL | build time | The public host |
NEXT_PUBLIC_POSTHOG_KEY | build time | PostHog project key. Unset means no analytics, errors or logs |
NEXT_PUBLIC_POSTHOG_HOST | build time | PostHog ingest host or your reverse proxy, e.g. https://eu.i.posthog.com |
NEXT_PUBLIC_POSTHOG_UI_HOST | build time | Behind a proxy, the PostHog app it fronts, e.g. https://eu.posthog.com |
DASHBOARD_ASSET_ORIGIN | build time | CDN origin pulling /_next/static from here, with CORS. Unset serves them here |
ADMIN_ACCOUNT_SECRET | runtime | The admin sign-in key. At least 32 characters or the dashboard refuses to start |
BROODS_SESSION_SIGNING_KEY | runtime | Private ES256 JWK that signs the session |
BROODS_BASE_URL | runtime | The public host broods login hands the CLI. Login fails without it |
Make the key pair once. The first line goes to the dashboard, the second to Convex:
bun -e 'const { privateKey } = require("node:crypto").generateKeyPairSync("ec", { namedCurve: "P-256" }); const jwk = { ...privateKey.export({ format: "jwk" }), alg: "ES256", kid: "broods-self-host", use: "sig" }; const { d, ...pub } = jwk; console.log("BROODS_SESSION_SIGNING_KEY=" + JSON.stringify(jwk)); console.log("BROODS_SESSION_JWKS=" + JSON.stringify({ keys: [pub] }))'
A session lasts 12 hours in an httpOnly cookie; the browser's Convex tokens last 15 minutes. To end every session at once, make a new key pair and set both values. Rotating ADMIN_ACCOUNT_SECRET does not end sessions. See apps/dashboard/.env.example.
Forwarders
Only for Discord agents. One release for every Convex deployment you run, one replica, strategy: Recreate. See operations for why.
| Variable | Notes |
|---|---|
BROODS_CONFIG_PLANES | JSON array of { "name", "convexUrl", "webhookBaseUrl" }. webhookBaseUrl is that plane's public host |
CONVEX_DEPLOY_KEY_<NAME> | One key per plane, upper-cased: plane dev reads CONVEX_DEPLOY_KEY_DEV |
DISCORD_BACKOFF_CEILING_MS | Default 300000 |
DISCORD_IDENTIFY_LIMIT | Default 500, half of Discord's 1000 per 24 hours |
Cloudflare MCP runtime (optional)
Runs hosted MCP servers on Cloudflare Workers instead of the tool-runner Lambda. apps/cloudflare-mcp is one Worker with a LOADER Worker Loader binding, which needs a Workers Paid plan. How it runs a batch is in tools and MCP.
Only a response tagged x-broods-nothing-ran reruns on Lambda; any other error fails the call.
Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID (Workers Paid plan) when you run bun run deploy. It creates the broods-mcp-bundles R2 bucket with a 30-day expiry and ships the Worker as the cloudflareWorkers.mcp output, pointed at your bundle bucket. Then give it a key, from apps/cloudflare-mcp:
bunx wrangler secret put MCP_API_KEY --name <cloudflareWorkers.mcp>
Then set core's CLOUDFLARE_MCP_URL to https://<worker-host>/mcp and CLOUDFLARE_MCP_API_KEY to the same secret. Until both are set, every server runs on Lambda.
Cloudflare sandbox bridge (optional)
Backs the cloudflare sandbox provider. The Container API only answers inside a Durable Object, so core calls apps/cloudflare-sandbox, a Worker where each sandbox id is one Durable Object owning one Container. Details are in sandboxes.
Set CLOUDFLARE_API_TOKEN (a user API token with Containers Edit: the Containers API refuses account API tokens) and CLOUDFLARE_ACCOUNT_ID (Workers Paid plan, for Containers) and have Docker running when you run bun run deploy: the first deploy, and any after a Dockerfile change, builds the image as broods-sandbox:<Dockerfile hash> in your Cloudflare registry; the Worker ships as the cloudflareWorkers.sandbox output. Then give it a key, from apps/cloudflare-sandbox:
bunx wrangler secret put SANDBOX_API_KEY --name <cloudflareWorkers.sandbox>
Then set core's CLOUDFLARE_SANDBOX_URL to the Worker's https:// URL and CLOUDFLARE_SANDBOX_API_KEY to the same secret. Plain http:// is accepted only on loopback, for wrangler dev. This provider cannot mount workspaces.
Cloudflare V8 Worker (optional)
Backs the worker sandbox provider: bash in a V8 isolate, no container, no Docker, nothing running between commands. Core calls apps/cloudflare-worker, a Worker that loads one Dynamic Worker per sandbox id and keeps a reserved sandbox's files in R2. Details are in sandboxes.
Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID (Workers Paid plan, for Dynamic Workers and R2) when you run bun run deploy. It creates the broods-worker-state R2 bucket and ships the Worker as the cloudflareWorkers.worker output. Then give it a key, from apps/cloudflare-worker:
bunx wrangler secret put WORKER_API_KEY --name <cloudflareWorkers.worker>
Then set core's CLOUDFLARE_WORKER_URL to the Worker's https:// URL and CLOUDFLARE_WORKER_API_KEY to the same secret. Plain http:// is accepted only on loopback, for wrangler dev. This provider cannot mount workspaces.
5. Create an account
With the dashboard, sign in with the admin key and the account is provisioned for your organization. Without it:
curl -X POST "$BROODS_BASE_URL/v1/accounts" \
-H "Authorization: Bearer $ADMIN_ACCOUNT_SECRET" \
-H "Content-Type: application/json" \
-d '{ "username": "company-a", "description": "Company A account" }'
The response holds the account secret once. That account belongs to an admin-owned org with no dashboard login; drive it with the account API or BroodsAccountClient.
6. Point the CLI at it
broods login --dashboard-url https://dashboard.example.com
broods dev
login records BROODS_BASE_URL in .env.local, so broods run, broods logs and SDK clients reach the same deployment. A runtime key only works on the deployment that issued it. In CI, set BROODS_TOKEN to a project key and BROODS_BASE_URL.
Webhook URLs
{BROODS_BASE_URL}/v1/webhooks/{accountId}/{channel} # production stages
{BROODS_BASE_URL}/v1/webhooks/{accountId}/dev/{endpointId}/{channel} # other stages
broods dev prints the endpoint id after a sync. The bare URL picks the agent whose credentials verify, so a second stage with the same bot token competes for its traffic. The stage URL reaches only that stage.
Smoke test
curl https://gateway.example.com/healthz
# {"status":"ok"}
bun run --filter broods build
cd packages/demos/basic-stream
echo 'BROODS_BASE_URL=https://gateway.example.com' >> .env.local
bun install && bun run dev && bun run start
basic-async does the same with background: true and polling. packages/demos/README.md lists the rest.
Run it locally
bun run local:up # --fresh wipes the instance first, --dashboard serves the dashboard
bun run local:verify # runs scripts/local-verify/cases through Traefik
bun run local:status # --key prints the admin sign-in key
bun run local:down # --purge deletes the instance state
- State, ports and logs live under
~/.broods-local/<instance>/, one stack per worktree. verifypasses without a model key: the run fails at the provider call, which still proves routing, auth, config encryption and the Convex round trips. SetANTHROPIC_API_KEYfor a full run (Claude Haiku 5.5 at medium effort).- No AWS data plane or NATS, so no sandboxes or WebSocket runs.
The signed-in dashboard suites run against it with no account to set up:
cd apps/dashboard
E2E_ADMIN_KEY=$(bun ../../scripts/local-stack.ts status --key) E2E_BASE_URL=<dashboard URL> bun run test:app