Docs menuGateway

Gateway

The personal gateway is the middle of three layers: the Personal Agent host that owns ~/.okbot on that machine, runs chat and tools, and exposes the local HTTP API. The desktop app and okbot serve share the same implementation. One listener per data root (default ~/.okbot).

Relationships:

  • Client 1 : N gateways — the desktop client can save many gateways and switch which one is active (one at a time).
  • Gateway 1 : N runtime computers — that gateway registers many runtime computers (see Remote computers).

Keep the gateway running so the Personal Agent can keep serving; register many runtime machines under it so tasks can land across them. Always-on means the gateway is up.

Client and gateway (1 : N)

  • Local default: on cold start with no gateway, the desktop app starts one; if OkBot is already listening (e.g. okbot serve), the window attaches — closing the window keeps the gateway running.
  • Many gateways: add URL + access token under Settings → Client → Gateway list, probe, then save; click Use to switch. Switching back to local may require a restart.
  • Client preferences (including the gateway list) stay on this machine; chat, assistants, memory, and the computers list always live on the active gateway host data root (default ~/.okbot).
  • The desktop app auto-attaches only the default data root (~/.okbot) and its configured port; custom --data-dir instances need a manual entry in the gateway list.

Gateway service settings

Settings → Gateway → Gateway service:

  • Port, LAN gateway, Serve Web UI
  • Gateway tokens: create any number of named tokens. Each has a name, role (user / admin), secret, plus daily/total message quotas and daily/total token quotas (0 or empty = unlimited). Open the usage view for that token’s chat counts and token spend per assistant / squad.
  • Token charset is [A-Za-z0-9_-]. Existing tokens are reused on ordinary save / attach; “Regenerate” in settings is a separate action.
  • A token is access to that gateway (chat, tool approvals, persona / memory / skills, depending on role). Keep it private.

Binds 127.0.0.1 by default (Host checks when LAN is off). Auth: Authorization: Bearer <token> or X-OkBot-Token (except GET /v1/health). There is no unhardened public internet entry; LAN still requires the token.

okbot serve

Headless gateway only:

okbot serve

Uses saved port, bind, token, and Web UI flag. Existing tokens are reused. Prints address and token on success; exits if OkBot is already listening. Stop with Ctrl+C.

Multi-instance (custom data root)

Run several gateway instances on one machine: --port and --data-dir must be paired (or omit both for default ~/.okbot + default port, usually 18765).

okbot serve --port 19001 --data-dir ~/okbot-alt
okbot status --port 19001 --data-dir ~/okbot-alt
okbot stop --port 19001 --data-dir ~/okbot-alt

Start is refused if the port or data-dir lock is already held. status / stop / restart require the same paired flags for a custom instance.

Useful CLI (see also okbot help): serve, status, stop, restart, config, token, data, version.

LAN and Web UI

LAN gateway binds 0.0.0.0 (still token-auth). Serve Web UI hosts the same frontend as desktop; open the printed URL and log in with the token (avoid leaving the token in the URL long-term).

HTTP API (summary)

Common capabilities: message an assistant / squad (optional SSE), lists and tool approvals, abort a turn, POST /v1/rpc/:op (CRUD, memory / skills, …), GET /v1/events (roster and turn events).

curl -N -X POST "http://127.0.0.1:<port>/v1/bots/<botId>/messages" \
  -H "Authorization: Bearer $OKBOT_TOKEN" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello"}'

One-click copy curl does not put the real token on the clipboard; the placeholder is $OKBOT_TOKEN.

Docker / Kubernetes

Run the headless gateway with Docker Compose or Helm (desktop is not packaged). See the product repo docs/install-docker-k8s.md, or start from Quick start.

Capability boundaries

Attach window / browser gateway: chat, approvals, memory, skills, Marketplace install, force compress, and more.

Attach / browser limits: path-based pack import/export, backup/restore, and some gateway config depend on token role; Whisper STT is available on the desktop app. User tokens are narrower; admin tokens manage full gateway settings.

Computers: Remote computers. Backup: FAQ.

Content is derived from the OkBot product repo and evolves with the product.

PreviousConceptsNextRemote computers