OpenBot is an open-source, self-hostable platform for running a team made up of multiple persistent AI bots. Each bot has a name, description, and instructions that constrain its behavior. Bots can converse with humans and other bots in shared threads, invoke pluggable tools, maintain long-term memory, and be accessed by external systems over HTTP. Chains of bots can form workflows: for example, a chief of staff bot delegates to an engineer bot, the engineer bot opens a pull request, a reviewer bot reviews it, and a QA bot tests it, requests human approval, and merges it.
Core concepts
Unified actor model: bots, humans, and external systems are all actors with persistent inboxes. Actors deliver messages to each other's inboxes via shared threads; when mail arrives, the bot actor is woken up, runs an LLM-driven agent loop with tools and memory, and replies, which in turn delivers new mail and wakes up the next bot. This unified model allows humans, bots, and webhook-driven event systems to participate in the same conversation in the same way.
Main capabilities
- Multi-bot workflows: user messages that do not explicitly mention a bot are sent to the thread's default bot (by default @chief_of_staff); bots hand off to each other via @mentions, with a hop limit to prevent runaway loops between bots. Only the first mention in a bot's reply wakes up a bot, so each handoff targets only one bot. If that bot still has newer messages waiting in the thread, the handoff is staged and automatically delivered after it catches up.
- Tools: built-in shell/file/HTTP tools rooted in the workspace directory, a plugin directory for custom Python tools, and tools from any MCP server (remote or stdio, with OAuth support), all selectable per bot. run_shell is not sandboxed (see Trust model/Security).
- Memory: each bot has long-term memory (LangMem), which the bot can search and update, with automatic background reflection after each run.
- Approvals and questions: bots can ask humans before taking sensitive actions (ask_human, or set an approval flag per tool); the run pauses until a human answers.
- External actors: external systems can be registered as actors to exchange mail with the rest of OpenBot via signed webhooks or a polling REST API.
- Real-time UI: React frontend, including inbox, thrprocesses, robots, settings, updated via SSE.
- Any SQL database: SQLite by default, switch to Postgres by changing one URL.
- Out-of-the-box LangSmith tracing.
How to use
Prerequisites: Python 3.12+ and uv, Node 24+ and pnpm 10. You also need an LLM provider: OpenRouter API key (recommended), OpenAI, Anthropic, or xAI key, or a local Ollama server.
The easiest way to try it is to download the desktop app from the latest release. Builds are provided for macOS (Apple Silicon and Intel, .dmg or .zip) and Linux (x64 .AppImage). There is no Windows build yet; on Windows you need to run from source following the quick start. The builds are unsigned; see the release notes for how to open them the first time. The app requires uv to be installed, and the first launch will take a while because it needs to set up Python.
Open http://localhost:5173。首次加载会显示简短设置向导：选择聊天提供商（粘贴密钥，或指向 Ollama), and choose the memory search method (embeddings via OpenRouter, OpenAI, or Ollama, or none). Both are stored encrypted in the OpenBot database and can be changed later in settings; they are not written to .env. After the wizard completes, OpenBot creates the human actor @you and four demo robots: chief_of_staff, engineer, reviewer, qa.
Desktop app (Electron): The Electron desktop app is an optional shell around the same frontend and HTTP/SSE API; the browser app remains unchanged. The renderer process has no Node integration and communicates with the backend through the same API as the browser; the preload bridge is deliberately kept minimal.
Production-style run: A single-process, production-style run where the backend serves the built frontend on port 8000.
Backend Docker: The backend runs in a container, while the UI stays on the host. Shell commands run as a separate shell user without the server environment, so they cannot read provider keys, secret.key, or the database.
Demo flow: The preset robots can run a small software workflow end-to-end against a real git repository using the gh CLI. Clone a pushable repository into workspace/, and make sure gh auth status succeeds in that directory—the robots will call git and gh. Start OpenBot and open the UI. Create a new thread (the default robot is @chief_of_staff unless changed), and send the example instruction. Watch the handoffs: the chief of staff delegates to @engineer, who implements the change, opens a PR, and mentions @reviewer; the reviewer reviews the diff and mentions @qa (or sends feedback back to @engineer); QA checks out the branch, runs the tests, and requests approval before merging. When QA's question appears in the inbox, open it and approve. QA merges the PR and reports back.
Trust model/security
OpenBot is intended for a single trusted operator running on their own machine. There is no login, no user accounts, and no permission isolation. Anyone who can access the HTTP port, and anyone who can get a robot to run tools, effectively has the privileges of the server process. Read this section before exposing OpenBot to a network or letting robots process untrusted input.
run_shell is not sandboxed. It runs with bash -lc executes arbitrary commands as the user running the server, with that user's full filesystem and network access. The thread working directory only provides the command's starting working directory: cd /, ../, absolute paths, etc. all work normally. It also inherits the server environment and can read database files and keys, so commands can steal all stored provider keys. There is no container, no chroot, no seccomp, no allowlist—giving the bot run_shell is equivalent to giving anyone who can talk to the bot a shell on the host.
CLI bots are managed by their CLI, not by OpenBot. Bots using the claude-code provider (see Bots powered by coding agent CLIs) use the CLI's own tools, and OpenBot's per-tool approval does not apply. What they can do is determined by the bot's own configuration.
