How to Install and Run OpenMausBot
This guide is based on the open-source project OpenMausBot (also known as MausBot) by Milind Soni / Supamaus Software Private Limited, licensed under Apache License 2.0 for the core. StackGuide AI is not affiliated with OpenMausBot, Milind Soni, Supamaus, Anthropic, OpenAI, or xAI. Official site: openmausbot.com.
OpenMausBot is a local-first, multi-bot desktop chat app: instead of one assistant in one box, you get a roster of bots in a messaging-style sidebar, and every chat is a real agent running on your own machine. Each bot has its own persona, model, memory, connected apps through Composio, and computer environment. As of November 6, 2026, the project has about 13,500 stars on GitHub, and its core is Apache-2.0 licensed — but read the licence section before assuming everything in the repository carries that licence, because one folder does not.
The shape will feel familiar if you have seen Grok Bot, Meta Muse, OpenAI dots, or Cue by Manus. OpenMausBot is the open, local-first version: your bots run on the claude, codex, and grok tools logged in on your own computer, with no proxy in the middle. That is the whole appeal — and why the security section matters: a bot that can run shell commands needs a permission setting you chose.
What OpenMausBot is, and when to use it
Every bot is a real agent backed by your local claude (Claude Code), codex (OpenAI Codex CLI), or grok (xAI CLI) tool, plus custom ACP or OpenAI-compatible engines. For its computer, a bot can use a Cloud Linux computer via Boat, an isolated Local VM, or — only where you explicitly opt in — your own host computer. The desktop app is built with Electron and React: a roster on the left, a conversation in the middle, a model picker per bot, and approval cards when a bot wants to do something that needs your say-so.
It suits people who already use one of those CLIs and want several of them working as a team without handing their files to a hosted service: a coding bot on Claude, a research bot on Codex, a quick-draft bot on Grok, each with its own working folder. It is not a hosted service, and it is not a way to use those CLIs without their own sign-ins. Before installing, sign in to at least one CLI, and decide how much power a bot should have before its first turn (see Step 5).
How it works: two processes on loopback
OpenMausBot is a two-process system. The Electron and React interface talks over loopback HTTP plus one server-sent-events (SSE) stream to a small local harness server, which owns every agent process and normalises each provider's native protocol into one event stream, logged per thread as NDJSON. In development the harness binds strictly to 127.0.0.1:8799 and the web UI runs on http://127.0.0.1:5199; in packaged builds the harness is embedded. A webhook-only receiver starts on 127.0.0.1:8800 by default (or one port above OMB_PORT) and only exposes /health and secret /hooks/... endpoints. Nothing listens on your network address.
Prerequisites
- Operating system: macOS (Apple silicon or Intel), Windows 10 or later (x64), or Ubuntu 24.04 LTS (x64, GNOME — beta).
- At least one agent CLI, installed and logged in:
claude,codex, orgrok, signed in through its own native flow in your terminal. - For building from source: Node.js 24 or newer (
engines.node >= 24), pnpm (corepack enable; the repo uses[email protected]).
Step 1: Install a packaged release (macOS, Windows, Ubuntu 24.04)
The fastest path is a packaged release from github.com/milind-soni/OpenMausBot/releases/latest. Check that the address is github.com/milind-soni/OpenMausBot before you download anything — look-alike repositories are exactly how fake installers spread.
macOS. Download OpenMausBot.dmg (Apple silicon) or OpenMausBot-intel.dmg (Intel). Both are signed and notarized: open the image, drag OpenMausBot to Applications, and open it.
Windows (x64). Download OpenMausBot-setup.exe and run it: a per-user, one-click installer, no admin rights needed. Expect a SmartScreen warning — the installer is not code-signed yet, so SmartScreen shows “Windows protected your PC” and an unknown publisher. That is the documented state of the current installer, not proof your download is bad — but it is why the URL check above matters. Verify the download came from github.com/milind-soni/OpenMausBot first, then click More info → Run anyway. If you cannot verify the source, do not click through.
Ubuntu 24.04 LTS (x64, Beta, GNOME). There are two packages, and the .deb is the recommended one. Download OpenMausBot-amd64.deb and install it with APT so its desktop dependencies are resolved:
sudo apt install ./OpenMausBot-amd64.debThen open OpenMausBot from the GNOME launcher; to remove it, run sudo apt remove openmausbot. The .deb is recommended because APT installs the desktop dependencies and loads a targeted AppArmor profile for the bundled bot browser, so the Chromium sandbox works without weakening Ubuntu's system-wide user-namespace restrictions. Upgrades refresh the same rule, and uninstalling removes it.
The portable alternative is OpenMausBot.AppImage, which installs no system files:
chmod +x OpenMausBot.AppImage
./OpenMausBot.AppImageThe AppImage uses a static runtime, so it does not need legacy libfuse2, but it does need fuse3 plus the standard desktop libraries on a minimal install. If Ubuntu's AppArmor user-namespace restriction makes the bundled browser report No usable sandbox, switch to the .deb — never add --no-sandbox, never disable AppArmor globally, and never allowlist arbitrary executables under your home directory. Ubuntu checksums are in SHA256SUMS-ubuntu-x64.txt on the releases page — verify them first.
GNOME Xorg vs Wayland: what works where
On Ubuntu, the GNOME session type decides what a bot may do with your screen. View-only screen preview works on both Xorg and Wayland. Local host computer control — assigning a bot to This computer via the bundled Cua Driver 0.19.3 — is an explicit opt-in on Ubuntu on Xorg only: Settings → Enable local control (Beta), wait for Ready, then assign a bot to This computer. On Wayland it remains disabled and fail-closed, tracked in issue #345: the app never starts the driver there, clears legacy opt-ins, and no environment override can bypass the gate. On Wayland, use chat, preview-only capture, the Cloud computer, or the Local VM — or sign out and choose Ubuntu on Xorg. Preview alone never gives a bot control: on Xorg, control needs both the opt-in and the per-bot assignment.
Step 2: The terminal / server CLI option
To run OpenMausBot from a terminal or a server, use the npm package (Node 24 or newer):
npm install -g openmausbot
openmausbotOr run it without a global install with npx openmausbot. The first launch walks you through arrow-key choices — AI access, sign-in or a hidden API key, a model, optionally a phone; the next launch reuses your saved setup. Keep the terminal open — Ctrl-C stops the server, not your saved work. Flags: --no-open skips opening the browser, --local ignores saved remote access for one launch, --no-pair suppresses phone prompts. API keys are saved as plaintext in a private config.json (mode 0600 on Unix).
For headless use: openmausbot team apply team.yaml applies a team definition from a file, and openmausbot run "Room Lead" "Rehearse the launch of https://example.com" --export ./out runs a prompt in a named room and exports the result. Run openmausbot setup to reconfigure without resetting your bots or conversations. For a background service on a VPS, use npx openmausbot serve with explicit remote options — --tunnel after npx openmausbot login, or --tailscale — and read the deployment guide before exposing anything to the internet.
Step 3: Build and run from source
Building from source runs the newest code, lets you audit it, or produces the pure open-source edition in Step 6. Clone the repository, enable Corepack, and install dependencies:
git clone https://github.com/milind-soni/OpenMausBot.git
cd OpenMausBot
corepack enable
pnpm installDevelopment uses three processes, one per terminal — keep all three running:
# Terminal 1: harness server → 127.0.0.1:8799
pnpm dev:server
# Terminal 2: web UI → http://127.0.0.1:5199
pnpm dev
# Terminal 3: Electron desktop shell (keep the two above running)
pnpm dev:desktopBefore you trust a build, run the project's own checks: pnpm typecheck, pnpm test, pnpm build, and pnpm check:electron (Electron main and preload files). To package the desktop app yourself, use pnpm package:mac (DMG plus ZIP; needs Swift and Xcode tools), pnpm package:win (installer plus ZIP), or pnpm package:linux (.deb plus AppImage). One failure mode is worth naming: the server launches with node --experimental-strip-types, so on Node older than 24 you will hit syntax and strip-types failures before anything starts — install Node 24 or newer instead of editing the launch scripts.
Step 4: Connect your claude, codex, and grok CLIs
Connecting a CLI is deliberately boring: OpenMausBot uses the login you already have. Install claude, codex, and/or grok from their own official sources, run each one once in your terminal, and complete its native sign-in there. Verify it responds, then start or restart OpenMausBot. Detected CLIs appear automatically in each bot's model picker, using your existing login and subscription, with no proxy in the middle. The picker shows a provider rail — defaults marked, unavailable providers dimmed with the reason — and you can switch a bot's model mid-conversation.
If a CLI is installed but not detected: the PATH pitfall
Desktop apps launched from a dock do not inherit the same interactive-shell PATH as your terminal, and this bites hardest on Linux GNOME and macOS GUI launches. OpenMausBot checks the inherited path plus common locations — ~/.local/bin, ~/.claude/local, ~/.volta/bin, ~/.bun/bin, ~/.asdf/shims, ~/.deno/bin, ~/.nvm/versions/node/*/bin, and /usr/local/bin — and probes your login shell in the background. If your CLI lives elsewhere, launch from a terminal with an explicit extra path:
OMB_EXTRA_PATH=/your/custom/bin ./OpenMausBot.AppImageReplace /your/custom/bin with the directory that actually holds your CLI binary — find it with which claude in the terminal where it works. If the CLI appears when launched from the terminal but not from the dock, the problem is the path, not the CLI.
Custom engines: your own ACP CLI, or an OpenAI-compatible endpoint
Two zero-code ways to run a bot on an engine the app does not ship, both configured in ~/.openmausbot/config.json under "instances", with a restart after editing. First, any ACP-speaking CLI can be added as a customAcp instance — point config.cli at the whole command, arguments included, for example "vibe-acp" for Mistral Vibe or "cmd acp" for Command Code — and sign in to that CLI in your terminal first, because the driver has no auth flow of its own. You can also set the CLI under Settings → Engines → Set CLI…, and use Re-detect to load the models the agent advertises. Foreign provider keys are stripped before a custom ACP CLI is spawned, so it can never bill against another engine's login.
Second, the built-in openai-compat driver supports multiple instances, so a local vLLM, LM Studio, or Ollama endpoint — or any hosted compatible API — is one entry with a url, an apiKeyEnv naming which environment value carries the key, and a model. The driver lists the endpoint's /models when it can; set config.tools to false for a model without tool support. Keep keys scoped to the one engine — config.json is mode 0600 and its environment values are plaintext.
Step 5: Security first — the Full access default
⚠️ Read this before your first real task: every new bot and thread starts at Full access by default. Under Full access, shell commands, file edits, selected-computer actions, profile, routine, and skill changes, and peer delegations execute without confirmation cards. The mapping is concrete: Claude runs with bypassPermissions, Codex with danger-full-access and never approvals, Gemini and Qwen with --yolo. It does not bypass OS privacy controls, authentication, CAPTCHA, or MFA — but within your login's permissions, it removes the pause where you would say yes or no.
That default is the single most important fact in this guide. Work through this checklist on first launch, before you point a bot at anything you care about:
- Lower the approval level. Switch bots from
Full accesstoAsk for approval— orAuto-accept edits/Approve for me— via the composer permission chip, Bot Settings, or Set for all bots in this department…. Timing rule: for native-mode CLIs, lowering takes effect on the next turn, not mid-turn. - Scope the working folder. Give each bot a dedicated scratch working folder, a Local VM, or a Cloud Linux VM, rather than binding bots to This computer unless you truly need it. A bot that can only reach a scratch folder can only damage a scratch folder.
- Keep connected-app sends on Ask every time. Sends through connected apps — email, messages, posts, payments — follow the bot's Sending on your behalf setting. Keep it on Ask every time; apps outside a bot's scope are still refused. Review imported
.mdteam packages before enabling skills or routines: imports arrive with skills off and routines paused — do not bulk-enable them unread. - Keep the loopback loopback. Keep the webhook receiver (
127.0.0.1:8800) on loopback, or behind Bearer authentication, rather than exposing127.0.0.1:8799. Forwarding the harness turns a local app into a network service. For public webhook delivery, proxy only the dedicated receiver through a hosted relay or Tailscale Funnel, never the harness.
Two more habits. The effective setting belongs to the source conversation: an existing Ask thread stays Ask even if the bot default is Full, and a Full thread works without the extra prompts even if the bot default is Ask — check the thread you are using. Treat ~/.openmausbot/config.json as a secrets file: mode 0600, values in plaintext, so never paste it into a chat, ticket, or public gist.
Step 6: Pure open-source edition vs the enterprise carve-out — and scams to avoid
OpenMausBot's licence has a split, written down in LICENSING.md and enterprise/README.md. Everything outside enterprise/ is Apache License 2.0 (the repository LICENSE). Everything inside enterprise/ — whitelabel, sso, admin, budgets, and billing — is under the separate, source-available OpenMausBot Enterprise License (enterprise/LICENSE): free to read, build, evaluate, and run in development and test, while production use of enterprise entitlements requires an OMB_LICENSE_KEY, and third-party hosting or white-labelling requires a partner agreement.
For a pure Apache-2.0 self-use build, delete enterprise/ when building from source:
rm -rf enterpriseCore loads the enterprise layer through one optional seam (server/enterprise.ts), so removing the folder changes nothing about standalone operation: without enterprise/, GET /api/edition returns {"edition":"oss"} — verified by an upstream CI job. Apache-2.0 section 6 does not grant rights to the OpenMausBot or MausBot names or the SupaMaus mascot, trademarks of Supamaus Software Private Limited.
Anti-phishing and scam warning
Verify the exact repository — https://github.com/milind-soni/OpenMausBot — and the official site https://www.openmausbot.com before you download or sign in to anything, and check release SHA-256 hashes where published. OpenMausBot has no cryptocurrency and no token: any coin using the OpenMausBot, Maus, or SupaMaus name is unaffiliated, and the maintainer states they have received no tokens, payment, or allocation and will not endorse any token. A download or installer from any other channel is not the project, however convincing it looks.
Troubleshooting
| Problem | Fix |
|---|---|
| CLI missing from the model picker | Install and sign in to the CLI in your terminal, verify it answers there, then restart OpenMausBot. If it works in the terminal but not the app, it is a PATH problem — launch from the terminal or set OMB_EXTRA_PATH. |
| Windows SmartScreen blocks the installer | Verify the download came from github.com/milind-soni/OpenMausBot, then click More info → Run anyway. The installer is not code-signed yet. |
AppImage: No usable sandbox or missing FUSE | Install fuse3 and the standard desktop libraries. If AppArmor's user-namespace restriction still blocks the sandbox, switch to the .deb. Never add --no-sandbox or disable AppArmor. |
Wayland: This computer disabled | Expected — host control is fail-closed on Wayland (issue #345). Use chat, preview-only capture, the Cloud computer, or the Local VM, or choose Ubuntu on Xorg. |
| Node older than 24: syntax / strip-types failure | Install Node.js 24 or newer — the server launches with node --experimental-strip-types. |
Lowering Full access does not apply | For native-mode CLIs it takes effect on the next turn, not mid-turn. Stop the running turn and start a new one. |
Ports 8799, 5199, or 8800 in use | Another app is already on that port. Stop it, or set OMB_PORT or OMB_WEBHOOK_PORT. |
FAQ
Is OpenMausBot a hosted service? No. It is a desktop app (or a terminal server you run yourself) whose harness, transcripts, and credentials live in ~/.openmausbot on your machine. Local chat works without any cloud piece.
Can a bot act on my own computer? Only where you explicitly opt in — macOS, or Ubuntu on Xorg with Enable local control (Beta) on and the bot assigned to This computer. On Wayland it is disabled, and preview-only sharing never grants control.
Licence and attribution
OpenMausBot's core is licensed under Apache License 2.0, © 2026 Milind Soni and OpenMausBot contributors, except for enterprise/, which is source-available under its own Enterprise License — see Step 6 for the split and the rm -rf enterprise step. In plain terms, and not as legal advice: Apache-2.0 lets you use, copy, modify, and distribute the core code, including commercially, provided you keep the copyright and licence notices — but it does not grant trademark rights to the OpenMausBot or MausBot names or the SupaMaus mascot. Bundled third-party components keep their own licences. OpenMausBot is an independent project inspired by Grok Bot, not affiliated with xAI, Meta, OpenAI, or Manus.
What to try next
Once one bot answers correctly from its own working folder, add a second bot on a different CLI with a different job — a Claude bot for code changes in a scratch folder, a Codex bot for research notes — then try a room where they hand work to each other.
This guide was checked against the official repository, README.md, LICENSING.md, SECURITY.md, docs/linux-desktop.md, docs/custom-engines.md, and docs/approval-levels.md as of November 6, 2026. StackGuide AI did not run this tool for this guide, so this guide makes no claim based on running the tool; the commands above are the ones the official documentation publishes. The checked sources were version 0.1.142 — filenames, defaults, and the Ubuntu beta status may change, so trust the releases page.
Sources
- https://github.com/milind-soni/OpenMausBot
- https://www.openmausbot.com
- https://github.com/milind-soni/OpenMausBot/releases/latest
- https://github.com/milind-soni/OpenMausBot/blob/main/README.md
- https://github.com/milind-soni/OpenMausBot/blob/main/LICENSING.md
- https://github.com/milind-soni/OpenMausBot/blob/main/SECURITY.md
- https://github.com/milind-soni/OpenMausBot/blob/main/docs/linux-desktop.md
- https://github.com/milind-soni/OpenMausBot/blob/main/docs/custom-engines.md
- https://github.com/milind-soni/OpenMausBot/blob/main/docs/approval-levels.md