Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

24.2 KB
Raw Blame

harness

Run the coding-agent CLIs you already use, and drive them from anywhere.

harness watches the agent sessions you start in tmux on your own machine and bridges them to a web UI and, optionally, to a paired hardware device. The agents keep running as your processes, in your terminal, with your credentials; this is a bridge, not a wrapper.

It works with the popular coding agents — src/engines/ is the current list, one folder per agent, and yours can join them.

  • Every supported agent process under a configured terminal backend shows up as one agent you can talk to from the browser.
  • Turns, tool calls, todo lists and sub-agents stream out as they happen.
  • The browser channel is end-to-end encrypted (see src/lib/e2ee/).
  • One self-contained bundle with no Node native dependencies. Node ≥ 20 plus tmux is required.

Supported platforms

macOS and Linux (Ubuntu 22.04+ verified, bare metal and containers alike). The published artifact is one pure-JS bundle run by your own Node, so there is no per-OS build to pick and no native module to compile — the same cli.js runs everywhere.

Requirement Notes
Node ≥ 20 On Ubuntu the distro nodejs package is too old (24.04 ships 18.19, 22.04 ships 12.22). Install from NodeSource or nvm install 20.
tmux How agents are discovered. Not preinstalled on Ubuntu Server: sudo apt install tmux.
sqlite3 CLI Only for the store-backed engines (opencode, kilo, hermes, devin), which keep conversations in SQLite instead of a transcript file. Present by default on macOS, not on Ubuntu: sudo apt install sqlite3. Every other engine works without it, and the daemon says so at startup if it is missing.

Windows is not supported.

Agent Messages

Harnesses in the same tab can message each other while Agent Messages are on: an experiment of the account, the same on each of its computers, in Settings ▸ Experimental, off by default. From a terminal, harness settings agent-messages on (or off) turns it for the account, through this computer's daemon, and harness settings alone lists every setting. An agent runs, in its own pane:

harness send                          # who is in this tab, and how to work together
harness send api "Is the cleanup fix in?"
harness send api,web --text-file /tmp/note.md   # a longer message, from the temporary folder
harness send web --fyi "Staging is free until 15:00"   # news: it starts no turn of theirs

The pane says who is sending; a message goes only to harnesses that share a tab with the sender, on this machine or another of the owner's paired machines, while the account has Agent Messages on (as each of the two computers last read it). A working agent reads it at its next tool call, through Harness's PostToolUse hook, with nothing typed into its pane; an idle agent gets it as a prompt, typed only into an empty composer. Each message arrives under one header line naming its sender, never as the person's words, and waits until it is delivered. See the design.

Remote media previews

Harness Desktop can download an agent's image/video and open it on the viewing computer. The CLI advertises features.mediaPreview in terminal_capabilities. The existing encrypted agent_read_file RPC accepts a media-only variant: {agentId, path, media: true, offset, revision?}. Replies carry media, filename, totalBytes, offset, revision, and contentBase64. Chunks are 128 KiB; every chunk after the first must supply its revision. The maximum file size is 512 MiB.

Absolute paths, home-relative paths and file URLs resolve on the owning machine; relative paths (including symlink targets) stay inside the agent's working folder. Media suffixes and file signatures are checked. The original text-reading rules remain unchanged. Reads are stateless, close their handles after each request, and reject file changes during transfer. Paths and contents are omitted from frame logs. This reuses the existing E2EE request/reply types and needs no backend release.

scripts/smoke-media-peer.ts is an opt-in fixture for Desktop's A/B smoke test; it uses temporary identities and loopback sockets, never live machine state.

Install & run (harness)

Install the CLI and run hn to work locally. Sign in when you want to connect other machines:

curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash

(The installer is a first-party hosted script. It brings its own Node, downloads the published bundle and writes the ~/.local/bin/harness command, and hn: Harness in a terminal, which starts your local daemon the first time you run it. Local use requires no login.)

harness login         # asks how to sign in (Google, Apple, or a QR your phone scans) and saves this computer's session
harness login --google # or --apple: straight to that account in the browser, without asking
harness login --force # stop the daemon and sign in as a different SSO account
harness start         # starts the local adapter; uses a saved SSO session if present
harness start -f      # foreground mode for a supervisor (harnessd's master and its core); logs to stdout
harness status     # is it running? shows pid + the chat link
harness stop       # stop the background adapter
harness version    # print the installed version
harness tui        # all of Harness in this terminal — tabs, panes, every machine (see tui/README.md)
harness logout     # stop the adapter and clear this computer's SSO session

login uses the browser's native loopback SSO flow, as the auth-service client of whoever asked — harness-cli from a terminal, harness-desktop when the desktop app runs it — and the session remembers that client, because a refresh has to name it again. Its access token, refresh token, expiry and backend-resolved machine id are stored atomically with owner-only permissions in ~/.harness/auth/session.json; the immutable computer id lives separately at ~/.harness/computer-id. Later harness start invocations reuse and refresh that session as needed. login --force holds the daemon's spawn lock from the moment it stops the old daemon until the new session is on disk, so a harness start that lands while the browser is open (the desktop app runs one whenever the daemon is down) waits its turn rather than bringing a daemon up on the account being replaced. harness start beside a running daemon also asks it which machine it serves, and restarts one that answers for another account instead of reporting it "already running". Raw daemon logs go to ${ADAPTER_DATA_DIR}/harness.log.

The log is capped at 10 MB: the daemon checks the size every minute and, over the cap, rewrites the file with the newest half (the oldest lines are dropped, marked by a [log] trimmed line at the top). It's one file, not a rotation — 10 MB is the total on disk. A log left under a pre-rename name (machine.log, or the older adapter.log) is adopted by rename on the first start, so existing history carries over.

The daemon auto-updates itself — it polls the release manifest once a minute, at second :45 of each minute (ADAPTER_UPDATE_SLOT_SEC), and, on a newer build, downloads + verifies + swaps its own bundle and restarts at once (with rollback on a bad build). The slot is deliberate: the desktop app spawns harness start only around :15, so an update handoff and a spawn never contend for the daemon's spawn lock. harness start itself stages the newest build only for a daemon it is about to spawn — with one already running it says so and touches nothing, leaving the update to that daemon. A 401 on the backend link refreshes the SSO token and reconnects; only a refresh token the backend rejects signs the computer out. See RELEASE.md for publishing and the update internals. Disable with ADAPTER_UPDATE_DISABLE=true.

From source (dev): cd this package && npm install && npm run build && node dist/cli.js login (or npm run dev -- login via tsx — always foreground; self-update is off in dev). npm run bundle produces the single-file release artifact.

Install your build as harness (no release): bash scripts/install-cli.sh bundles this working tree into ~/.harness/cli — the same layout the public installer produces — and restarts the daemon on it, so harness on this computer means your code without publishing a version. Self-update is turned off in the command shim it writes (otherwise the published release overwrites your build within the minute). See RELEASE.md.

After signing in, start each agent yourself in tmux with its normal vendor command. Harness observes the process; it does not launch the CLI or choose its permission/trust flags:

tmux new
claude                    # or: codex, agent, opencode, pi, hermes, cmd, devin, muse, amp, kilo, grok

tmux is watched by default — there is no env var to set.

Each supported top-level CLI process appears automatically. Exiting or deleting the agent stops only the validated engine process; Harness never closes the user-owned tmux pane.

How it works

claude under a terminal backend ──writes──▶ ~/.claude/projects/**.jsonl
        ▲                                   │ chokidar + byte-offset tail (only new lines)
        │ backend input contract            ▼ normalize → ServerEvents (+ derived turn lifecycle)
   adapter CLI ◀────── down:{agentId} ── backend /api/adapter-ws ── up:{agentId} ──▶ web chat
  • The adapter emulates a node on the backend hub: it answers the hosted runtime RPCs (agents_list = discovered engine processes, sessions_list, session_get = full JSONL replay, project_files/project_read_file = the session's cwd file tree + file view, models_list, claude_login_status) and consumes web chat frames.
  • Files panel (project_files/project_read_file): rooted at the tmux session's working dir, it lists the tree (ignoring node_modules/.git/dist/… like the hosted runtime) and views a file only if it's ≤ 5 MB and text (binary → rejected). The same guard was added to the hosted runtime so both behave identically.
  • Process discovery is lifetime authority. On startup and every five seconds the daemon reads each configured terminal inventory and one shared process table. A supported top-level engine creates an agent immediately, before an engine session exists. A changed process in the same pane replaces it immediately; an absent process is removed after two successful scans. Probe failures do not remove anything.
  • Only sessions the daemon created are discoverable. The tmux inventory is limited to sessions named harness-<engine>-<timestamp>, which is what agent_create names them. A tmux session you open by hand and run an engine in, or one an agent spawns itself with a nested tmux new-session, never becomes an agent — create it through the app (or agent_create) instead.
  • Agents survive a reboot. The registry outlives the tmux server. On start, every registered agent whose pane is gone (a reboot, a tmux kill-server) gets a new pane running the same engine in the same folder, resuming its engine session when it has one, under the same agent id — so the app's tiles reattach by themselves. An agent that was pointed at a grid comes back on that grid: the registry row keeps the launch it was created or retargeted with (gridLaunch, key included, in the 0600 registry.json), and restore, agent_restart and the offline hook fallback all reuse it — a relaunch on the engine's own login would spend the wrong account while looking identical. A Codex profile agent comes back under its CODEX_HOME with its hooks installed. A grid row written before the launch was persisted is not relaunched; it is marked GRID_CREDENTIAL_REQUIRED instead. An engine with no resume flag (devin) comes back fresh.
  • Hooks bind mutable engine sessions to the process agent using authenticated tmux runtime hints plus verified caller ancestry. They do not require MACHINE_ID. SessionStart and catch hooks attach transcript/store metadata; SessionEnd only requests an immediate process reconciliation. /clear, /new, and resume move or rotate the binding without changing the live process agent's UUID.
  • Live agent sync to web + device: discovery emits agent_synced immediately, even with no session; binding later emits session sync, and confirmed process exit emits one agent_deleted. A sessionless agent returns an empty sessions_list, accepts input by agentId, and binds after the first turn.
  • A new agent can be pointed at a grid. When the desktop app has a grid selected it sends payload.grid (relay base URL, a key minted for that launch, and optionally a model) on agent_create; the daemon turns it into the engine's own environment and gives the new tmux session that environment with new-session -e, so the credential never appears in the engine's argv. Six engines have a documented way to be pointed somewhere else and are supported through it: claude (ANTHROPIC_BASE_URL), codex (-c model_providers.grid.*, key via env_key), hermes (OPENAI_BASE_URL), grok (GROK_MODELS_BASE_URL), copilot (COPILOT_PROVIDER_BASE_URL), and two that need a provider DECLARED rather than an endpoint moved: pi (a private config directory via PI_CODING_AGENT_DIR) and opencode (a private opencode.json via OPENCODE_CONFIG) — so the user's own ~/.pi and ~/.config/opencode are never touched. OpenCode is in that second group because pointing OPENAI_BASE_URL at a grid leaves its compiled-in model catalogue in charge: the endpoint moves, the model names do not, and the relay answers 503 · No providers available for this model. Every other engine is refused with GRID_ENGINE_UNSUPPORTED and a reason specific to it — some talk only to their own service, some need a provider block written into a dotfile this daemon will not edit — rather than quietly started on its own login. Needs tmux ≥ 3.2; an older one is refused as TMUX_TOO_OLD_FOR_GRID. See src/lib/gridLaunch.ts.
  • A running agent can be moved to a grid (agent_retarget): respawn-pane -k -e re-execs the pane's engine with the new launch and --resume, keeping the pane, its id and its scrollback, and the new process is adopted onto the same agent record. A pane mid-turn is refused (AGENT_BUSY) rather than interrupted. Which grid an agent is on is read off its live process (src/lib/gridAssignment.ts), never bookkept.
  • Mirror-all: every JSONL line streams up — prompts typed directly in the terminal render in the web identically to web-sent ones (turn_started/turn_ended are derived from the file).
  • Compaction (/compact or auto-compact): claude does an in-file compact — the JSONL keeps the same sessionId and stays append-only (pre-compact history is preserved on disk), so the byte-offset tail streams straight through with no dead file and no truncation re-read. The injected system/compact_boundary line becomes a single context_compact UI hint; the big isCompactSummary summary line and any isMeta bookkeeping line are suppressed via those authoritative flags (compactEventFromRaw in lib/normalize.ts) so the summary is never rendered as a fake user turn — an auto-compact firing mid-turn keeps the open turn open.
  • A web chat message arrives as a message frame and is submitted through one validated primary runtime.

Terminal backend behavior

  • Two backends: tmux and ptyhost. tmux is the backend on macOS and Linux. ptyhost is the Harness PTY host (pty/, harness-pty), a long-lived process of its own with a ConPTY per pane: the backend on Windows, and buildable on Unix for its tests. Its home is HARNESS_PTY_DIR (~/.harness/pty), with its discovery file in run/ and its log in logs/pty-host-<instance>.log (one per host build); HARNESS_PTY_BIN overrides the host binary. The retired Herdr backend has been removed. TERMINAL_BACKENDS=herdr is not an error — it is dropped with a warning and the daemon runs on the platform's default, because the CLI self-updates and a retired setting must not stop an unattended machine from starting. HERDR_SESSIONS and HERDR_BIN are no longer read.
  • Unset means auto, which resolves to ptyhost on Windows and tmux everywhere else. TERMINAL_BACKENDS pins the set (tmux, ptyhost, or both).
  • Harness never auto-starts a session.
  • harness status answers "is my pane being watched?" — terminalSelection says auto or configured, and terminalTargets lists what is live right now, not what was configured at boot.
  • The shared backend contract can create and close a tmux session when explicitly invoked. This is lifecycle capability, not automatic startup behavior; normal discovery observes user-owned sessions, and agent deletion still terminates only the validated engine process.
  • One process visible through nested panes remains one Harness agent with multiple runtime locators; an engine process replacement does not.
  • Backend failures are independent. A failed probe is unknown, not proof of death. An agent with no verified runtime becomes dormant and is republished with the same id after recovery.
  • Existing tmuxPane registry rows migrate in place. tmux rows retain their legacy projection during the compatibility window. Runtimes an earlier build recorded for a Herdr pane are dropped on load, and an agent that lived only in one is removed.

For reproducible multiplexer verification, install dependencies and run the opt-in real suite from cli/ under a normal umask:

umask 022
npm ci
npm run test:tmux-real

The tmux suite creates and cleans up its own private server, including when run from inside a Harness pane. No outer tmux kill-server cleanup is needed. Setting TMUX_TMPDIR alone does not isolate tmux: an inherited TMUX still selects the parent server. Any separate fixture must clear TMUX/TMUX_PANE and name its private socket explicitly with tmux -S for cleanup.

The suite uses isolated, test-owned lifecycle fixtures. Its engine matrix explicitly skips commands that are not installed; authentication or first-run onboarding that prevents a proprietary CLI from running is unavailable evidence and must be reported as such, not described as exercised.

Config (environment variables; see .env.example)

Dev and release builds use the same production backend, account and machine state by default. Harness does not load a project's .env when started from that folder. To run against a different backend deliberately, export the settings or select a file explicitly:

HARNESS_ENV_FILE=/absolute/path/to/harness.env harness start

Exported variables take precedence. An explicit DOTENV_CONFIG_PATH remains supported. If you previously relied on automatic .env loading, set one of these paths before starting Harness. harness status reports the running daemon's backend, account environment and state directories; those can differ from the shell that invokes the command. Older daemons may not report all fields.

var default meaning
BACKEND_WS_URL wss://harness-api.autonomous.ai backend to dial (/api/adapter-ws)
AUTONOMOUS_ENV prod SSO environment: prod or stag
ADAPTER_COMPUTER_ID (unset) pin the stable local computer id for an ephemeral host; never written to disk
PORT 18473 localhost port for the hook callbacks (FIXED — if taken, the adapter reports it rather than picking a random port)
CLAUDE_PROJECTS_DIR ~/.claude/projects where Claude writes session JSONL
ADAPTER_DATA_DIR ~/.harness/cli/data registry and daemon-local state (SSO session is always ~/.harness/auth/session.json)
DISABLE_HOOK_INSTALL false skip auto-installing the claude hooks
TERMINAL_BACKENDS (auto) pin the set: tmux, ptyhost, or both (auto: ptyhost on Windows, tmux elsewhere); a retired herdr is dropped with a warning
HARNESS_PTY_DIR ~/.harness/pty the PTY host's home (run/, logs/)
HARNESS_PTY_BIN (bundled) the harness-pty binary to run, used as it is
TERMINAL_RECONCILE_INTERVAL_MS 5000 backend-neutral discovery interval; minimum 5000 ms
TMUX_REAP_INTERVAL_MS 5000 process discovery interval (removal requires two confirmed misses)
ADAPTER_UPDATE_URL …/adapter/metadata.json GCS release manifest the daemon polls for a newer build
ADAPTER_UPDATE_KEY cli manifest key for this CLI
ADAPTER_UPDATE_CHECK_MS 60000 how often (ms) to poll for a newer build (no check on start — harness start already staged the newest)
ADAPTER_UPDATE_SLOT_SEC 45 the wall-clock second each poll lands on; keeps clear of the desktop's harness start slot at :15. Negative = plain interval
ADAPTER_UPDATE_DISABLE false set true to turn self-update off
ADAPTER_CLI_DIR ~/.harness/cli install dir holding the cli.js/notify.mjs the updater swaps
LOG_FRAMES false one log line per backend frame — type, audience and opaque ids, never a payload body. Every content-bearing frame is encrypted before it reaches the socket, so this is the only way to see what the daemon actually sent
HARNESS_HOOK_DEADLINE_MS 4500 wall-clock budget a hook gives itself before abandoning optional work. Raise it on a slow or heavily loaded machine, where the budget is spent on load rather than on the hook and the offline registry fallback silently does nothing. Clamped, never below the default
ORI_VOICE_ROUTE_MODEL deepseek/deepseek-v4-flash the voice router's classification model for agents routed through an OpenRouter gateway (ori claude), which have no vendor credential to spend
ORI_CREDENTIALS_PATH ~/.ori/credentials.json where ori login stores its key; read only when neither the daemon env nor the agent's own process supplies one

Device (hardware commander)

A paired device mirrors the same agent. The adapter emits a curated commander stream from the same watched JSONL (via sendCommander, commanderEligible): commander_event cards — processing (busy), tool (name + arg + color), todos checklist, summary, done (clear busy). It answers the device's agents_list (tiles) and agent_recent (last summary) RPCs; voice turns arrive as an injected message → sendToTmux. A device that joins mid-turn converges via a client-count signal (__clients) — the adapter re-emits the open turn's live state on join (no periodic heartbeat).

The per-turn recap is cut from the answer the moment a turn ends, with no model in the loop: the answer's first prose sentence is the headline, and the text under it is the answer itself, flattened to one line and clipped to 250 characters (deriveTurnBody). It is persisted as recap\n\ntext per session (${ADAPTER_DATA_DIR}/summaries.json) and returned on project_recent at device boot. The window, the phone and the dial each show it beside the full answer, so the model rewrite the daemon once offered (about 9 s of every turn) is gone.

Pair an Autonomous device directly

Harness discovers the OS's existing _autonomous._tcp advertisement. Select a discovered device and enter the code displayed on it; no IP address or device backend login is needed.

harness autonomous-device discover --json
harness autonomous-device pair --device '<discovery-id>' --code-stdin
harness autonomous-device status --json
harness autonomous-device list --json
harness autonomous-device revoke '<full fingerprint from list>'

Desktop writes the code to stdin and closes stdin. Terminal users may use pair <device-code> --device <discovery-id>. Mac connects directly to the advertised OS endpoint, reusing the original Harness E2eeManager and identity store. Saved associations rediscover/reconnect automatically. Revoke closes only the selected device connection. Existing Harness Mac login/start requirements remain unchanged; the running daemon's direct device transport works offline from its backend. Browser/dial behavior and Buddy are unchanged.

See the contract.