milind-soni/OpenMausBot

OpenMausBot is a desktop chat client in which each contact in the sidebar is a separate AI agent, with its own model, personality, storage, and apps. It targets people who want a Grok Bot-style multi-agent workspace without sending conversations, keys, or agent processes to a vendor's cloud.

Core loop and architecture

A small harness server bound to 127.0.0.1 owns every agent process; the React app sends typed commands over HTTP and consumes one SSE stream of normalized runtime events. Transcripts, keys, and events live in ~/.openmausbot. See the project overview.

A concrete flow: create a bot, choose a provider and model, give it a task in a channel, and watch tool-run activity stream into the thread. Commands, file edits, and questions surface as inline Allow/Deny cards through a permission broker before they run. Optional connected apps (Composio) and a cloud Linux desktop (Boat) extend what the bot can touch; both need their own credentials.

Bots also run through a CLI: openmausbot drives a running workspace from scripts, applying a team from a file, running one job, waiting for dependent teammates, and exporting results with JSON output and branchable exit codes (headless CLI docs). A stdio MCP server exposes a deliberately bounded control plane to external clients — it omits approvals, deletion, credentials, and computer lifecycle (MCP docs).

Requirements and platform limits

• Desktop builds: macOS (Apple silicon and Intel, signed and notarized), Windows x64 (unsigned installer, so SmartScreen warns), and Ubuntu 24.04 x64 as a beta with GNOME supported (release page).
• From source: Node 24+, pnpm, and at least one of the claude, codex, or grok CLIs installed and logged in. Any ACP-speaking CLI or OpenAI-compatible endpoint can also be configured without code.
• Local computer control: supported on macOS; Ubuntu Xorg needs explicit opt-in; Ubuntu Wayland is disabled pending a safety gate. Chat, screen preview, cloud computers, and Local VMs still work on Wayland.
• Optional paid services: Composio for connected apps and Boat for cloud desktops are third-party accounts; Boat is paid after a trial. Hosted voices need an ElevenLabs, Fish Audio, or xAI key; built-in Mac and local Chatterbox voices do not. Calls are macOS-only.

Users should also know that API keys in the terminal setup path are saved as plaintext (not encrypted) in a private config.json. Webhook triggers use a local receiver and require the app to stay running; public delivery needs a relay or funnel. App-event triggers require the bundled connected-apps setup, and a server using its own Composio key cannot watch apps yet.

Status and licence

The author calls it early but end-to-end working, with hosted/mobile connectivity and an always-on webhook relay still in progress. The code is Apache-2.0, except the enterprise/ folder, which is source-available under a separate licence; removing it leaves the open-source edition. On 2026-10-29 HotRepo recorded 6,999 stars and a single daily-board appearance; that one sample does not show a trend.