buildd
Agents say they're done. buildd checks.
You write down what done means, as checks. Agents do the work on runners you control. buildd runs the tests, its own review agents and its decision models, and nothing counts as done until the checks pass.
buildd.dev · Docs · Dashboard
How it works
- Start with what done means. You give a mission its goal criteria. Where it can, buildd runs each one as a check: a command that must exit 0, PRs that must merge, an artifact that must exist. A criterion no command can express stays a plain sentence, and a model grades it. A mission can't complete until every criterion passes.
- You only get asked when it matters. When an agent asks a question, a decision model answers the low-stakes ones on the spot. Questions that touch migrations, auth and secrets, CI or deploys, protected paths or spending always come to you.
- buildd checks the work. buildd won't merge a PR on red CI. Depending on the merge policy you pick, a reviewer agent reads the change and approves it, sends it back to the author or escalates to you, and a visual auditor screenshots the pages a mission changed. Work that falls short goes back.
The server coordinates and never runs an agent. Runners claim tasks over the REST API, do the work in a git worktree, open the PR and report back. Agent runs take minutes to hours, longer than a serverless request can live.
Quick start
curl -fsSL https://buildd.dev/install.sh | bash
exec $SHELL
buildd login
buildd
buildd login opens your browser to connect this machine to your account; on a headless or SSH machine with no browser, use buildd login --device and enter the code it prints. buildd then starts the runner in that terminal. To keep it running after you close the terminal, and across reboots, run buildd service install instead.
The installer clones the runner into ~/.buildd, installs Bun if you don't have it, puts the buildd launcher in ~/.local/bin and adds that to your shell rc. Once you're logged in, re-running it offers to register the background service; pass --service to register it without asking (curl -fsSL https://buildd.dev/install.sh | bash -s -- --service). Windows, from any shell: powershell -ExecutionPolicy ByPass -c "irm https://buildd.dev/install.ps1 | iex" (set BUILDD_SERVICE=1 first to register the service without asking).
The runner has no web page by default. buildd --debug adds a local one on http://localhost:8766 for troubleshooting.
buildd login also registers the buildd MCP server in ~/.claude.json, so Claude Code can create and work tasks. Runner commands, the background service and env overrides are in apps/runner/README.md.
Next: create a workspace and your first mission in the dashboard, and read the runner guide.
Where it runs
| Where | Status | |
|---|
| Your machine or server | Available | Laptop, build box, VM. Runners connect out to buildd; nothing has to reach in. |
| Your Cloudflare account | Preview | A fresh container per task, with a short-lived GitHub token for one repo (apps/cloud-runner). |
| Hosted by us | Coming soon | We run the runner; you still bring your own model key. |
Specs, review and merge rules are the same wherever the runner lives.
Models
Bring your own key. Store it in buildd, team-wide or for one workspace, and runners receive it when they claim a task.
- Anthropic API key for Claude tasks
- OpenRouter key
- LiteLLM or another OpenAI-compatible gateway (
apiKey + baseUrl)
- OpenAI API key for Codex tasks
Each task runs on Claude (Agent SDK) or Codex, picked per task, role or workspace. Credentials live in one encrypted secrets table; see docs/credentials-architecture.md.
Every prompt the server sends a model has a public default in this repo, and a deployment can override any of them (docs/prompts.md).
Repo layout
| Path | What it is |
|---|
apps/web | Next.js dashboard, REST API and MCP server (src/app/api/mcp) |
apps/runner | The runner: claims tasks, runs agents, local web UI and buildd CLI (Bun) |
apps/cloud-runner | Cloudflare Worker that runs one container per task |
apps/dispatch | Cloudflare Worker for queued delivery, timers and retries |
apps/model-policy | Cloudflare Worker that maps a surface and tier to a provider and model |
packages/core | Drizzle schema and migrations, knowledge store, model routing, question gate |
packages/shared | Types shared by the server and the runner |
packages/ai-kit | Chat components, tool permissions and model plans for your own app (@buildd/ai-kit) |
packages/dispatch-contract | Wire types between buildd and the dispatch Worker |
The product spec lives in docs/SPEC.md, with per-capability contracts in docs/specs/.
Contributing
bun install
cp apps/web/.env.example apps/web/.env.local # fill in DATABASE_URL, AUTH_SECRET, ...
bun dev
Run the unit tests with bun run test, not bun test. The script runs each test file in its own process; bun test loads them all into one, and module mocks leak between files. Read CLAUDE.md for repo conventions (branching, migrations, the public-repo rules) and docs/testing.md for the test layout. PRs target dev.
License
The product is source-available under the Functional Source License (FSL-1.1-ALv2), sometimes called Fair Source. The contract packages are Apache-2.0.
| Path | License |
|---|
apps/web, apps/control-plane, apps/dispatch, apps/cloud-runner, apps/model-policy, apps/responder, packages/core | FSL-1.1-ALv2 |
apps/runner, packages/shared, packages/ai-kit, packages/dispatch-contract, packages/spec-contract, packages/workflow-kernel | Apache-2.0 |
The FSL code is free to use, modify and self-host for anything except offering a competing commercial product or service. Each release converts to Apache-2.0 two years after it ships. The Apache-2.0 packages can be embedded in anything, no strings attached. Each package carries its own license and license field in package.json.
The buildd name and logo are not licensed. The licenses above cover the code, not the brand.
Contributing code requires signing a Contributor License Agreement; see CONTRIBUTING.md.
A separately licensed Enterprise module is a proposal only; see docs/specs/commercial-licensing.md. The offline license check in packages/core/license is an entitlement signal for such future modules, not protection for this source-available code.
