Remote machines

How it works

A small daemon, kadro-worker, hosts agent sessions on the remote machine. Everything rides your Tailscale tailnet — the worker binds only its Tailscale address, so nothing is exposed to the internet. Pairing a machine takes a single-use, 10-minute code; panes on that machine then behave like local ones: same terminal, same agents, same keybindings.

Sessions survive independently of the app. Close the pane and the agent keeps working; quit ADE and reattach tomorrow; if the worker machine reboots mid-conversation, reopening the pane resumes the agent's conversation where it stopped.

The fast path: let an agent set it up

In ADE open Settings → Machines → “Set up a new machine with an agent…”, copy the generated prompt, and paste it into any agent with shell access on the new machine — a claude session over SSH is perfect.

The agent installs the worker, then loops the built-in wizard (kadro-worker setup --json), fixing what it safely can. It hands you each auth moment as it hits one:

1. Tailscale login — it relays a login URL; open it, authenticate.
2. GitHub SSH key — the wizard generates a dedicated key (~/.ssh/kadro-worker, passphrase-less, because the worker runs git non-interactively under systemd/launchd); the agent relays the public key; add it to GitHub → Settings → SSH keys.
3. Agent CLI logins — run e.g. claude once on the machine and log in.

When every check is green the wizard prints a pairing code, host, and port. The agent reports them back to you; enter them in ADE under Settings → Machines → Add machine. That's the whole trust handshake: the code is single-use, expires in 10 minutes, and the setup agent never talks to your ADE.

The manual path

Same steps, no agent:

1. Install:

   curl -fsSL https://github.com/alexci04/kadro-releases/releases/latest/download/kadro-worker-install.sh | sh

   Prefix with sudo on Linux for a system-wide service.
2. Wizard: run kadro-worker setup and follow the ✓ / → / ⚠ lines — → steps come with the exact command to run; ⚠ steps are the auth moments above. Rerun after each fix; it is idempotent.
3. Defaults: once your agent CLIs are logged in, run kadro-worker setup --apply-defaults— it sets claude's permissions.defaultMode to autoso remote sessions don't stall on approval prompts. Never applied without the flag.
4. Pair: the final run prints the pairing code + host + port; enter them in ADE → Settings → Machines.

Useful commands afterwards:

How your repos get there

Remote sessions are repo-managed: when your workspace has a GitHub origin, the worker clones it and runs the agent in a dedicated worktree on a session branch (kadro/<workspace>-…). Push from the pane menu and the branch lands on origin, fetched locally so your usual diff/PR flow sees it. The worker can only clone from origin — it can't see your local disk — so a repo without a remote runs in the worker's home directory instead (the pane says so when that happens).

Using a laptop as a worker

Laptops fight you in two ways; both are fixable once:

• Lid close = sleep. In /etc/systemd/logind.conf set HandleLidSwitch=ignore, HandleLidSwitchExternalPower=ignore and HandleLidSwitchDocked=ignore, mask the sleep targets (systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target), restart systemd-logind.
• Wi-Fi power save. It causes brutal latency spikes and packet loss — and lid/AC events silently re-enable it. Turn it off (iw dev wlan0 set power_save off) and make it stick with a udev rule plus a small systemd timer that re-asserts it every minute.

The agent runbook applies both automatically when it detects a laptop.

Troubleshooting

• 90% packet loss / stalls on Wi-Fi — check that only ONE network daemon owns the interface. A machine running both iwdand NetworkManager will misbehave under load; disable and mask the one you don't use.
• git works over SSH but the worker can't push — the worker runs git non-interactively, so passphrase-protected keys fail silently. Use the dedicated passphrase-less ~/.ssh/kadro-worker key the wizard generates.
• tailscale: command not found on macOS — the App Store install ships no CLI symlink. The worker probes the app-bundle CLI automatically; for your own shell use brew install tailscale.
• An agent CLI isn't found by the service — the service PATH covers ~/.local/bin, /opt/homebrew/bin, /usr/local/bin and the system dirs. Install CLIs into one of those, not a shell-rc-only location.
• Worker offline after reboot — user-level services need lingering: sudo loginctl enable-linger <user> (the wizard reminds you). System services installed with sudo start on boot by themselves.

Security model, in short

• Transport is your tailnet (WireGuard); the worker binds the Tailscale address only.
• Pairing mints a 256-bit bearer token; only its hash is stored on disk. The 8-character pairing code is single-use and expires in 10 minutes.
• The GitHub key is a dedicated, least-privilege key you can revoke any time; it never leaves the worker machine.