30 lines
2.0 KiB
Markdown
30 lines
2.0 KiB
Markdown
# 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.
|