clawdbot/docs/mac/remote.md

Remote Clawd mode (Dec 2025)

What it is

• Run the Clawdis relay on another machine (Linux/macOS) reachable over SSH while the macOS app keeps TCC, notifications, and UI.
• You can toggle Local vs Remote in Settings → General → Clawdis runs; remote adds fields for SSH target, identity file, and project root.
• We recommend running a Tailscale node on both sides so the target is reachable even off-LAN.

Requirements

• SSH access with public-key auth (BatchMode=yes); set user@host[:port] and an identity file.
• The remote host must have a working clawdis install in the project root you specify.
• clawdis-mac is still used for permissioned actions; the CLI path is auto-discovered on the remote via command -v + common prefixes.

How it works

• The app builds commands through the new runner:
  • clawdis status/health/agent/relay are wrapped in ssh … /bin/sh -c '<cd project && clawdis …>' with CLI path lookup.
  • clawdis rpc is tunneled over a long-lived SSH process so web chat and the app’s Agent tab stay responsive.
• Local TCC flows remain unchanged; if the remote agent needs local permissions, it should SSH back here and invoke clawdis-mac … (same CLI surface).

Setup steps

1. Open Settings → General → Clawdis runs and pick Remote over SSH.
2. Fill SSH target, Identity file, and Project root (where clawdis lives on the remote).
3. Click Test remote; it runs clawdis status --json remotely and caches the resolved CLI path.
4. Run onboarding’s WhatsApp login step on the machine where the relay will run (remote if remote mode is enabled).

Notes

• Connection strings accept user@host:port; leading ssh is stripped if pasted from a shell snippet.
• Project root defaults to the path you enter; if blank, no cd is issued before the relay command.
• The remote log path remains /tmp/clawdis/clawdis.log; view it via SSH if you need details.
• If you switch back to Local, existing remote state is left untouched; re-run Test remote when switching again.