Connect your Runner

A Runner is a machine you own, beyond your desktop, that executes Workspaces: a VPS, a homelab box, or a VM on your own cloud account, running the same sidecar binary the desktop bundles. Your agents run there under your own subscriptions, and no third party sits in the execution path; the desktop stays the control plane. This guide takes you from a Linux box to a Workspace running on it.

What the host needs

• Linux with KVM. Each Workspace on a Runner executes in its own hardware microVM, so the host must expose /dev/kvm. Compatible: Hetzner, OVH, bare metal, Proxmox homelabs, and clouds with nested virtualization enabled. AWS works on metal instances only. A host without KVM is refused at bootstrap with a message naming the reason and this provider list.
• A container engine. Docker or Podman. A host without one is also refused.
• Kata Containers, the KVM-backed microVM runtime, for the microVM tier (the Sandboxed preset). With an engine but no Kata, the Runner reports the plain-container tier, which serves the Trusted preset only.
• A network path to your desktop. The Runner dials out to your desktop, so the desktop must be reachable from the host over your own network (LAN, VPN, or tailnet). There is no relay service.

1. Pair the host

In Settings, under Runners, choose Add a Runner. The flow states the KVM requirement, then shows a one-command bootstrap with a live pairing code inside it:

cohalen-sidecar --runner --pair <code>@<host>:<port>

Run that command on your host before the code expires; the flow shows the countdown, and New code mints another. The code is single-use. The Runner dials out to your desktop's listener, so nothing listens on the Runner and you open no inbound port on it.

When the host connects, its row appears with the facts a real probe carries: reachable or not, disk free, and the isolation tier (microVM or container). If the host fails the KVM or engine probe, the flow shows the typed refusal and stays open, so you can run the same command on a different host.

2. Place your credentials

Pairing places nothing. Placing credentials is its own act: Place credentials on the paired row sends this desktop's own agent auth (your Claude Code OAuth token, your Codex auth file) to the host, where it lands as an owner-only file (mode 0600). If the desktop holds neither, the act is refused with the reason.

An agent receives the credential only as environment variables when its sandbox spawns; no credential file exists inside a Workspace's sandbox. The placement is revocable: removing the Runner offers to wipe what you placed.

3. Run a Workspace on it

Launch a Workspace as usual. With a Runner paired, a host pill appears under the prompt input while the Workspace is unstarted, set to Local by default; open it and pick your Runner.

A Runner needs a spend cap. Set the monthly cap in USD on the cap pill beside the host pill; until you set one, the prompt does not send. The cap is mandatory on a Runner because an unattended host has no one watching the meter: the Spend kill-switch stops a Turn that crosses it, the same way it does locally.

From there the flow is the one you know. The Runner keeps one clone per Repository plus a worktree per Workspace, the repo's Setup script runs inside the Workspace's microVM on the first Turn, and the Turn streams into Chat live.

If the channel to your desktop drops mid-Turn, the Turn keeps running on the Runner; when the channel returns, the desktop catches up from where it left off. A Turn that finished while the desktop was closed is rebuilt from the Runner's disk when you reopen the Workspace.

4. Remove a Runner

Remove, on the Runner's row, unpairs it: new Workspaces stop routing to it, while clones and worktrees stay on the host. The confirm offers a checkbox to also revoke any agent credentials you placed there.

Current limits

• One paired Runner holds the live channel per desktop; the registry is a list, but a second Runner cannot connect alongside the first yet.
• The Runner's row does not yet show its spend for the month.
• The channel is ws://: the traffic crosses your network unencrypted. Pair over a LAN or VPN you trust.

Next: Working as a team, sharing visibility without sharing execution.