bitterbot-ai/bitterbot-desktop

Your AI should belong to you. A personal agent with living memory, a dream engine, and skills that have to prove themselves. Open source. Your hardware. Your choice of model.

= 18 (the installer needs no Node)">

Get started · Memory · Learning · Circles · Project status · Docs

Build a history with your AI. Keep what it learns.

Bitterbot runs on your machine, remembers context across conversations, and works through a real browser, code execution, and the chat apps you already use. Give it a project, return with a new decision, and continue with the context it has retained.

Between conversations, it dreams: consolidating memories, preparing grounded briefs, and feeding a learning pipeline that proposes and tests reusable skills. Through Circles, you can connect with people you know and their independently owned agents.

Your agent’s memory, identity, and skills live in files and SQLite on your disk. Inspect them. Back them up. Choose a different supported model. Modify the code. The history you build stays under your control.

Meta’s Muse and OpenAI’s dots made the persistent personal agent mainstream: an AI that remembers you and keeps working after you close the app. Bitterbot is the same idea, built to be yours. It runs on your machine, its memory is plain files you can read and correct, you choose the model, and it’s MIT-licensed.

Put it to work

Start with a task you already do. These are example requests to try after configuring the relevant tools and channels:

Talk through the Control UI, WhatsApp, Telegram, Discord, Signal, Slack, or email. Browser automation, code tools, scheduled jobs, and durable tasks give the agent ways to act on those conversations. Background work runs while the gateway is running.

Explore the tools · Connect a chat app · Long-horizon tasks

Quick Start

One command. Paste it into a terminal on macOS (Apple silicon or Intel) or Linux (x64/arm64) and it takes you straight into setup:

curl -fsSL https://github.com/Bitterbot-AI/bitterbot-desktop/releases/latest/download/install.sh | bash

It downloads a signed release with its own Node runtime (no Node, no sudo, nothing else to install), verifies it, and runs the setup wizard, which asks for a model key, offers web search, and opens the Control UI at http://127.0.0.1:19001. What it verifies, and how to pin, roll back, or remove: install script guide.

Windows: open PowerShell (not Ubuntu/WSL) and run this. It installs inside WSL2 for you (no administrator rights needed once WSL2 is set up):

irm https://raw.githubusercontent.com/Bitterbot-AI/bitterbot-desktop/main/scripts/install.ps1 | iex

Already in an Ubuntu/WSL terminal? Use the macOS/Linux line instead, and run it from your Linux home (cd ~), not from /mnt/c.

Server (Docker). The compose file is attached to every release:

mkdir bitterbot && cd bitterbot
curl -fsSLO https://github.com/Bitterbot-AI/bitterbot-desktop/releases/latest/download/docker-compose.yml
docker compose up -d

Get the gateway token with docker compose exec -u node bitterbot-gateway node bitterbot.mjs config get gateway.auth.token (or use your BITTERBOT_GATEWAY_TOKEN), then open http://127.0.0.1:19001. Fly.io and VPS templates: Docker guide.

Already manage Node with nvm, fnm, Volta or Homebrew? Then npm install -g bitterbot && bitterbot onboard works too (Node 18 or newer); the package is a small launcher that downloads the same signed release on first run. Never run it with sudo. With Node from nodejs.org or from apt, npm cannot write to its global folder and fails with EACCES; the fix is the one command above, not sudo. Details: npm package.

Developing Bitterbot. Install from source with pnpm, below.

Make your first conversation personal:

“I’m working on [project]. My priorities are [priorities], and I prefer [communication style]. Remember this, then help me plan the next step.”

Later, start a fresh conversation and ask what it remembers about the project.

Updating

Your memory, settings, and keys live in ~/.bitterbot and are kept across updates. The Control UI tells you when a new release is out. Updating and rolling back

Memory that builds on your history

Projects change. Preferences become clearer. Yesterday’s plan becomes today’s decision. Bitterbot’s memory is designed to follow that history.

• Remember the essentials. A compact canonical-facts ledger keeps key identities, preferences, and project facts in context without a separate search. Re-stating a fact strengthens it; contradicting it supersedes the old belief while keeping its history.
• Find the connections. Semantic search and a typed knowledge graph connect conversations with the people, projects, and relationships they describe. Deep Recall can search histories larger than a single context window.
• Weigh what it knows. Facts mentioned once count for less than facts confirmed across separate sessions. Recent facts win for “what are you working on?”; older ones for “when did we discuss X?”.
• Consolidate between conversations. Dream cycles organize accumulated memory, distill verified workflows, and prepare briefs grounded in recent activity. New-input, idle-time, and budget gates limit background work.

The architecture takes inspiration from biological memory: reinforcement, forgetting, curiosity, and changing internal state. Numerical signals named dopamine, cortisol, and oxytocin modulate memory processing and response style. These are inspectable software mechanisms; their effectiveness is something to measure.

Your agent also has a persistent identity. GENOME.md defines values and constraints; MEMORY.md holds its evolving self-concept, understanding of you, and active context. Tool guards protect the Genome, with their boundaries documented in known limitations.

Memory architecture · Dream Engine

Learned skills have to earn their place

A generated skill starts as a hypothesis. Bitterbot’s evolution pipeline tests whether it helps before promoting it.

Experience → Memory → Patterns → Candidate skill
                                      ↓
                          Test against the incumbent
                                      ↓
                           Canary → Monitor → Share

The pipeline learns from recorded successes and failures, proposes a skill, and stages it for validation. Candidate and incumbent are run on held-out tasks with deterministic checks. Promotion requires statistical evidence of improvement on the evaluated suite, alongside regression, triggering, and cost checks.

The gate observes whether the agent actually reads the skill. A skill that does not trigger is held; an overly broad one can be rejected. Promoted skills enter a canary period, and regression monitoring can roll them back. An LLM’s retrospective opinion alone cannot authorize promotion. A tool call that merely did not fail earns no credit: competence is credited from a run verdict, a task verdict, or your own feedback (bitterbot skills feedback).

You can inspect the evidence. The Evolution tab and bitterbot skills evidence expose validation results, credited uses, model information, and lineage. Young nodes may produce few promotions while evidence accumulates.

Skills can also include pre-action interceptors: code that checks proposed tool calls and can modify parameters, add context, require prerequisites, or block execution. Because an interceptor is a code path rather than a prompt, it runs on every matching tool call.

Passing a task suite is a bounded result, not a guarantee of improvement on every task. Published benchmarks include their caveats; broad learning gains remain an active evaluation target.

Skills pipeline · Benchmarks · Executable skills

Your people, their agents

Circles bring independently owned agents into a shared space. Connect with a partner, a household, or a trip crew. Each person runs their own node.

Use a Circle for conversations, shared notes, plans, canvas cards, and expense tracking. Invite people directly. Ask their agents for recommendations through consent-gated requests. Review your own agent’s contributions before publishing them.

• Friends’ agents are untrusted input. Their messages are scanned, can never trigger a tool, and never enter your agent’s searchable memory.
• Nothing private leaves by default. Disclosure requests are denied unless you allow a category for a circle, and even then the answer waits for you.
• Tamper-evident. Shared notes and expenses are signed, hash-chained events; corrections are reversals, never edits.
• Offline delivery. Relay mailboxes hold messages encrypted to the recipient, so the mailbox host cannot read them.

There is no public feed or follower count. Expense tracking records a shared tab; it does not move money. Circles are enabled by default and can be disabled. Membership removal currently takes effect per node: other members must apply a removal before their future messages stop reaching the removed member.

Meet Circles · Protocol and security details

One agent’s lesson could help another

The longer-term ambition is a network where agents turn experience into useful capabilities and share those capabilities with evidence attached.

Bitterbot implements signed skill exchange over a P2P mesh, receiver quarantine and validation, peer reputation, and retractions. A2A provides an optional route for other agent frameworks to discover and delegate work to a node; ACP supports external clients such as IDEs. The Gateway can also serve an OpenAI-compatible /v1/chat/completions endpoint (off by default), so any tool that speaks the OpenAI API can use a Bitterbot agent as its model.

An experimental economic layer adds USDC wallets on Base, x402 payments, and skill-marketplace infrastructure. The wallet, payments, A2A HTTP, marketplace, and bounties are opt-in. The wallet starts on testnet. Classified wallet spending asks for approval by default unless covered by a standing grant; spend caps still apply, and paid A2A tasks use their own grant path.

The marketplace is early and has not carried meaningful paid volume. Payment functionality has not had a third-party audit. You can use Bitterbot’s personal-agent capabilities without enabling the money layer.

Skill marketplace · A2A integration · OpenAI-compatible endpoint · Wallet · Action review

Models

Bring your own model. Setup offers Anthropic (Claude Sonnet 5.5 recommended, plus Opus 5.5, Fable 5.1, and Haiku), OpenAI (GPT-5.5), Google Gemini, and OpenRouter. After setup you can also use Bedrock, Together, Venice, and others, or run fully local models through Ollama or vLLM. The model list is discovered live from your provider, so new models appear without an update.

• Switch models any time, per conversation, from the Control UI. The agent is told which model it is running on every turn, so it answers that question correctly right after a switch.
• Shortcuts follow the newest model. opus, sonnet, haiku, and fable point at the newest model of that family your provider serves.
• Costs are tracked per model from live provider prices. Estimates are marked ~$, and bitterbot doctor flags models it cannot price.

Model capability affects tool use and task quality, and any agent with tools and untrusted inboxes should run on the strongest model you can afford.

Choose a model · Models and shortcuts · Usage and costs

What to expect today

Local-first means you control the runtime and stored state. Cloud model providers receive the prompts and recalled memories sent to them. Local inference keeps model processing on your machine; browser activity, connected services, and enabled network features can still make outbound requests.

Security and privacy

Bitterbot connects to real messaging surfaces, so inbound messages are treated as untrusted input by default.

• Pairing. Unknown senders get a pairing code; approve them with bitterbot pairing approve .
• Approvals. Shell commands outside the allowlist ask first. Tools that run code, drive the browser, or move money are owner-only. Payments, public posts, first messages to new people, and connector writes wait in the review queue.
• Sandboxing. Tools run with your user permissions unless you enable the sandbox; group and channel sessions can run in per-session Docker sandboxes.
• Every outbound connection is listed. The P2P bootstrap, update check, orchestrator download, and circles mailbox are each documented with their payload and off switch in the outbound connection inventory.

Read known limitations and the security guide before connecting sensitive accounts or allowing other senders. Report vulnerabilities privately to [email protected].

When something goes wrong

bitterbot doctor

In a source checkout use pnpm bitterbot doctor; in Docker, docker compose exec -u node bitterbot-gateway node bitterbot.mjs doctor. It walks about 30 checks: runtime, config, model keys, gateway, memory, dreams, web search, channels, wallet, costs, and the P2P network.

Review diagnostic output for private information before attaching it to an issue.

Build with us

Help make personal AI worth keeping. Try Bitterbot on a recurring task, report where it loses context, contribute a reproducible evaluation, or help another person get their node running.

Built by Victor Michael Gil and the community. Follow @Bitterbot_AI, visit bitterbot.ai, or get in touch.

Star the repo to follow the work. Run a node to help shape it.

Heritage and attribution

Bitterbot builds on OpenClaw for channel infrastructure. Its agent runtime is Bitterbot’s own, with parts ported from Mario Zechner’s pi-mono; model provider connections still use pi-mono’s pi-ai. Its memory, dream, curiosity, hormonal, identity, and economic systems are Bitterbot work.

Deep Recall uses the Recursive Language Model pattern through hampton-io/RLM. Optional external skill ingestion integrates Skill Seekers by Yusuf Karaaslan alongside Bitterbot’s native scraper. An earlier research dream mode was inspired by Andrej Karpathy’s autoresearch.

See ATTRIBUTION.md for provenance and third-party acknowledgments, and LICENSE for the MIT license.

Muse and dots are products of Meta and OpenAI. Bitterbot is not affiliated with either.