How Buildd Runs AI
Where model calls run, which credential pays for each, and what to set up for API keys, subscriptions or self-hosting
How Buildd Runs AI
Buildd calls models in two places. Each has its own credentials and its own bill.
| Server-side model call | Runner-side agent run | |
|---|---|---|
| Where | The buildd web app | Your runners |
| How long | Seconds | Minutes to hours |
| What it is | One model call, or one streaming chat turn. No repo, no shell | A Claude Code or Codex session with a worktree, tools and commits |
| Used for | Interactive AI (chat), goal-criteria grading, task classification and category checks | Every task: building, research, planning, PRs |
| Paid with | A provider API key (Anthropic, OpenAI, OpenRouter) | A subscription (Claude or ChatGPT/Codex) or an API key |
| Billed | Per token | Per seat, or per token if the runner uses an API key |
A subscription can't pay for server-side calls. Subscription login is tied to the runner that holds it, and a single server request has no seat to use. So server-side calls always need an API key, and a runner never uses those keys.
Server-side model calls
These run inside buildd and return in seconds. None of them needs turning on.
| Kind | Features | When it runs | Control |
|---|---|---|---|
| Interactive AI | Chat, and the per-turn routing that picks each turn's tier | Whenever a key resolves | None |
| Decision calls | Task classification, task category check | Whenever a key resolves | None |
| Server-side features | Goal-criteria grading (the only one listed today) | By billing model: server-side if a team key resolves, else on a runner | Per-feature override (Server-side / Runner) under Advanced in AI → AI features |
Things to know:
- Chat never falls back to a runner or a subscription. With no key, the chat box shows who can fix it: admins can add a key under Connections → Model providers, or if the key policy is "Each person's own key", members can connect one under Account → Profile or add OpenRouter.
- Chat writes starting recurring or unattended work always ask for approval. This includes scheduling tasks, arming a mission, or resuming work.
- Grading always has somewhere to run. Without a team key, or with an override set to Runner, an agent run on your runner grades written criteria instead, slower and on its seat.
Providers per call:
| Path | Anthropic | OpenAI | OpenRouter |
|---|---|---|---|
| Chat | Yes | Yes | Yes |
| Grading | Yes | No | Yes |
| Decision calls | No | No | Yes |
A chat tier mapped to an Anthropic or OpenAI model still works with only an OpenRouter key. Buildd serves the same model through OpenRouter.
Runner-side agent runs
Runners do the actual work: they clone the repo, run the agent harness, and open PRs. Credentials for them are covered in Secrets & Credentials and Codex Backend.
| Harness | Subscription | API key |
|---|---|---|
| Claude Code | Claude OAuth token (oauth_token) or Claude credentials (claude_credential) | anthropic_api_key |
| Codex | ChatGPT/Codex auth.json (codex_credential) | OPENAI_API_KEY on the runner |
| Claude Code via OpenRouter | — | llmProvider: openrouter + llmApiKey in the runner's config |
Credentials on the runner itself win. Server-managed secrets are the fallback, delivered when a runner claims a task.
Why the runner still matters when you pay per token: Serverless hosts can't hold a process for an hour, and agent work needs a real filesystem and shell. The runner is where that runs, whoever pays.
Why a subscription is usually cheaper for agent work: a long agent run can use millions of tokens. On a seat that costs nothing extra until you hit the plan's usage window. The cost buildd shows for seat runs is an estimate (labelled virtual), not money spent.
Keys: the team's or each person's
Server-side keys live in Connections → Model providers. Connect OpenRouter with one click, or paste an Anthropic, OpenAI or OpenRouter key. Only the last four characters are shown after saving.
An admin picks whose key pays. The choice covers all server-side AI, not just chat:
| Whose key | Chat | Team work with no person behind it (grading) |
|---|---|---|
| Team key (default) | The team key. Personal keys ignored | The team key |
| Team key, people may use their own | A person's own key if they added one, else the team key | The team key |
| Each person's own key | That person's key. No team fallback | No key resolves, so it runs on a runner |
Members add their own key under Account → Profile. A personal key only ever pays for its owner's calls.
Budgets
Team → Budgets shows spend split into Interactive and Agent runs, today and this month. Admins see it per person. Agent runs count against the person who created the mission.
| Cap | Default | Notes |
|---|---|---|
| Team daily interactive budget | $20/day | Resets at midnight in the team's timezone. 0 pauses chat. Never uncapped |
| Per-person daily cap | $10/day (half the team budget) | Clamped to the team budget |
| Turn rate | 30 turns per person per 10 minutes | Fixed |
Under Each person's own key there is no team cap and no default per-person
cap; an admin can still set one. Interactive spend never counts against an
account's maxCostPerDay.
Model tiers
Nobody picks a vendor model per task or per chat. Callers ask for a tier; an admin decides which model backs it.
| Tier | Meant for |
|---|---|
premium-plus | Opt-in only. Nothing is routed here unless a task or role asks for it |
premium | Planning, hard engineering, design |
standard | Most engineering and research. The default |
budget | Fast, cheap calls: triage, classification |
Admins map each tier to a provider and model in AI → Model tiers (or the
manage_model_tiers MCP action), for the whole team or one workspace. Buildd
resolves a tier in this order:
- The workspace's mapping
- The team's mapping
- The newest model in the tier's price band from the live model catalog
- Built-in defaults
Things to know:
- Agent runs resolve at claim time. Change a mapping and tasks already in the queue pick up the new model. Changes apply within about a minute.
- An explicit
modelwins. A task withmodelset, or a role pinned to a full model ID, skips tiers and pools entirely. - Chat picks a tier per turn. A quick classifier sends simple turns to
budgetand complex ones topremium, and falls back tostandard. It never changes which model backs a tier.
Tier pools
A tier can be backed by a pool of models instead of one. AI → Model tiers shows two tables, Agent runs and Chat and quick calls, with each tier's models, traffic share, win rate, mistake mix and cost per 1k tokens.
| Today | |
|---|---|
| Traffic | Split by hand: an admin sets each model's share, or pins the tier to its base model. Buildd does not shift traffic on its own |
| Stickiness | A task keeps its model across retries, and a mission's tasks share one. A chat keeps its model while it stays on the same tier |
| Feedback | Thumbs up or down on each assistant turn in chat. A thumbs-down asks for a reason |
| Excluded | premium-plus, sensitive workspaces, tasks with an explicit model or a pinned role, and reviewer tasks |
If a pool's model can't be served (the runner can't run it, or there's no key for its route), the base model runs instead.
Settings map
| Group | Pages |
|---|---|
| Account | Profile: your sign-in, teams and personal key |
| Team | Members, Budgets |
| Connections | Runners, Model providers, GitHub and Vercel, Notifications, MCP connectors |
| AI | AI features, Model tiers |
| Workspaces | Workspaces |
What to set up
| You... | Runners (Connections → Runners) | Server-side (Connections → Model providers) | Whose key |
|---|---|---|---|
| Pay per token | Store an anthropic_api_key secret, or set OPENAI_API_KEY on the runner for Codex. Runners still run the agent | Add an OpenRouter, Anthropic or OpenAI key. Chat and grading then run server-side | Team key |
| Have a Claude or ChatGPT subscription | Add the Claude OAuth token or Codex auth.json. This is where the heavy work runs | Optional. Add a key only if you want chat. With a team key, grading moves server-side; override it to Runner under Advanced to keep it on your seat | Team key, or each person's own |
| Self-host | Same as either row above | Either add keys in the app, or set ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY and BUILDD_ALLOW_ENV_INFERENCE_KEYS=1 | Any |
In production, provider env vars are ignored unless
BUILDD_ALLOW_ENV_INFERENCE_KEYS=1 is set. Without it, a self-hosted deploy
with only ANTHROPIC_API_KEY in its environment has no server-side key, and
chat stays off. Env keys are also a last resort: any key stored in the app
wins.