clawdbot/docs/webchat.md

Web Chat (loopback + SSH tunnel)

Updated: 2025-12-08

What shipped

• The relay now starts a loopback-only web chat server automatically (default port 18788, configurable via webchat.port).
• Endpoints:
  • GET /webchat/info?session=<key> → {port, sessionId, initialMessages, basePath} plus history from the relay’s session store.
  • GET /webchat/* → static Web Chat assets.
  • POST /webchat/rpc → runs the agent in-process and returns { ok, payloads?, error? } (no CLI spawn, no PATH dependency).
• The macOS app simply loads http://127.0.0.1:<port>/webchat/?session=<key> (or the SSH-forwarded port in remote mode). No Swift bridge is used for sends; all chat traffic stays inside the Node relay.
• Initial messages are fetched from /webchat/info, so history appears immediately.
• Enable/disable via webchat.enabled (default true); set the port with webchat.port.

Security

• Loopback only; remote access requires SSH port-forwarding.
• No bearer token; the trust model is “local machine or your SSH tunnel”.

Failure handling

• Bootstrap errors show in-app (“Web chat failed to connect …”) instead of hanging.
• The mac app logs tunnel and endpoint details to the com.steipete.clawdis/WebChat subsystem.

Dev notes

• Static assets stay in apps/macos/Sources/Clawdis/Resources/WebChat; the server reads them directly.
• Server code: src/webchat/server.ts.
• CLI entrypoint (optional): clawdis webchat --json [--port N] to query/start manually.
• RPC send path is in-process; the relay does not spawn clawdis or rely on PATH.
• Mac glue: WebChatWindow.swift (bootstrap + tunnel) and WebChatTunnel (SSH -L).

TODO / nice-to-haves

• Enforce token by default once mobile/remote auth flows are in place.
• Stream responses instead of one-shot payloads.
• Expose a readiness endpoint for health checks.