let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add docs:list helper and front matter

Browse Source
This commit is contained in:
Peter Steinberger
2025-12-09 17:51:05 +00:00
parent b3d4e5cfdf
commit bc3a14cde2
44 changed files with 436 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/remote.md
View File

@@ -1,9 +1,14 @@
---
summary: "Remote mode topology using SSH control channels between gateway and mac app"
read_when:
- Running or troubleshooting remote gateway setups
---
# Remote mode with control channel
This repo supports “remote over SSH” by keeping a single relay (the master) running on a host (e.g., your Mac Studio) and connecting one or more macOS menu bar clients to it. The menu app no longer shells out to `pnpm clawdis …`; it talks to the relay over a persistent control channel that is tunneled through SSH.
This repo supports “remote over SSH” by keeping a single gateway (the master) running on a host (e.g., your Mac Studio) and connecting one or more macOS menu bar clients to it. The menu app no longer shells out to `pnpm clawdis …`; it talks to the gateway over a persistent control channel that is tunneled through SSH.
## Topology
- Master: runs the relay + control server on `127.0.0.1:18789` (in-process TCP server).
- Master: runs the gateway + control server on `127.0.0.1:18789` (in-process TCP server).
- Clients: when “Remote over SSH” is selected, the app opens one SSH tunnel:
- `ssh -N -L <localPort>:127.0.0.1:18789 <user>@<host>`
- The app then connects to `localhost:<localPort>` and keeps that socket open.
@@ -14,10 +19,10 @@ This repo supports “remote over SSH” by keeping a single relay (the master)
2) Open TCP socket to the local forwarded port.
3) Send `ping` to verify connectivity.
4) Issue `health`, `status`, and `last-heartbeat` requests to seed UI.
5) Listen for `event` frames (heartbeat updates, relay status).
5) Listen for `event` frames (heartbeat updates, gateway status).
## Heartbeats
- Heartbeats always run on the master relay.
- Heartbeats always run on the master gateway.
- The control server emits `event: "heartbeat"` after each heartbeat attempt and keeps the latest in memory for `last-heartbeat` requests.
- No file-based heartbeat logs/state are required when the control stream is available.
@@ -26,7 +31,7 @@ This repo supports “remote over SSH” by keeping a single relay (the master)
## Failure handling
- If the tunnel drops, the client reconnects and re-issues `ping`, `health`, and `last-heartbeat` to refresh state (the mac app shows “Control channel disconnected”).
- If the control port is unavailable (older relay), the app can optionally fall back to the legacy CLI path, but the goal is to rely solely on the control channel.
- If the control port is unavailable (older gateway), the app can optionally fall back to the legacy CLI path, but the goal is to rely solely on the control channel.
## Test Remote (in the mac app)
1) SSH reachability check (`ssh -o BatchMode=yes … echo ok`).
@@ -39,4 +44,4 @@ This repo supports “remote over SSH” by keeping a single relay (the master)
## Files to keep in sync
- Protocol definition: `docs/control-api.md`.
- App connection logic: macOS `Remote over SSH` plumbing.
- Relay control server: lives inside the Node relay process.
- Gateway control server: lives inside the Node gateway process.