Your own team of AI bots, in a chat app.
Every bot in the sidebar is a real agent — Claude or Codex running locally under the hood — with its own personality, its own model, its own computer, and its own connected apps. Talk to them like contacts. Watch them work. Approve what matters.
alca-bots is a derivative of OpenMausBot by Milind Soni and the OpenMausBot contributors, used under the Apache License 2.0. It is renamed, ships without upstream's source-available
enterprise/directory, and is not affiliated with or endorsed by the upstream project. See LICENSING.md and NOTICE.
One assistant in one box is the wrong shape for agents. AlcaBots is an independent, open-source project inspired by Grok Bot — it keeps the idea (AI as a messaging app: a roster of bots you chat with, each with its own personality, memory of its thread, model, computer, and apps) and rebuilds it open, local-first, and on the agents you already have:
- Bring your own agents. Bots run on the
claude,codex, andgrokCLIs installed on your own machine — your existing logins and subscriptions, no new accounts, no proxy in the middle. Point any engine at a custom CLI binary (a versioned build or wrapper) in Settings → Engines. - Local first. One small harness server on
127.0.0.1owns every agent process. Transcripts, keys, and events live in~/.alcabots, not a cloud. - Agents with hands. Each bot can use a cloud Linux desktop, an isolated Local VM, or—where the platform safety boundary is currently certified—your own computer, plus 500+ apps through Composio. Host control is available on macOS and Ubuntu Xorg after explicit opt-in. Ubuntu Wayland host control remains disabled while issue #345 is resolved.
Keep Work, Personal, and each project in separate channels without cloning your bots. Every channel has its own transcript, shared instructions, working folder, responder rules, and editable bot roster. File a channel and its bots under a named context, then rename it or change its members whenever the team changes.
Add a TypeSafe Jev key, or an OpenRouter key and model, in Settings → Decision model and rooms set to Auto pick the bot that fits each un-mentioned message in a few hundred milliseconds, falling back to the room's lead whenever the decision model is off or unsure. See docs/decision-model.md.
Browse outcome-driven teams on BotMRR, then choose Add to AlcaBots. The app
opens a review screen before creating the bots, Chief of Staff, channels, playbooks, connector checklist,
and suggested routines. You can also import the same .md file from disk or paste its public GitHub URL
in Teams → Import.
The format stays portable: AlcaBots reads the structured YAML frontmatter for a reliable one-click install, while Grok, Claude, ChatGPT, and people can follow the ordinary Markdown playbook. Connections remain off until you approve them, routines arrive paused, and packages never carry credentials, conversations, permissions, memory, or computer access. Browse the open-source playbook repository or read its portable format.
Right-click a department and choose Share department… (or use Templates → Share) to save the whole department as one file: its bots with their instructions, pictures and skills, group chats, routines, shared instructions, Chief of Staff, connection slots and each bot's starter notes (untick them to leave them out). The dialog shows exactly what the file holds before you save it. Chat history, keys and passwords, model choices and computers never go in, and anything that looks like a secret is removed from the text. Whoever imports it gets new bots on Ask, skills switched off and routines paused. See docs/team-sharing.md. Desktops connected to an organization also get Templates → From {Organization}: the packages its Admin shares, added with one click, skills switched on. See docs/org-library.md. Your New bot defaults can travel too, as a preset bot that appears in New bot (in a team file, or on their own with Share as preset…). See docs/presets.md.
Bots browse the web through ego lite, the Chromium browser on your own Mac or Windows PC. You see every page a bot opens in its own group of tabs, your sign-ins stay yours, and when a site needs you (a sign-in, a code, a CAPTCHA) the bot hands the tabs to you and continues when you are done. From a paired phone you can watch the bot's browser and take it over: the bot waits until you hand it back. Install ego lite and finish its onboarding, then restart AlcaBots. See the browser guide.
Press the speaker on any reply, or switch a bot to read its answers out as they land — so you can listen to what ran overnight while you make breakfast. Hit call and it's a conversation: it hears you, tells you what it's doing while it works, and asks for approvals out loud.
Choose ElevenLabs, Fish Audio, Grok (xAI), built-in Mac voices, or a local Chatterbox server in an agent profile. Paste a cloud key once when needed, pick a voice, and every bot can talk. Give a bot its own voice and a channel stops sounding like one person.
For Grok, save your xAI API key in Settings → Connections, then choose Grok (xAI) and a voice under the bot’s Voice & alerts. It reuses that host-side key and returns MP3 audio for spoken replies and calls. Language is detected automatically from the reply text; quality varies outside xAI’s officially supported languages. This adds speech synthesis to the existing call flow; microphone transcription remains unchanged.
Also in the box: streaming replies with tool-run activity chips · dictation from the composer mic (on-device Apple speech recognition on macOS, Fish Audio speech-to-text on Windows and Linux, in the desktop app) · SupaMaus cursor mascots with role-aware expressions · screenshots of the bot's work folded into the transcript.
| Service | Purpose |
|---|---|
| Claude · Codex · Grok | The agents behind every bot, run through their local CLIs |
| Electron | Desktop shells for macOS, Windows, and Ubuntu |
| React + Vite + Tailwind CSS | The chat app UI and its build |
| Boat (boat.dev) | Cloud computers (upstream integration; needs your own account) |
| Composio | Connected apps — Gmail, Slack, GitHub, and more |
| Cua Driver | Native computer use on your own machine |
| ego lite (lite.ego.app) | The bots' web browser, installed separately on your computer |
| ElevenLabs · Fish Audio | Hosted voices for bots that talk back |
Two processes. The app holds no transports of its own — it sends typed commands over HTTP and folds one SSE event stream into state. The harness server owns every agent process and normalizes each provider's native protocol into one canonical runtime event stream (logged per-thread as NDJSON).
flowchart LR
subgraph app ["App — React + Tailwind (5199)"]
UI[Chat UI · model picker · computer panel]
end
subgraph server ["Harness server (127.0.0.1:8799)"]
REG[Driver registry] --> BUS[Event bus → SSE]
BROKER[Permission broker]
end
subgraph agents ["Agents on your computer"]
CL[claude CLI]
CX[codex CLI]
GR[grok CLI]
end
UI -- "HTTP commands" --> server
BUS -- "one SSE stream" --> UI
REG --> CL & CX & GR
CL & CX & GR -- "permission requests" --> BROKER
server -- "Boat API" --> BOAT[("Cloud computer<br/>boat.dev")]
server -- "Composio Session" --> APPS[("Gmail · Slack · GitHub · …")]
| Layer | Where | What it does |
|---|---|---|
| Drivers | server/drivers/ |
One per provider: Claude, Codex, and Grok Build over their local CLIs (stream-JSON / JSON-RPC / ACP), plus a cloud-computer agent. Unknown drivers degrade to "unavailable", never crash the fleet. |
| Harness | server/harness/ |
Registry (configs → live instances) and the fan-in event bus every client folds. |
| API | server/index.ts |
Bots, turns, approvals, model catalog, computer lifecycle, connectors, config — HTTP + SSE. |
| Voice | server/tts/ |
ElevenLabs, Fish Audio, Grok (xAI), built-in Mac voices, or local Chatterbox. Cloud keys stay on the harness; markdown is rewritten into something worth hearing before it is spoken. |
| App | src/ |
The chat shell. Server-backed store, one reducer, zero client-side transports. |
| Desktop | electron/ |
macOS, Windows, and Ubuntu shells with an embedded harness and platform capabilities; Apple speech stays macOS-only, Ubuntu Xorg has opt-in local control, and Wayland remains fail-closed. |
AlcaBots ships a stdio MCP server for external clients such as Claude Desktop and Cursor. It exposes a deliberately bounded team control plane: inspect bots and channels, read/search compact transcript pages, create and configure bots/channels/tasks, send work, wait for completion, switch models, and interrupt turns. It does not expose approval grants, deletion, arbitrary settings, credentials, or computer lifecycle.
See MCP server setup and tool reference.
The alcabots command drives a running workspace without a screen: set a
team up from a file, give a bot one job, wait until it and every teammate it
asked are done, and export what they made. One JSON document with --json,
and exit codes a script can branch on.
alcabots team apply team.yaml
alcabots run "Room Lead" "Rehearse the launch of https://example.com" --export ./outSee Run AlcaBots from scripts and CI.
Released builds (latest release): the harness server is embedded, so no separate server setup is required.
| Download | Install | |
|---|---|---|
| macOS (Apple silicon) | AlcaBots.dmg | Drag it to Applications, open it. Signed & notarized. |
| macOS (Intel) | AlcaBots-intel.dmg | Same app, built for Intel Macs. Signed & notarized. |
| Windows (x64) | AlcaBots-setup.exe | Run it — one-click, per-user, no admin rights. The installer isn't code-signed yet, so SmartScreen shows "unknown publisher": More info → Run anyway. |
| Ubuntu 24.04 (x64) | AlcaBots-amd64.deb · AlcaBots.AppImage | Install the .deb with APT (recommended), or make the AppImage executable and run it. Beta; GNOME is the supported desktop. |
See the Ubuntu Desktop guide for installation, capabilities, and troubleshooting.
From source:
git clone https://github.com/ihsieh31/alca-bots && cd AlcaBots
pnpm install
pnpm dev:server # harness server → 127.0.0.1:8799
pnpm dev # app → http://127.0.0.1:5199
pnpm dev:desktop # Electron shell; keep the two commands above runningRequirements: macOS, Windows, or Ubuntu 24.04 x64, Node 24+, pnpm, and at least one agent CLI — claude,
codex, or grok — installed and logged in. They appear
in the model picker automatically.
Package the desktop application:
pnpm package:mac # macOS: DMG + ZIP; requires Swift/Xcode tools
pnpm package:win # Windows: installer + ZIP
pnpm package:linux # Ubuntu x64: .deb + AppImage + verified CUA runtime| Capability | macOS | Ubuntu 24.04 Xorg | Ubuntu 24.04 Wayland |
|---|---|---|---|
| Packaged app, embedded harness, local agent CLIs | Supported | Beta | Beta |
| Composio and Boat/cloud computers | Supported | Beta | Beta |
| Explicit preview-only local screen capture | Supported | Beta | Beta |
| Bot control of this computer | Supported | Beta, explicit opt-in | Disabled: Wayland safety gate |
| Native on-device dictation | Supported | Planned | Planned |
| Dictation and Take turns calls through Fish Audio (needs a Fish Audio key) | Not used, on-device instead | Supported | Supported |
The Linux preview is user-initiated and never enables local bot control or Auto routing. On Xorg, the reviewed Cua Driver 0.19.3 runtime starts only after explicit opt-in and without its full-screen cursor overlay. On Wayland the app never starts it and clears legacy opt-ins while that real-seat safety gate remains unresolved. Chat, preview, Cloud, and Local VM remain available on both sessions. See the Ubuntu Desktop guide and tracking issues #29, #345, and #113.
The Linux packager downloads only the tag-pinned upstream archive during the build, verifies its size, SHA-256,
complete member allowlist, and inner executable hashes, then packages only the CLI and cursor-theme sidecar. The
installed app never downloads or self-updates native automation code. Cua's MIT notice, Inter's SIL OFL, a generated
third-party license report, and a CycloneDX inventory ship with the runtime. See
third_party/cua-driver/ for the reviewed provenance record.
These credentials are optional — local chat works without them. Paste a key once in App Settings (gear in the sidebar footer) when you want to enable its integration:
| Credential | What it enables | Where to get it |
|---|---|---|
Composio project key (ak_…) |
Connect Gmail, GitHub, Slack, Notion, and other apps to your bots | AlcaBots Composio setup |
| Boat API key | Give bots an isolated remote Linux computer with a desktop and terminal | Boat API key guide |
| ElevenLabs key | Read replies aloud, and call your bots | ElevenLabs API keys |
| Fish Audio key | Read replies aloud with Fish Audio voices, and call your bots | Fish Audio API keys |
Composio and Boat are third-party services with their own accounts and terms. Boat is a paid service after its trial, and using a cloud computer may incur charges.
pnpm typecheck # app + server
pnpm test # unit, driver, API, and desktop capability tests
pnpm build # typecheck + production build
pnpm check:electron # syntax-check Electron main/preload files
pnpm package:win # Windows installer + zip → release/
pnpm package:linux # Ubuntu x64 .deb + AppImage → release/A trigger is "when something happens, a bot does something". Tell a bot "every weekday at 9, send me a summary
of my inbox" or "whenever our form calls, draft a reply" and it sets the trigger up in that turn with
its trigger tool (no confirmation; the chat shows a live card with Edit, Pause and Undo). Triggers, first in
the sidebar, lists every schedule and webhook, with a calendar and the run history. Bots manage them with
trigger_info (list, app events), trigger (create, update, pause, resume, run now) and delete_trigger; a webhook a bot makes never shows the bot its secret:
the person copies the link from the card or the Triggers page.
Schedules (routines) can run once, on selected weekdays, or every 5–1,440 minutes, using either a bot's configured model/computer or the Cloud VM runner. Interval schedules stay aligned to their chosen start time and skip an occurrence when the previous run is still active, so slow work cannot build an unbounded queue. A separate optional Advanced run limit can safely stop stuck work; no timeout is imposed unless one is chosen. The existing duration field remains calendar/display metadata. Webhook triggers are independent from schedules but reuse the same queued task executor and calendar receipts.
App events start a bot when something happens in a connected app ("whenever I get an email from Acme, draft
a reply"). The bot finds the app's events with trigger_info (action: "events") and calls trigger with
action: "create" and when: "app_event"; the person can also choose New → Set it up yourself → When something happens in an app.
Composio sends each event to AlcaBots's connected-apps service, which queues it; the app collects the queue
with a long poll, so a desktop needs no public address and events wait while it is closed. Gmail is checked every
15 minutes; Slack, GitHub and other push apps arrive at once. A desktop keeps up to 500 events a day and a paid
Cloud 2,000; what is skipped shows on the automation. App events need the included connected apps: a server
using its own Composio key cannot watch apps yet. Details: docs/composio.md.
AlcaBots starts a webhook-only receiver on 127.0.0.1:8800 by default (or one port above ALCA_PORT).
Set ALCA_WEBHOOK_PORT to choose another port. A webhook secret is shown once when the trigger is created
or rotated. Bearer authentication is recommended so the secret stays out of request URLs and most access
logs; a single capability URL remains available for senders that cannot configure headers. The receiver
exposes only /health and secret /hooks/... endpoints; it never exposes the app's broader API.
AlcaBots must remain running to accept a delivery. For public internet delivery, proxy only this
dedicated receiver through a hosted relay or a tool such as Tailscale Funnel.
Early but real — the loop works end to end: message → agent → streamed reply → tools → approvals →
computer use. macOS, Windows, and Ubuntu 24.04 x64 have released builds; Ubuntu remains a beta with the
capability limits above. Rough edges to expect: hosted/mobile connectivity is still being built, and webhook
triggers currently use the local receiver rather than an always-on hosted relay.
Hosted voice needs an ElevenLabs, Fish Audio, or xAI key; built-in Mac and local Chatterbox voices need no cloud key. Take-turns calls and the composer mic listen on-device on macOS and through Fish Audio speech-to-text on Windows and Linux (the same Fish Audio key as voices). See docs/voice-mode.md for the design and the known gaps.
Contributions welcome — the driver SPI in server/contracts.ts is deliberately
small; adding a provider is one file in server/drivers/ plus a one-line registration.
No code needed at all for your own engines: any ACP-speaking CLI or OpenAI-compatible endpoint
plugs in through config — see docs/custom-engines.md.
Users can add their own MCP tool servers with zero code via docs/custom-mcp-servers.md.
To run bots on OpenRouter, Fireworks AI, DeepSeek, Cline or your own OpenAI- or Anthropic-compatible provider,
see Other model providers.
Usage analytics are optional and anonymous: product events and a once-a-day count of what is set up, never keys,
names, addresses or conversations. Turn them off in Settings → General → Usage analytics;
docs/analytics.md lists every event and property.
With Node 24 or newer, install once and run:
npm install -g alcabots
alcabotsOr use npx alcabots without a global install. First launch guides you with
arrow-key choices: choose AI access, sign in or paste a hidden API key, choose
a model, and optionally connect a phone. Next time, the same command reuses your
saved setup and opens AlcaBots on this computer. Keep the terminal open; Ctrl-C stops
the server, not your saved work. Use --no-open to skip opening the browser.
Phones use a web page, with no app to install: turn on phone access in Settings, or run
alcabots phone on a machine with no screen, and scan the code. The connection is end-to-end
encrypted through a relay you can host yourself. See Use AlcaBots from your phone.
Run alcabots setup to reconfigure without resetting bots or conversations;
the saved model default applies only to new bots. Native setup confirms provider
sign-in; API setup asks before a potentially billable test message. API keys are
saved as plaintext, not encrypted, in private config.json (0600 on Unix).
See the short setup guide for account differences,
phone choices, credential storage, and cancellation.
For a background service on a VPS or an always-on computer, use
npx alcabots serve with explicit remote options: --tailscale for your
tailnet, or the Docker stack for your own domain. alcabots phone needs neither. These are separate from
AI-provider sign-in. Devices pair once with a short code. The deployment guide is
docs/deploy-vps.md; the reference is
docs/self-hosting.md.
Apache License 2.0. Copyright 2026 ihsieh31 and alca-bots contributors; portions Copyright 2026 Milind Soni and OpenMausBot contributors. Details are in LICENSING.md and NOTICE.
Packaged Cua Driver components retain their upstream MIT, SIL OFL 1.1, MPL-2.0, and other dependency terms;
the corresponding notices, license texts, source locations, and SBOM are in
third_party/cua-driver/ and ship beside the native runtime.
ego lite is proprietary software by Citro Labs, installed separately under its own
terms and never bundled; the bots' browsing guide is adapted from the MIT-licensed
ego-browser skill, whose license is in third_party/ego-lite/.
OpenMausBot and MausBot are trademarks of Supamaus Software Private Limited; "Grok" and other product names are trademarks of their respective owners. alca-bots is not affiliated with any of them.





