Quick start

Requirements

• macOS: arm64 / x64
• Windows: x64
• Linux: x64 (AppImage)
• From source: Node ≥ 22.13 and pnpm

Download

Get builds from GitHub Releases:

Platform	Artifact
macOS	.dmg / .zip (arm64 and x64)
Windows	NSIS installer (x64)
Linux	.AppImage (x64)

Early builds may be unsigned. macOS Gatekeeper or Windows SmartScreen may block the first open — allow in system settings only if you trust the download.

Three steps

1. Install and open OkBot (single instance: launching again focuses the existing window).
2. Settings → Models: add a provider and API key, pick a default model (BYO).
3. Create an assistant (name, avatar, persona) and start chatting. Most tools run without a prompt by default; if you set a tool to ask (or hit a forced-confirm / MCP call), allow once, remember a rule, or deny.

Optional next: Settings → Client → Gateway list for a remote personal gateway; Settings → Computers for remote executors; in-app Marketplace for starter assistants; okbot serve when you want the gateway always on (see Gateway).

Data directory: ~/.okbot/ on the active gateway host (custom instances: okbot serve --data-dir).

From source

git clone https://github.com/shuzheng/okbot.git
cd okbot
pnpm install
pnpm approve-builds --all   # if pnpm 11 reports ignored build scripts
pnpm dev

Headless gateway: build the gateway package, then okbot serve (multi-instance needs paired --port and --data-dir). See the repo README / GUIDE.md and Gateway.

Self-host the gateway (Docker / Kubernetes)

Desktop stays a native install. To run the headless gateway (okbot serve) in Docker or Kubernetes (Helm), see the product repo docs/install-docker-k8s.md. Packaging lives under deploy/docker/ and deploy/helm/okbot/. The image does not include Electron; attach the desktop client to that remote gateway. See also Gateway.