agentproto serve

agentproto serve [--workspace <dir>] [--port <n>] [--bind <ip>]
                 [--connect <url> [--token <jwt>] [--label <name>]]
                 [--allow-origin <url> …] [--interactive | -i]

Runs the agentproto daemon in the foreground. Boots a local HTTP gateway (sessions, MCP, events SSE, optional PTY WS) on --port (default 18790) and, if --connect <url> is set, opens an outbound WebSocket tunnel to a host so cloud-side operators can drive this machine.

For running it as an OS-managed background service, see daemon.md — same binary, same flags, just wrapped in launchd / systemd.

Flags

Token resolution (--connect mode)

1. --token <jwt>
2. $AGENTPROTO_TOKEN
3. ~/.agentproto/credentials.json[<host>] (set by auth login)

Expired credentials are still sent — the host's 401 surfaces a clearer error than a silent disconnect — but serve prints a warning suggesting agentproto auth login --host <host>.

Origins

By default, any Origin that resolves to 127.0.0.1:* / localhost:* is trusted, plus anything in --allow-origin and daemon.allowedOrigins. Set daemon.strictOrigins=true (via config) to drop the localhost default and trust only the explicit allowlist — for hardened / shared-host setups.

The Bearer-token check on /mcp and other routes is independent of the Origin check — a valid token bypasses the Origin allowlist.

Modes

Local-only

agentproto serve
agentproto serve --workspace ~/code/my-project --port 18791

No tunnel, no --connect. Local clients (web spawn dialogs running in the browser, agentproto sessions, MCP clients) talk to http://127.0.0.1:18790. Discover the URL + token from ~/.agentproto/runtime.json (written at boot).

Tunnel

agentproto auth login --host wss://guilde.work
agentproto serve --connect wss://guilde.work/api/v1/agentproto/tunnel

Boots the same local gateway and opens a WS to the host. Every tunnel-driven spawn is also registered locally — operators dispatching from the cloud land in the same /sessions list as local ones, so the LocalDaemonSessionsCard, agentproto sessions, etc. all see them.

Reconnect-with-backoff (1s → 30s ceiling) is built in. The local gateway stays up across reconnects; only the WS cycles. Keep-alive pings every 30s prevent reverse-proxies (Cloud Run, …) from closing idle sockets.

Interactive (--interactive / -i)

agentproto serve --workspace ~/code --interactive

Spawns the watch TUI as a child after boot, inheriting stdio. Quitting the TUI (q / Ctrl-C) tears the daemon down. Use the PTY-attach detach chord (Ctrl-] then q) to leave the TUI while keeping the daemon running.

Boot banner

─ agentproto · gateway up · http://127.0.0.1:18790 ─
  workspace    ~/code/my-project
  pty          enabled (node-pty)
  origins      localhost:* only (default)
  endpoints    /mcp · /sessions · /events · /sessions/:id/pty (WS)
  mode         tunnel → wss://guilde.work/api/v1/agentproto/tunnel

Each line is a quick sanity check:

• pty — whether node-pty was loadable. Without it, PTY-backed session routes return 501. Install with npm i -g node-pty.
• origins — STRICT when daemon.strictOrigins=true. Empty strict allowlist is highlighted red (everything 401s except Bearer-token requests).
• mode — local-only or tunnel → <url>.

When to use serve vs daemon install

• agentproto serve — run-as-foreground, Ctrl-C to stop. Good for development, debugging the tunnel, --interactive TUI.
• agentproto daemon install — same code, run by launchd / systemd. Survives logout/login and crashes. Pick this for "always-on" tunnels.

Both read the same ~/.agentproto/config.json.

Shutdown

SIGINT, SIGTERM, and SIGHUP all trigger a clean shutdown sequence: stop accepting new requests → close the tunnel → stop the gateway → delete the daemon's runtime.json. The exit banner is ── shutting down (<signal>) ──.

Files written

Stale runtime.json files (dead PID) in registered workspaces are swept at boot — they confuse discovery otherwise.