Runner Setup

The Runner is a standalone worker that connects to buildd.dev. It runs on your machine (or a remote workspace like Coder) and executes tasks using the Claude Agent SDK.

Prerequisites

Bun runtime
A buildd.dev account with an API key

Quick Start

cd apps/runner
bun install
bun start

On first launch, open http://localhost:8766 in your browser to complete setup (API key, workspace linking).

Configuration

All config is stored in ~/.buildd/config.json. The file is created automatically during setup.

Config Fields

Field	Type	Default	Description
`apiKey`	string	—	Buildd API key (`bld_xxx`)
`runnerUrl`	string	auto-detected	Public URL for this instance (see URL Resolution)
`maxConcurrent`	number	`3`	Max concurrent workers
`model`	string	`claude-opus-4-6`	Claude model to use
`acceptRemoteTasks`	boolean	`true`	Accept task assignments from the dashboard
`bypassPermissions`	boolean	`false`	Skip permission prompts (dangerous commands still blocked)
`builddServer`	string	`https://buildd.dev`	Server URL override
`openBrowser`	boolean	—	Auto-open browser on startup
`llmProvider`	string	`anthropic`	LLM provider: `anthropic` or `openrouter`
`llmApiKey`	string	—	Provider API key (for OpenRouter, etc.)
`llmBaseUrl`	string	—	Custom LLM base URL
`pusherKey`	string	—	Pusher key for realtime events
`pusherCluster`	string	—	Pusher cluster (e.g. `us2`)

Environment Variables

Env vars override config file values. Useful for CI/Docker.

Variable	Overrides
`BUILDD_API_KEY`	`apiKey`
`RUNNER_URL`	`runnerUrl`
`PORT`	Listen port (default: `8766`)
`PROJECTS_ROOT`	Comma-separated project directories (e.g. `~/projects,~/work`)
`MAX_CONCURRENT`	`maxConcurrent`
`MODEL`	`model`
`BUILDD_SERVER`	`builddServer`
`BUILDD_CONFIG`	Config file path (default: `~/.buildd/config.json`)
`LLM_PROVIDER`	`llmProvider`
`LLM_API_KEY`	`llmApiKey`
`LLM_BASE_URL`	`llmBaseUrl`

URL Resolution

The runnerUrl determines how the buildd.dev dashboard links back to this instance (the "Open" and "Open Terminal" buttons). It's resolved once at startup in this order:

RUNNER_URL env var (highest priority)
runnerUrl in ~/.buildd/config.json
Tailscale auto-detect — runs tailscale ip -4 and uses the IPv4 address
http://localhost:8766 (fallback)

Remote Workspaces (Coder, SSH, etc.)

If you're running the runner on a remote machine that's accessible via Tailscale or another network, set the URL explicitly so dashboard links work:

// ~/.buildd/config.json on the remote machine
{
  "runnerUrl": "http://<tailscale-ip>:8766"
}

Or via env var:

RUNNER_URL=http://<tailscale-ip>:8766 bun start

If Tailscale CLI is installed on the machine, the IP is auto-detected and you don't need to set anything.

How It Works

The runner starts and sends a heartbeat to buildd.dev every 5 minutes
The dashboard shows connected instances under "Connected Agents"
When a task is created and assigned, the runner claims it and spawns a Claude Agent SDK session
Progress is reported back to buildd.dev in real-time via API + Pusher
The dashboard can link directly to the runner for live terminal output

Runner Setup

On this page