Getting started
These guides take you from nothing installed to a small, always-on agent setup running on your own Mac or Linux box. By the end you will have:
- Harness, supervising agent CLIs (Claude Code, Crush, Codex) as a service. It restarts them when they fall over, fires scheduled sweeps on a cron, and lets you attach to any of them from a terminal or over SSH.
- Switchboard, turning webhooks into durable todos. It pushes those todos to your always-on agents the moment they arrive, so the agents don't poll.
- Cairn, giving your agents a place to publish reports and handoffs as shareable links.
You do not need all three. Harness is useful on its own from the first page; Switchboard and Cairn slot in when you want real-time work and shareable output.
The path
Read these in order the first time; each one assumes the previous.
| # | Guide | You finish with |
|---|---|---|
| 1 | Install | harness on your PATH, verified with harness doctor |
| 2 | Run the daemon as a service | the supervisor surviving logout and reboot (systemd or launchd) |
| 3 | Your first supervised agent | a Crush or Claude Code session you can attach to, restart, and read logs from |
| 4 | Scheduled sweeps | an unattended agent run on a cron, with outcomes you can trust |
| 5 | Push events with MCP channels | an always-on agent that wakes on a Switchboard todo |
| — | Claude Code under Harness | exactly what Harness runs for Claude Code, one-shot limits, and the channels flag |
| 6 | Observability | post-mortems with harness logs, the chatroom, doctor, and the SSH cockpit |
| 7 | The stack: Harness, Switchboard and Cairn | the whole loop end to end: roles, what each tool is and is not, a worked team example |
| — | Shared agents (stables) | a PR reviewer installed from a stable with harness agent install, scheduled on your own table |
| 8 | Run the merge train | approved PRs landing one at a time, each tested as the exact tree that merges |
| — | Troubleshooting | answers for the usual "it's green but nothing happens" moments |
| — | Onboarding path | Cairn, Switchboard and Harness set up one layer at a time, each with a gate that proves it works |
| — | Glossary | every Harness, Switchboard and Cairn term on one page, with an anchor to link |
The Usage section is the reference behind these guides: every verb, every config key, every flag.
Before you start
- A Mac or a Linux box you can leave running. A laptop works; scheduled sweeps notice when it wakes from sleep.
- At least one agent CLI, installed and logged in as the same user that will run Harness: Claude Code, Crush, or Codex.
- Credentials for that agent. Harness never asks for them; it starts the
CLI with the environment you give it. For Claude Code that is your Keychain
login on macOS, or a
claude setup-tokensubscription token (CLAUDE_CODE_OAUTH_TOKEN) on Linux and headless boxes.ANTHROPIC_API_KEYworks too, but bills the API rather than your subscription. See Claude Code authentication.
:::note Version
These guides track main. Several features they use are newer than the latest
tagged release: CRON_TZ, catch_up, timeout, on_overlap, keep_runs,
prompt_file, run history, the agent-activity view of harness logs, and the
chatroom. Install shows how to build from main until a release
catches up.
:::