Concepts

Three layers

OkBot has three layers:

1. Desktop client — desktop app or browser Web UI. One client can save many personal gateways under Settings → Client → Gateway list and switch which one is active (client 1 : N gateways). Only one gateway is attached at a time; some switches need a restart.
2. Personal gateway — the Personal Agent host that owns the data root on that machine (default ~/.okbot). Deploy on a machine you choose: started by the desktop app, or headless with okbot serve (optional --port + --data-dir for multiple instances).
3. Runtime computers — one gateway registers many runtime computers under Settings → Computers (local + remote sandbox-agent) (gateway 1 : N runtime computers). Tools can run on a chosen computer.

In short: client, personal gateway, runtime computers — one client can switch among gateways; one gateway can host many runtime computers.

Keep the gateway deployed and running for continuous service; send work across registered runtime machines. That is an always-on Personal Agent across multiple computers when the gateway is up (no running gateway means no always-on). Schedules likewise fire only while the gateway is running.

Assistants (bots)

Named assistants: name, avatar, persona (SOUL.md), optional private skills and memory. The sidebar manages the roster. Assistants can keep long-running task checklists, schedules, and a resources library / HTML notes (see Evolution, Assistants).

Collaboration: Mesh and Squad

• Mesh: in 1:1 chats, an assistant can ask roster peers for help (status lines + read-only transcript).
• Squad: form when needed; you assign work, a captain orchestrates, members can run in parallel. Day-to-day 1:1 usually uses Mesh.

Sessions

Each assistant / squad has its own session log (jsonl). Supports paged scroll-up, quotes, copy, retry, and in-place bubble emoji reactions (on the message record — not a new timeline bubble).

Tools and approval

Assistants can call tools on local or remote runtime computers (shell, files, web, schedules, long-running task progress, HTML notes, and more). Out of the box, most tools auto-allow (including run_shell / write_file / edit_file); HITL cards appear when you set a tool to ask. Forced-confirm actions (schedule create/delete, memory forget) and every MCP call when MCP is on also require approval. When a tool is set to ask, allow once, remember an auto-approval rule (AAR), or deny.

MCP extensions master switch is on by default (an existing explicit off stays off); MCP tools always ask; auto-approval rules apply to built-in tools.

Security protection: path prefixes and the dangerous-command denylist are soft guards, not isolation — local tool execution is not an OS sandbox (no seatbelt/container by default). Relative reads/writes default under the current assistant/squad work root (~/.okbot/data/<memberId>); run_shell defaults cwd to temp/ under that root; library files use resources/…, and overwrites of durable session/memory state files are blocked. Optional Agent input/output and tool-result guardrails in Settings (off by default). Tighter posture: set dangerous tools to ask, keep LAN bind off, leave MCP off, and tighten allowed paths.

Data directory

Data lives on the active gateway host data root (default ~/.okbot/: assistants, sessions, memory, gateway settings, computers list, …). Client shell preferences (theme, language, gateway list, …) stay in local client.json; each gateway keeps its own settings and data when you switch.

Secret files use tightened permissions. A gateway can hold many access tokens (with quotas and usage).