README.md

September 7, 2026 · View on GitHub

Your own AI coworkers, on your own Mac.

Create agents, give them a computer, watch them work, and take the wheel when you want to. Bring any model — OpenAI, Anthropic, Google, xAI, or a model running locally through Ollama. Your agents, their files, and their browsers stay on this Mac.

In v1 your conversation history is the exception: it is stored by CopilotKit, the service xBot's engine is built on. ADR-0007 says why, and onboarding says so before you type a key.

What it is

xBot is a native macOS app. You download a .dmg, drag it to Applications, and open it. It walks you through everything else.

Behind the app, a full agent platform runs in containers on your Mac: each agent gets its own computer with its own browser, its own files, and only the tools you grant it. Every action an agent takes is decided against a policy before it happens and recorded after.

You never open a terminal. You never edit a configuration file. You never read a log.

Why it exists

Two good things existed separately.

OpenBot is a serious, well-built, self-hosted agent platform — per-agent isolation, an action gateway, a real audit trail. It is also a developer template: you clone a repository, copy an .env, fill in credentials, and run a shell script.

Grok Bot showed what the consumer shape of this looks like — a chat app with a rail of agents, a live view of what each one is doing, and settings you can actually find.

xBot is the fusion: OpenBot's engine, a native Mac experience, and no lock-in to any single model vendor.

Status

In development. The native Mac client ships rail, conversation, composer, panel, command palette, onboarding (five steps), in-window settings (General, Models, Agents, Computer, Usage, Updates, Advanced), agent settings (model picker, plugins reach, handoff grants), plugins admin webview — all wired to RuntimeController and HTTPEngineClient when the engine is running. The app pulls a pinned ghcr engine digest from manifests/engine-stable.json on start. M2's model router has been driven live against a real vendor — per-run selection, a deployment fallback, an openai-compatible endpoint in the same process, and a bogus model name rejected by the vendor rather than silently substituted — and the hop the product actually uses, through copilot.ts and the AG-UI client, is covered by a test that asserts on the posted body. A second live vendor, M6 VM validation, and M7 signing/notarization remain open.

Start at docs/README.md. The current milestone table is in docs/12-roadmap.md.

Run the Mac app locally

cd apps/mac && swift run          # debug: stub engine, full UI, no Docker
cd apps/mac && XBOT_USE_RUNTIME=1 swift run   # debug: real runtime path — Start in the UI
cd apps/mac && swift test         # 235 unit tests (SwiftPM)
scripts/build-engine-image.sh     # dev: build xbot/engine:1 for the runtime path
scripts/check-engine-health.sh    # dev: read-only /health check once the engine is up
scripts/generate-app-icon.sh      # compile xBot.icon → Assets.car + xBot.icns
scripts/bundle-mac-app.sh          # wrap release binary in XBot.app (after swift build -c release)

Release builds always use the runtime path. On start the app fetches the pinned engine manifest (manifests/engine-stable.json) and pulls ghcr.io/masteryoav/xbot-engine@sha256:…. For local development, build xbot/engine:1 with scripts/build-engine-image.sh or set XBOT_ENGINE_IMAGE=xbot/engine:1. Bearer token and encryption key are generated on first run and held in the Keychain. First Start can take up to ~2 minutes while Postgres initializes. If a start fails mid-boot, docker rm -f xbot-engine clears the container for a clean retry (volumes are kept).

Documentation


Vision	What we are building, for whom, and what we are not building
Architecture	Services, ports, data flow
The OpenBot fork	What we inherit and what we have to change
Model providers	Per-agent model selection across every vendor
The Mac app	Swift target layout and module boundaries
Onboarding	The first-run flow, screen by screen
Container runtime	Driving containers without the user knowing
Design system	Tokens, type, motion, materials
UI specification	Every screen
Security	Keys, secrets, isolation, what never gets written down
Packaging	Signing, notarization, updates
Roadmap	Milestones
Launch checklist	What is left between here and a download, in order
Engine environment mapping	App settings → container env vars
Decisions	ADRs — read these before disagreeing with anything above

Built on OpenBot

Licence

MIT.