Remote Clawdis (macOS ⇄ remote host)

Updated: 2025-12-08

This flow lets the macOS app act as a full remote control for a Clawdis gateway running on another host (e.g. a Mac Studio). All features—health checks, permissions bootstrapping via the helper CLI, Voice Wake forwarding, and Web Chat—reuse the same remote SSH configuration from Settings → General.

Modes

Local (this Mac): Everything runs on the laptop. No SSH involved.
Remote over SSH: Clawdis commands are executed on the remote host. The mac app opens an SSH connection with -o BatchMode plus your chosen identity/key.

Prereqs on the remote host

Install Node + pnpm and build/install the Clawdis CLI (pnpm install && pnpm build && pnpm link --global).
Ensure clawdis is on PATH for non-interactive shells. If you prefer, symlink clawdis-mac too so TCC-capable actions can run remotely when needed.
Open SSH with key auth. We recommend Tailscale IPs for stable reachability off-LAN.

macOS app setup

Open Settings → General.
Under Clawdis runs, pick Remote over SSH and set:
- SSH target: user@host (optional :port).
- Identity file (advanced): path to your key.
- Project root (advanced): remote checkout path used for commands.
Hit Test remote. Success indicates the remote clawdis status --json runs correctly. Failures usually mean PATH/CLI issues; exit 127 means the CLI isn’t found remotely.
Health checks and Web Chat will now run through this SSH tunnel automatically.

Web Chat over SSH

The mac app serves the WebChat assets locally (from the app bundle) and connects to the gateway over the forwarded WebSocket control port (default 18789).
The gateway’s own loopback WebChat HTTP server (default 18788, see webchat.port) is not required in remote mode.
Keep the feature enabled in Settings → Config → Web chat. Disable it to hide the menu entry entirely.

Permissions

The remote host needs the same TCC approvals as local (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Run onboarding on that machine to grant them once.
When remote commands need local TCC (e.g., screenshots on the remote Mac), ensure clawdis-mac is installed there so the helper can request/hold those permissions.

Run clawdis login --verbose on the remote host. Scan the QR with WhatsApp on your phone.
Re-run login on that host if auth expires. Health check will surface link problems.

Troubleshooting

exit 127 / not found: clawdis isn’t on PATH for non-login shells. Add it to /etc/paths, your shell rc, or symlink into /usr/local/bin//opt/homebrew/bin.
Health probe failed: check SSH reachability, PATH, and that Baileys is logged in (clawdis status --json).
Web Chat stuck: confirm the gateway is running on the remote host and webchat.enabled is true; ensure the forwarded port matches Settings → Config. Since RPC is in-process, PATH is no longer a factor.
Voice Wake: trigger phrases are forwarded automatically in remote mode; no separate forwarder is needed.

Notification sounds

Pick sounds per notification from scripts with the helper CLI, e.g.:

clawdis-mac notify --title "Ping" --body "Remote gateway ready" --sound Glass

There is no global “default sound” toggle in the app anymore; callers choose a sound (or none) per request.

3.5 KiB Raw Blame History Unescape Escape