bitterbot-desktop

Most AI agents are stateless wrappers around an LLM API. Close the terminal, and they forget you exist.

Bitterbot is a persistent personal agent that runs on your own machine. It remembers you across sessions, acts through real tools (a browser, code execution, the chat apps you already use), and keeps working between conversations. While idle it dreams: consolidating memory, distilling workflows that verifiably worked into reusable skills, and preparing for what you are likely to ask next. It grades that dreaming by whether the results get used.

Its memory, identity and skills are files and a SQLite database on your disk. The code is MIT. The model is whichever one you choose.

The personal agent, without the platform owner

In September 2026, Meta Muse and OpenAI dots made persistent personal agents mainstream: AI that remembers its user, acts through tools, and keeps working after the app is closed. Both run on a cloud computer the vendor operates, on the vendor's model.

Bitterbot has been building toward the same category in public since March 2026 (first commit, changelog), from a different premise: the agent, its memory, its identity and what it learns should belong to the person it works for.

Muse is what Meta's personal agent looks like. Dots is what OpenAI's personal agent looks like. Bitterbot is what yours looks like.

If what interests you about Muse or dots is a persistent AI that remembers you and acts on your behalf, Bitterbot explores the same category as an open-source, self-hosted, model-independent system.

Vendor columns reflect each company's public launch material as of October 2026. Corrections welcome in an issue.

To be straight about the other direction: Muse and dots offer zero-setup hosting, first-party frontier models, mobile apps, large catalogs of prebuilt app connectors, and (Muse) card checkout. Bitterbot runs from source or as a self-hosted container today, and its gaps are listed in LIMITATIONS.md.

"Local-first" here means the runtime, the state and the memory are yours. If you configure a cloud model provider, your prompts (including recalled memories) go to that provider; with a local model they stay on the machine. Every default outbound connection is listed with its off switch in docs/network/egress.md.

And that's where the similarities end

A persistent agent you can self-host is the entry point. Bitterbot's architecture is built around a longer loop:

experience → memory → dreaming → skill candidates → validation → peer exchange → new experience

Remembers. Long-term memory that changes with use: facts decay unless they keep mattering, confidence grows with corroboration and drops on contradiction, a typed knowledge graph tracks the people and projects in your life, and a small ledger of canonical facts is always in context. How it remembers ↓

Learns. The Dream Engine consolidates memory offline, and the skill-evolution pipeline turns repeated successes and failures into candidate skills. Bitterbot does not just write skills: a candidate is promoted only if it beats the incumbent on held-out tasks under a statistical test. Nothing is promoted on a model's opinion of its own work. How it learns ↓

Connects. Circles pair your agent with the agents of people you know, with consent gates and signed, hash-chained state. A2A makes it reachable by other agent frameworks. A wallet and x402 let it pay and be paid. Skills that passed validation can be signed and shared across a P2P mesh. How it connects ↓

Most personal agents learn in isolation. Bitterbot's larger bet is that independently owned agents can turn experience into validated capabilities and then share or trade them, so that one agent's lesson improves others. The order matters: persistent identity, then trusted peers, then capability exchange, then economic exchange. The first two work today. The last two are implemented, opt-in and early (see The Agent Economy).

Quick Start

Runtime: Node ≥ 22.12 · Package manager: pnpm

No pnpm yet? It ships with Node via corepack:

corepack enable pnpm || npm install -g pnpm

git clone https://github.com/Bitterbot-AI/bitterbot-desktop.git && cd bitterbot-desktop
bash scripts/setup-deps.sh    # system deps: ffmpeg, ripgrep, jq, etc.
pnpm install
pnpm exec playwright install --with-deps chromium   # browser automation

Windows: use WSL2, and clone into the Linux filesystem (~/bitterbot-desktop), not /mnt/c/...: the 9p mount makes boots dramatically slower (43x measured).

Always-on server? Run the public container image ghcr.io/bitterbot-ai/bitterbot-desktop, or the Fly.io and VPS templates, and finish setup in the browser: docs/platforms/docker.md.

Run the onboarding wizard. It walks you through model auth (API keys), memory embeddings, web search, channels, wallet, and workspace setup, then starts the gateway + Control UI for you and opens the browser. When it finishes, Bitterbot is already running; there's nothing else to type.

pnpm bitterbot onboard

Open http://127.0.0.1:19001 to reach the Bitterbot Control UI where you chat, view dreams, manage skills, and monitor the agent. The gateway serves the UI itself, and the P2P orchestrator starts automatically: one process, one port.

Start it yourself later (or if you skipped the wizard's auto-start):

pnpm start:all              # starts the gateway (which serves the Control UI); skips if already up

start:all builds dist/entry.js and stages the Control UI on first run if they're missing, so no separate pnpm build step is required.

Developing on the source? Use watch mode instead:

pnpm dev:all                # gateway (tsdown --watch) + Vite hot-reload, color-tagged logs
# or two terminals:
pnpm gateway:watch          # Terminal 1: auto-rebuilds on TS changes
cd desktop && pnpm dev      # Terminal 2: Vite hot-reload

The orchestrator (P2P sidecar) is spawned automatically by the gateway, so you do not need to start it separately.

The Control UI needs no wiring: the gateway serves it and hands it the auth token over a same-origin loopback endpoint, so opening http://127.0.0.1:19001/ on the machine that runs the gateway just works. From another machine, open the same URL through an SSH tunnel (ssh -N -L 19001:127.0.0.1:19001 user@host), or use the first-run screen to point the UI at a remote gateway with its token from ~/.bitterbot/bitterbot.json → gateway.auth.token. (desktop/.env is only a development-mode override for pnpm dev:all.)

If you prefer to configure everything by hand instead of using the wizard:

cp .env.example .env
# Edit .env with your Anthropic API key (ANTHROPIC_API_KEY)
# and optionally: TAVILY_API_KEY, BRAVE_API_KEY, OPENAI_API_KEY, NEARAI_API_KEY

Then run pnpm bitterbot configure to set gateway port/bind/auth, channels, and other options interactively. Or edit ~/.bitterbot/bitterbot.json directly.

You can also talk to your agent from the terminal:

pnpm bitterbot agent --agent main --message "What have you learned about me so far?"

A Biological Brain