openmausbot

Your own team of AI bots, with guided terminal setup. Requires Node 24+.

npm install -g openmausbot
openmausbot

Or run npx openmausbot without a global install. Use the same command next time; openmausbot start is an alias for the bare command.

First launch: use arrow keys and Enter (numbered choices in plain terminals) to choose ChatGPT/Codex, Claude Code, or an API service; sign in or paste a hidden API key; choose a model and save. Setup asks before installing a missing Codex or Claude CLI. The saved model applies only to new bots; existing bots and conversations keep their settings.

One optional step connects your phone, defaulting to Skip for now. Choose an explicitly approved managed public HTTPS endpoint protected by pairing, existing Tailscale, or an HTTPS reverse proxy you already configured. Managed access uses a separate OpenMausBot account and asks permission for the public endpoint and possible connector download. The pairing page and basic server identity are public; chat and settings require pairing. Tailscale must already be installed and signed in on both devices.

After the HTTPS connection is checked, scan the QR with your phone. When you pair an Android phone the QR is an app link, so scan it inside the OpenMausBot app; the web address is printed beside it if you would rather use a browser. On iPhone or iPad, scan with Camera for Safari, or use the app's own scanner. Choose Connect on the phone; scanning alone is not a completed pairing. Codes are private, single-use, and expire after five minutes. Guided phone access permits chat and approvals, not settings or pairing administration. Localhost and a bare LAN address cannot connect your phone to this server.

Later launches reuse your saved choices and open OpenMausBot on this computer. Keep the terminal open: this is a foreground server, not a background service. Ctrl-C stops the server without deleting saved work. Automatic browser opening uses only the local address; it is skipped for SSH and headless sessions, and can be disabled with --no-open.

openmausbot setup          # reconfigure AI and optional phone access; not a reset
openmausbot --no-open      # do not open a browser
openmausbot --local        # ignore saved remote access for this launch
openmausbot --no-pair      # suppress phone prompts and invitations
openmausbot pair           # another phone while the HTTPS server is running
openmausbot sessions       # list devices; sessions revoke ID signs one out
openmausbot serve          # no onboarding prompts; explicit remote flags for services

Stop an existing server before reconfiguring or changing access mode. --local preserves your saved choice for next time. --no-pair does not turn off saved remote access; use --local for that on a new launch. With a custom --data-dir or --port, keep using those options when starting and pairing.

API services include OpenAI, OpenRouter, Groq, and compatible endpoints. API connections currently support chat only. Setup asks before a short, potentially billable API test; native setup confirms sign-in, with model access checked when you send a message. API billing is separate from ChatGPT/Claude subscriptions. New API keys in config.json and managed account credentials in tunnel-account.json are plaintext, not encrypted, with owner-only permissions (0600 on Unix). Keep these files private.

Ctrl-C before saving AI setup leaves its pending OMB changes unapplied. During the later phone step, it keeps the AI setup already saved and exits without starting a server. Completed installs and sign-ins remain; run openmausbot setup to continue without deleting your data.

For a service, use serve --tunnel after login for managed HTTPS, serve --tailscale for your tailnet, or your own reverse proxy. The login command signs in to an OpenMausBot account, not an AI provider; it does not start the tunnel itself.

Scripts, CI and other agents can drive a running workspace without a screen: set a team up from a file, give a bot one job and wait until it and every teammate it asked are done, and export what they made.

openmausbot team apply team.yaml
openmausbot run "Room Lead" "Rehearse the launch of https://example.com" --export ./out
openmausbot help run       # every verb: doctor, run, wait, send, export, events, team, engine, connect, mcp

Setup guide · Scripts and CI · Hosting guide