Skip to main content

​
Remote access (SSH, tunnels, and tailnets)

This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it.
  • For operators (you / the macOS app): SSH tunneling is the universal fallback.
  • For nodes (iOS/Android and future devices): prefer the Gateway Bridge when on the same LAN/tailnet (see Discovery).

​
The core idea

  • The Gateway WebSocket binds to loopback on your configured port (defaults to 18789).
  • For remote use, you forward that loopback port over SSH (or use a tailnet/VPN and tunnel less).

​
Command flow (what runs where)

One gateway daemon owns state + providers. Nodes are peripherals. Flow example (Telegram → node):
  • Telegram message arrives at the Gateway.
  • Gateway runs the agent and decides whether to call a node tool.
  • Gateway calls the node over the Bridge (node.* RPC).
  • Node returns the result; Gateway replies back out to Telegram.
Notes:
  • Nodes do not run the gateway daemon. Only one gateway should run per host.
  • macOS app “node mode” is just a node client over the Bridge.

​
SSH tunnel (CLI + tools)

Create a local tunnel to the remote Gateway WS: 
ssh -N -L 18789:127.0.0.1:18789 user@host
With the tunnel up:
  • clawdbot health and clawdbot status --deep now reach the remote gateway via ws://127.0.0.1:18789.
  • clawdbot gateway {status,health,send,agent,call} can also target the forwarded URL via --url when needed.
Note: replace 18789 with your configured gateway.port (or --port/CLAWDBOT_GATEWAY_PORT).

​
CLI remote defaults

You can persist a remote target so CLI commands use it by default: 
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token"
    }
  }
}
When the gateway is loopback-only, keep the URL at ws://127.0.0.1:18789 and open the SSH tunnel first.

​
Chat UI over SSH

WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects directly to the Gateway WebSocket.
  • Forward 18789 over SSH (see above), then connect clients to ws://127.0.0.1:18789.
  • On macOS, prefer the app’s “Remote over SSH” mode, which manages the tunnel automatically.

​
macOS app “Remote over SSH”

The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding). Runbook: macOS remote access.