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
BUILDD_API_KEY=bld_xxx PROJECTS_ROOT=~/projects bun start

Configure it in one of three ways:

• BUILDD_API_KEY env var — the simplest path, and it takes priority over the config file.
• buildd login — writes apiKey (and builddServer) into ~/.buildd/config.json.
• bun start --debug — starts the debug HTTP server on port 8766, which exposes an OAuth login route (/auth/login) and a POST /api/config endpoint. Only in this mode does opening http://localhost:8766 do anything.

With no API key and no serverless flag, a headless runner prints No API key — run with --debug or set BUILDD_API_KEY and does no work.

PROJECTS_ROOT is effectively mandatory: the runner exits at startup if it cannot resolve at least one project root.

Configuration

All config is stored in ~/.buildd/config.json. The file path can be overridden with BUILDD_CONFIG, and the containing directory with BUILDD_HOME.

Config Fields

Unrecognised keys in config.json are ignored at load time.

Environment Variables

Env vars with no config-file equivalent:

Note that every one of these is resolved with ||, not ??. A falsy value in config.json — maxConcurrent: 0, builddServer: "" — falls through to the next source rather than being honoured.

CLI Flags

There is no argument parser — any other flag is silently ignored.

URL Resolution

localUiUrl determines how the dashboard links back to a debug-mode instance (the "Open" and "Open Terminal" buttons). It is resolved once at startup:

1. Headless (no --debug, no PORT) → headless://<hostname>, and the steps below are never reached
2. LOCAL_UI_URL env var
3. localUiUrl in ~/.buildd/config.json
4. Tailscale auto-detect — runs tailscale ip -4 and uses the IPv4 address
5. http://localhost:<PORT> (fallback)

Remote Workspaces (Coder, SSH, etc.)

To get working dashboard links from a remote machine, run in debug mode and set the URL explicitly:

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

Or via env var:

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

If the Tailscale CLI is installed on the machine, the IP is auto-detected and you don't need to set anything — again, only in debug mode.

How It Works

The runner keeps two timers, not one:

Both are skipped entirely when serverless is set. Extra heartbeats are also sent at startup, after a claim, and on demand over Pusher.

Server-side, a runner shows as online while its last beat is within 1.5× the task-poll interval, stale between 1.5× and 2.5×, and is dropped from runner queries beyond 2.5×.

1. The runner starts and begins both timers
2. The dashboard shows connected instances under "Connected Agents"
3. When a task is created and assigned, the runner claims it and spawns a Claude Agent SDK session
4. Progress is reported back to buildd.dev in real-time via API + Pusher
5. In --debug mode, the dashboard can link directly to the runner for live terminal output