@donna-orchestrator/runner

Native macOS / Linux / Windows runner for the Donna orchestrator.

The runner connects a developer machine to a Donna orchestrator and accepts spec / plan / implement / verify / review work. Stages run locally on your host using an agent CLI — no Docker required for native macOS runners (that's the whole point of running native: drive Xcode, simulators, and other host-only tooling).

Requirements

• Node.js 22+ (the only thing this package depends on)
• A Donna orchestrator URL + 6-digit pairing code (your operator gives you these)
• git and any project-specific tooling. These are required — the runner refuses to start without them.
• At least one AI executor CLI. Claude alone is enough; Codex is optional. The runner refuses to start only when it can find none of them.

donna-runner tools prints two tables — required host tools, and the AI executors it found:

Required host tools
Tool   Status      Version   Install
------------------------------------
git    installed   2.43.0    —
node   installed   22.1.0    —

AI executors (at least one required; Codex is optional)
Executor   Status      Version   Dispatchable   Install
-------------------------------------------------------
claude     installed   2.0.30    yes            —
codex      missing     —         —              npm install -g @openai/codex

A backend can be installed but not dispatchable — that means Donna has no validated parser for its output yet and will refuse the stage at spawn. The runner still starts, but warns at boot rather than letting you discover it card by card.

The runner does not bundle any agent CLI, git, or Xcode. They're detected and reported, never installed for you.

Install

npm install -g @donna-orchestrator/runner

Or run without installing:

npx @donna-orchestrator/runner pair --url wss://donna.example.com/ws/runner --code 482931
npx @donna-orchestrator/runner start

Pair

Exchange the 6-digit pairing code shown in the Donna UI for a long-lived token:

donna-runner pair --url wss://donna.example.com/ws/runner --code 482931

The token + runner ID are persisted to ~/.donna-runner/config.json (mode 0600).

Start

donna-runner start

The runner connects to the orchestrator, advertises its capabilities (detected tools, which agent CLIs it has, sandbox tier, host info), and waits for work. Reconnect is automatic — keep the process running (or wrap it in a process supervisor of your choice).

Startup refuses, with the install command for each backend it looked for, when no executor is present:

donna-runner: no AI executor found on this host — a runner needs at least one:
  - claude: not installed — npm install -g @anthropic-ai/claude-code
  - codex: not installed — npm install -g @openai/codex
  ...
       Install one of the above and re-run. Codex is optional: Claude alone is enough.

Because the runner advertises per-backend capabilities, the orchestrator can route a card pinned to a backend you don't have away from this machine — you get a clean "no matching executor" decline on that card instead of the runner being shut down.

Other subcommands

| Command | What it does | | --------------------- | ------------------------------------------------------------------------------------------------------------ | | donna-runner status | Print local config + connection state. Token is redacted. | | donna-runner tools | Probe installed developer tools and print a status table. Useful for diagnosing setup issues before pairing. | | donna-runner update | Run npm update -g @donna-orchestrator/runner to upgrade. |

Auto-update notice

On each donna-runner start, the runner checks the npm registry once every 24 hours. If a newer version is available, you'll see a one-line notice on stderr:

donna-runner: a newer version is available: 1.2.0 -> 1.3.0
             Run `donna-runner update` to upgrade.

It will never auto-install — upgrades are explicit.

Configuration

~/.donna-runner/config.json (override the directory with DONNA_RUNNER_CONFIG_DIR):

{
  "orchestrator_url": "wss://donna.example.com/ws/runner",
  "token": "...long-lived JWT...",
  "runner_id": "moritz-mbp",
  "workspace_dir": "/Users/moritz/.donna-runner/workspaces",
  "host_mode": "same_user",
  "sandbox_mode": "auto",
  "xcode_path": "/Applications/Xcode.app/Contents/Developer",
  "simulator_device_set_path": "/Users/moritz/Library/Developer/CoreSimulator/Devices"
}

xcode_path and simulator_device_set_path are macOS-only and only required if you run iOS/macOS work. sandbox_mode is one of auto (default), seatbelt, docker, none. none prints a security warning because it disables process isolation.

Versioning

This package versions independently from the orchestrator. Compatibility is negotiated via the runner:hello protocol version. Use the latest published version of @donna-orchestrator/runner against the latest orchestrator release.

Troubleshooting

• start: required tool(s) missing on this host — donna-runner tools shows what's missing. Install it and re-run.
• Cannot connect — check donna-runner status for the saved URL, and verify wss://... is reachable from your machine. Reconnect attempts are unlimited with backoff capped at 30s.
• Token rejected — your token may have been revoked from the orchestrator UI. Re-pair: donna-runner pair --url ... --code ....

License

UNLICENSED — Donna is currently a private project.