OpenMausBot: A Local-First, Open-Source Team of AI Agents in a Chat App

If you use agent CLIs like Claude Code or Codex every day, you have probably wished you could run several of them side by side, give each one a role, and manage them like contacts in a messaging app. That is the idea behind OpenMausBot.

This post is a practical walkthrough for developers: what it is, how it is built, how to run it in a few minutes, and where you can extend it.

What is OpenMausBot?

OpenMausBot is an open-source, local-first chat app where every chat is a real AI agent. Each bot in the sidebar is backed by an agent CLI running on your machine, and each one can have its own:

• personality and instructions
• model
• computer (a cloud Linux desktop, an isolated local VM, or your own machine)
• set of connected apps

The project describes itself as an independent, open-source alternative to products like Grok Bot, Meta Muse, OpenAI dots, and Cue by Manus. It is not affiliated with xAI, Meta, OpenAI, or Manus. It is also known as MausBot and was formerly called OpenGrokBot.

Quick facts from the repository:

Why developers might care

There are three design choices that make this project interesting from an engineering point of view.

1. Bring your own agents. OpenMausBot does not proxy your requests through a hosted service. Bots run on the claude, codex, and grok CLIs already installed and logged in on your machine, so your existing subscriptions and logins are reused. You can point an engine at a custom CLI binary in Settings under Engines.

2. Local first. One small harness server listens on 127.0.0.1 and owns every agent process. Transcripts, keys, and events are stored in ~/.openmausbot, not in someone else's cloud.

3. Approvals instead of blind autonomy. A permission broker turns risky actions such as shell commands and file edits into inline cards in the chat. You choose Allow or Deny, for cloud and local computers alike.

Architecture in two minutes

OpenMausBot is split into two processes.

• The app (React and Tailwind, port 5199 in dev) holds no transports of its own. It sends typed commands over HTTP and folds a single Server-Sent Events (SSE) stream into state.
• The harness server (127.0.0.1:8799) owns every agent process. It normalizes each provider's native protocol into one canonical runtime event stream, which is logged per thread as NDJSON.

App (React + Tailwind, :5199) | HTTP commands ^ one SSE stream v | Harness server (127.0.0.1:8799) |-- Driver registry --> claude CLI / codex CLI / grok CLI |-- Event bus (SSE) |-- Permission broker <-- permission requests from agents |-- Boat API --> cloud computer |-- Composio session --> Gmail, Slack, GitHub, ... 

The main layers map to folders in the repo:

If you have built anything with an event-sourced UI, this will feel familiar: commands go in over HTTP, events come out over one stream, and the client is a reducer over those events.

Get it running

You have three options.

Option 1: Download a release

Released builds embed the harness server, so there is no separate server setup. Builds are available for macOS (Apple silicon and Intel), Windows x64, and Ubuntu 24.04 x64 (beta, as a .deb or AppImage). Grab them from the latest release.

Note that the Windows installer is not code-signed yet, so SmartScreen will show "unknown publisher". Use More info, then Run anyway.

Option 2: Run from the terminal with npm

This is the fastest path if you just want to try it, and it works on a server too. You need Node 24 or newer.

npm install -g openmausbot openmausbot 

You can also skip the global install:

npx openmausbot 

First launch walks you through arrow-key prompts: choose AI access, sign in or paste a hidden API key, choose a model, and optionally connect a phone. The next run reuses your saved setup. Useful flags and commands:

openmausbot --no-open # do not open the browser automatically openmausbot setup # reconfigure without resetting bots or conversations npx openmausbot serve # background service for a VPS or always-on machine 

Option 3: Build from source

git clone https://github.com/milind-soni/OpenMausBot && cd OpenMausBot pnpm install pnpm dev:server # harness server on 127.0.0.1:8799 pnpm dev # app on http://127.0.0.1:5199 pnpm dev:desktop # Electron shell; keep the two commands above running 

Requirements: macOS, Windows, or Ubuntu 24.04 x64, Node 24+, pnpm, and at least one agent CLI (claude, codex, or grok) installed and logged in. Installed CLIs show up in the model picker automatically.

Useful scripts while developing:

pnpm typecheck # app and server pnpm test # unit, driver, API, and desktop capability tests pnpm build # typecheck and production build pnpm check:electron # syntax-check Electron main and preload files pnpm package:mac # DMG and ZIP (needs Swift/Xcode tools) pnpm package:win # installer and ZIP pnpm package:linux # .deb, AppImage, verified CUA runtime 

Optional credentials

Local chat works without any extra keys. Add these in App Settings (the gear icon in the sidebar footer) only when you want the matching feature:

Composio and Boat are third-party services with their own accounts and terms. Boat is paid after its trial, so a cloud computer can incur charges.

Features worth knowing about

Model picker per bot. Claude and Codex models appear side by side, and you can switch a bot's model mid-conversation.

Computers for bots. A bot can use a cloud desktop, an isolated Local VM, or your own computer. Control of your own machine is explicit opt-in and available on macOS and Ubuntu Xorg. On Ubuntu Wayland it is currently disabled behind a safety gate (tracked in issue #345).

Channels. Separate Work, Personal, and project contexts without cloning bots. Each channel has its own transcript, shared instructions, working folder, and roster.

Teams from one Markdown file. A team package uses YAML frontmatter plus a normal Markdown playbook, so the app can install it in one click while humans can still read it. Connections stay off until you approve them, routines arrive paused, and packages never carry credentials, conversations, or memory.

Triggers. Schedules and webhooks let a bot act without you. Schedules can run once, on selected weekdays, or every 5 to 1,440 minutes. Interval schedules skip a run if the previous one is still active, so slow work cannot pile up in a queue.

Voice. Spoken replies and calls through ElevenLabs, Fish Audio, Grok, built-in Mac voices, or a local Chatterbox server. Calls are macOS-only for now.

Automate it: webhooks, CLI, and MCP

This is where it gets useful for developers.

Webhook triggers

OpenMausBot starts a webhook-only receiver on 127.0.0.1:8800 by default. Set OMB_WEBHOOK_PORT to change it. Key points:

• The webhook secret is shown once, when the trigger is created or rotated.
• Bearer authentication is recommended so the secret stays out of URLs and access logs.
• The receiver exposes only /health and secret /hooks/... endpoints. It never exposes the broader API.
• The app must be running to accept a delivery. For public delivery, proxy only this receiver through a hosted relay or something like Tailscale Funnel.

Headless CLI for scripts and CI

The openmausbot command can drive a running workspace without a screen. It returns one JSON document with --json and uses exit codes a script can branch on.

openmausbot team apply team.yaml openmausbot run "Room Lead" "Rehearse the launch of https://example.com" --export ./out 

MCP server

OpenMausBot ships a stdio MCP server so external clients such as Claude Desktop and Cursor can orchestrate your bots. The tool surface is deliberately bounded: inspect bots and channels, read and search transcripts, create and configure bots, channels, and tasks, send work, wait for completion, switch models, and interrupt turns.

It does not expose approval grants, deletion, arbitrary settings, credentials, or computer lifecycle. That is a sensible boundary, because it means an outside client cannot approve its own risky actions. Setup details are in the MCP docs.

Extending it

You have three extension paths, in increasing order of effort.

1. Add an MCP tool server with zero code. See docs/custom-mcp-servers.md in the repo.
2. Add a custom engine with config only. Any ACP-speaking CLI or OpenAI-compatible endpoint plugs in through configuration. See docs/custom-engines.md. The docs also cover running bots on OpenRouter, Fireworks AI, DeepSeek, Cline, or your own OpenAI- or Anthropic-compatible provider.
3. Write a new driver. The driver interface in server/contracts.ts is deliberately small. Adding a provider is one file in server/drivers/ plus a one-line registration.

If you want to contribute, read CONTRIBUTING.md and LICENSING.md first. The repo uses a CLA and describes how contributions are signed off.

Security mindset

Any tool that lets an agent run shell commands and control a computer deserves care. Reasonable defaults when you try it:

• Keep bots on Ask mode (approval cards) until you trust a workflow.
• Start with the cloud computer or Local VM before pointing a bot at your own machine.
• Connect only the apps a given bot needs.
• Review a team package before importing it from someone else.
• If you expose it to the internet, use a managed HTTPS endpoint with pairing, Tailscale, or your own reverse proxy, never a bare open port.

Where to go next

• Repository: github.com/milind-soni/OpenMausBot
• Website: openmausbot.com
• Self-hosting guide: docs/self-hosting.md and docs/deploy-vps.md in the repo

If you try it, start with npx openmausbot, create one bot, and watch the approval cards while it works. That is the fastest way to see why the architecture is built the way it is.