FAQ

Blocked on first open?

Early builds may be unsigned. On macOS / Windows, allow the downloaded app in system settings only if you trust the source.

Where is data stored?

Chat, memory, and settings default to ~/.okbot on the active gateway host (or the custom directory for okbot serve --data-dir). Model requests go to the provider baseURL you configure.

Where do models come from?

Bring your own (BYO). Requests go to endpoints you configure. OkBot does not host inference.

How do I switch gateways / use many machines?

Settings → Client → Gateway list to switch saved gateways (restart may apply). Settings → Computers to register many computers under one gateway (including remote sandbox-agent). See Gateway and Remote computers.

Can I run multiple gateway instances?

Yes. Pair okbot serve --port <port> --data-dir <dir>. The desktop app attaches to ~/.okbot by default. See Gateway.

How do gateway tokens work?

Settings → Gateway service: create many named tokens (user / admin) with message and token quotas; inspect per-token usage by assistant / squad.

Why did my schedule not fire?

Schedules are checked only while a gateway owner process is running (desktop-started gateway or okbot serve). Nothing fires while it is stopped; after restart, overdue next-times get one catch-up run. See Evolution.

What are long-running tasks?

Assistants keep a durable checklist: decompose steps, persist progress, resume after interruption, and continue (multi-task; backlog / in progress / finished). Separate from schedules and HTML notes. See Evolution.

Notes vs tasks?

Timed / recurring → schedules; do-now or unscheduled backlog work → long-running tasks; durable documents to maintain → HTML notes (resources library). See Assistants and Evolution.

How does MCP approval work?

MCP master switch is on by default; every MCP tool call needs human approval. Auto-approval rules apply to built-in tools. You can turn the master switch off in Settings; Marketplace connector presets still need enabling individually.

What is in an exported assistant?

.okbot includes persona and skills (plus name / avatar). Chat, memory, and secrets stay on the gateway host.

What is “Wrapping up”?

Post-turn silent upkeep of persona / skills / memory (memories start as candidates, then consolidate to durable; prompts inject pinned and relevant durables only); it applies on the next prompt. See Evolution.

What does security protection cover?

Path prefixes and the dangerous-command denylist are soft guards, not isolation — local execution is not an OS sandbox. Relative reads/writes default under the current assistant/squad work root; run_shell defaults cwd to temp/; library files use resources/…, and overwrites of durable state like session.jsonl are blocked. Most tools auto-allow out of the box (including shell / file writes); HITL appears when you set a tool to ask, or for forced-confirm actions (schedule create/delete, memory forget) / MCP. Settings → Security also has Tool | Agent tabs: optional Agent input/output and tool-result guardrails (off by default). Tighter posture: set dangerous tools to ask, keep LAN bind off, leave MCP off, tighten allowed paths.

Marketplace status?

In-app Marketplace (assistants / connectors) is available. The site community marketplace page is coming soon. You can also export / import .okbot, or paste a public GitHub / .okbot source.

How do I back up?

On the desktop app that owns the local gateway: Settings → Gateway service → Data to export / restore gateway data (secrets can be omitted by default). Confirm no assistant is working or waiting for approval first. Attach window / Web UI do not expose backup routes.

More

File issues on GitHub Issues, or read GUIDE.md in the repo.