Skip to main content

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​

PieceSourceRuns as
AWS data planeapps/core/sst.config.tsSST deploy into your AWS account
Convex backendpackages/convexConvex Cloud, or the self-hosted convex-backend image
coreapps/core/DockerfileContainer, port 3000, cluster-internal
Traefikupstream, config from apps/edgeThe only public door
gatewayapps/gateway/DockerfileContainer, port 3000, behind Traefik
dashboardapps/dashboard/DockerfileContainer, port 3000
NATS with JetStreamupstreamFor WebSocket runs and live logs
OPAupstream, with apps/core/opa/broods_authz.regoFor agent policies
OTel collector, Loki, TempoupstreamOptional. Log and trace history
discord-forwarderapps/discord-forwarder/DockerfileOptional, one replica. Discord agents only
cloudflare-mcpapps/cloudflare-mcpOptional Worker. Hosted MCP off Lambda
cloudflare-sandboxapps/cloudflare-sandboxOptional Worker. The cloudflare sandbox provider
cloudflare-workerapps/cloudflare-workerOptional 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.

VariableRequiredNotes
AWS_ACCOUNT_IDyesRole ARNs, bucket policies, resource names
PROJECT_NAMEyesName prefix <stage>-<project>-<service>-<account>-<region>; production stages drop <stage>-
PROJECT_OWNER_EMAILyesResource tags
AWS_REGIONCI onlyDefaults to eu-west-1 locally
AWS_PROFILElocalIgnored when CI is set
SST_STAGEyesdev, production-eu-west-1, ... production and production-* are production
CONVEX_URLyesThe deploy fails without it
CONVEX_DEPLOY_KEYyesDeploy key, or the self-hosted admin key
OTEL_EXPORTER_OTLP_ENDPOINTnoCollector for the sandbox log forwarder. Default https://otel.beeblast.co, so set it
OTEL_EXPORTER_OTLP_HEADERSnoAuthorization=Basic .... Unset skips the sandbox log forwarder; MicroVM logs stay in CloudWatch
MCP_TENANT_ISOLATIONnotrue creates the hosted MCP Lambda in per-tenant mode. AWS must enable tenancy first; cannot change later
SANDBOX_IMAGE_READYnotrue imports the existing sandbox ECR repo instead of creating it

Stack outputs:

OutputFeeds
filesystemBucketNamecore and Convex FILESYSTEM_BUCKET_NAME
skillsBucketNamecore and Convex SKILLS_BUCKET_NAME
toolBundlesBucketNamecore and Convex TOOL_BUNDLES_BUCKET_NAME
toolRunnerFunctionNamecore TOOL_RUNNER_FUNCTION_NAME
microvmExecutionRoleArn, microvmEgressNetworkConnectorArncore MICROVM_EXECUTION_ROLE_ARN, MICROVM_EGRESS_NETWORK_CONNECTOR_ARN
microvmArtifactsBucketName, microvmBuildRoleArnConvex MICROVM_ARTIFACTS_BUCKET_NAME, MICROVM_BUILD_ROLE_ARN
coreRuntimeUserNameaws iam create-access-key --user-name <name>, the key for core
convexAwsRoleArnConvex CONVEX_AWS_ROLE_ARN
convexBootstrapUserNamemint the key for Convex AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
cloudflareWorkersthe 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:

VariableRequiredNotes
ACCOUNT_CONFIG_ENCRYPTION_SECRETyesSame as core. Comma-separated list
ADMIN_ACCOUNT_SECRETyesSame as core
SERVICE_AUTH_SECRETyesSame as core
STAGE_TICKET_SECRETyesSame as core
ANALYTICS_ID_SECRETnoSame as core. Keys the dashboard's PostHog user id; unset leaves it anonymous per browser
BROODS_ACCOUNT_MANAGE_URLyesCore's in-cluster URL, such as http://core.<ns>.svc.cluster.local. Never the public host
AWS_REGIONyesThe data plane region
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYyesThe bootstrap user's key. It can only assume ConvexAwsRole
CONVEX_AWS_ROLE_ARNyesconvexAwsRoleArn output
CONVEX_AWS_EXTERNAL_IDnoDefault broods-convex
FILESYSTEM_BUCKET_NAME, SKILLS_BUCKET_NAME, TOOL_BUNDLES_BUCKET_NAMEyesStack outputs
MICROVM_ARTIFACTS_BUCKET_NAME, MICROVM_BUILD_ROLE_ARNnoRefused as a workspace's own bucket or role
ALLOW_PRIVATE_STORAGE_ENDPOINTSnotrue accepts a private workspace storage.endpoint, such as MinIO. Set the same on core
BROODS_AUTH_PROVIDERyesself-host for the dashboard's admin session, workos for the managed login
BROODS_SESSION_JWKSdashboardPublic half of BROODS_SESSION_SIGNING_KEY, see dashboard
BROODS_MODEL_PRICESnoYour token rates for the Usage tab, see model prices
BROODS_MODEL_PRICES_URLnoA models.dev-format catalogue to crawl hourly. Unset fetches nothing
WORKOS_API_KEY, WORKOS_CLIENT_ID, WORKOS_WEBHOOK_SECRETnoThe managed service's login. Leave unset
CHATGPT_PLAN_ENABLEDnotrue lets the managed service offer chatgpt connections. Self-hosted offers them always
DASHBOARD_ORIGINbillingAllowed origin for Stripe return URLs
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRETnoBilling
STRIPE_PRO_PRICE_IDnoMonthly Pro price, with 2 developer seats; Upgrade bills it
STRIPE_SEAT_PRICE_IDnoMonthly price of one seat past Pro's 2; Upgrade and Add seat bill it
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEYGitHubYour GitHub App, see GitHub App. All six or none
GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_WEBHOOK_SECRETGitHubSame App
BROODS_AGENT_URL, BROODS_AGENT_IDnoThe 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_SECRETnoThat 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:

SettingValue
Callback URL{dashboard}/github/callback
Request user authorization (OAuth) during installationon
Webhook URL{CONVEX_SITE_URL}/github/webhook
Repository permissionsAdministration, Contents, Environments, Pull requests, Secrets, Workflows: read and write. Actions, Metadata: read
Organization permissionsMembers: read, so Broods connects only orgs the user is an admin of
Subscribe to eventsWorkflow 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​

ServiceNeeded forNotes
NATS with JetStreamWebSocket runs, live logsCore 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
OPAagent policiesLoad apps/core/opa/broods_authz.rego. Core posts to /v1/data/broods/authz/decision
OTel, Loki, Tempohistory, optionalCore 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.

VariableRequiredNotes
CONVEX_URL, CONVEX_DEPLOY_KEYyesDeploy key or self-hosted admin key
ACCOUNT_CONFIG_ENCRYPTION_SECRETyesSame as Convex. See service secrets
SERVICE_AUTH_SECRET, STAGE_TICKET_SECRETyesSame as Convex
TERMINAL_TICKET_SECRET, MEDIA_TICKET_SECRETyesComma-separated lists
ADMIN_ACCOUNT_SECRETnoEnables POST /v1/accounts
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGIONyesThe core runtime user's key
FILESYSTEM_BUCKET_NAME, SKILLS_BUCKET_NAME, TOOL_BUNDLES_BUCKET_NAME, TOOL_RUNNER_FUNCTION_NAMEyesStack outputs
PUBLIC_BASE_URLyesThe public host. Sandbox job callbacks and status URLs use it
WORKOS_AUTHKIT_DOMAINnoThe 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_URLnoThe dashboard a run's trace link opens. Defaults to https://dashboard.broods.app
SANDBOX_MOUNT_ROLE_ARNfor mountsRole assumed for prefix-scoped workspace mount credentials
MICROVM_IMAGE_IDENTIFIER, MICROVM_EXECUTION_ROLE_ARN, MICROVM_LOG_GROUP_NAME, MICROVM_EGRESS_NETWORK_CONNECTOR_ARNfor lambda sandboxesWithout the connector, deny-all MicroVMs fail to launch
WORKDIR_URL, WORKDIR_API_KEYfor sandboxThe workdir control plane
CLOUDFLARE_SANDBOX_URL, CLOUDFLARE_SANDBOX_API_KEYfor cloudflareSee Cloudflare sandbox bridge
CLOUDFLARE_WORKER_URL, CLOUDFLARE_WORKER_API_KEYfor workerSee Cloudflare V8 Worker
APPLY_SANDBOXfor the dashboard's ApplyA 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_KEYfor Cloudflare MCPSee Cloudflare MCP runtime
DAYTONA_API_KEY, DAYTONA_API_URL, DAYTONA_ORGANIZATION_ID, DAYTONA_TARGET; E2B_API_KEY; VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_IDnoFallbacks for sandbox configs that omit their own
ENABLE_WEBSOCKET, NATS_URL, NATS_TOKENfor WebSocketENABLE_WEBSOCKET=true needs NATS_URL; NATS_URL needs DEPLOYMENT_ENVIRONMENT
OPA_BASE_URL, OPA_API_TOKENfor policiesDefault http://127.0.0.1:8181
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, SERVICE_NAME, DEPLOYMENT_ENVIRONMENTnoNo endpoint means no export
POSTHOG_API_KEY, POSTHOG_HOSTnoAnonymous PostHog AI traces + Logs. Unset either means no export
ANALYTICS_ID_SECRETnoSame as Convex. Keys AI session ids; unset means none
ENABLE_DIRECT_APInoDefault true. false turns POST /v1/runs off
ALLOW_PRIVATE_STORAGE_ENDPOINTSnoSame 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.yaml on an entry point named web, 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 rateLimit middlewares in apps/edge/src/traefik.ts.

gateway​

Stateless; scale it with replicas.

VariableRequiredNotes
BROODS_CORE_URLyesCore's URL, for socket token checks, agent runs and the machine relay
TERMINAL_TICKET_SECRETyesSame list as core
NATS_URL, NATS_TOKEN, DEPLOYMENT_ENVIRONMENTfor WebSocket and logsConnected on first use. DEPLOYMENT_ENVIRONMENT must equal core's, or no replay ever matches
LOKI_URL, TEMPO_URLnoLog and trace history
GATEWAY_ALLOWED_ORIGINSnoWebSocket 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_MSnoPer-pod limits. See apps/gateway/.env.example
GATEWAY_AUTH_FAILURES_PER_MINUTEnoFailed socket logins per client address. Default 20

dashboard​

VariableWhenNotes
NEXT_PUBLIC_CONVEX_URLbuild timeYour Convex URL
NEXT_PUBLIC_BROODS_BASE_URLbuild timeThe public host
NEXT_PUBLIC_POSTHOG_KEYbuild timePostHog project key. Unset means no analytics, errors or logs
NEXT_PUBLIC_POSTHOG_HOSTbuild timePostHog ingest host or your reverse proxy, e.g. https://eu.i.posthog.com
NEXT_PUBLIC_POSTHOG_UI_HOSTbuild timeBehind a proxy, the PostHog app it fronts, e.g. https://eu.posthog.com
DASHBOARD_ASSET_ORIGINbuild timeCDN origin pulling /_next/static from here, with CORS. Unset serves them here
ADMIN_ACCOUNT_SECRETruntimeThe admin sign-in key. At least 32 characters or the dashboard refuses to start
BROODS_SESSION_SIGNING_KEYruntimePrivate ES256 JWK that signs the session
BROODS_BASE_URLruntimeThe 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.

VariableNotes
BROODS_CONFIG_PLANESJSON 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_MSDefault 300000
DISCORD_IDENTIFY_LIMITDefault 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.
  • verify passes without a model key: the run fails at the provider call, which still proves routing, auth, config encryption and the Convex round trips. Set ANTHROPIC_API_KEY for 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