# Run OpenMausBot from scripts and CI The `openmausbot` command can drive a running workspace without a screen: set up a team from a file, give a bot a job, wait until it and every teammate it asked are done, and keep what they made. It works against the server on this computer or one somewhere else, and it is built for scripts, CI and other agents: every command can print one JSON document, and the exit code says how things went. ```sh npm install -g openmausbot # or use npx openmausbot … openmausbot serve --no-pair & # a workspace with no screen (or use your desktop app) openmausbot engine set claude --key-env ANTHROPIC_API_KEY openmausbot team apply launch-room.yaml openmausbot run "Room Lead" "Rehearse the launch of https://example.com" --export ./rehearsal ``` `run` prints progress as it goes, then the Room Lead's final reply and the files it links, and writes everything to `./rehearsal`. ## Sign in once ```sh openmausbot login # the MausBot app on this computer openmausbot login https://maus.example.com # a Cloud or a server elsewhere ``` `login` asks the server, and the person allows it with one click. On this computer the MausBot app shows a card, "A terminal wants to control MausBot", with a short code; the same code is printed in the terminal, so you allow the terminal you are looking at. For a Cloud or a server elsewhere your browser opens the server's page, where the same card waits (sign in there first if it asks). On a server you started yourself with `openmausbot serve`, a command on the same computer is its owner, so `login` signs in without a card. The sign-in lasts 30 days and renews while you use it. It is kept in the macOS Keychain, or on Linux and Windows in a file only you can read (`~/.config/openmausbot/`), and it is never printed or taken on the command line. `--scope chat` signs in for chat only. Every command then goes to that server, with that sign-in, and the sign-in is sent only to the exact address it was made at. | Command | What it does | |---|---| | `login [SERVER] [--scope chat] [--name NAME]` | Sign in (above); the server becomes the current one. | | `logout [NAME]` | End the sign-in on the server and remove it here. | | `whoami` | The server the commands go to, and who you are to it. | | `servers` | The servers you signed in to; `*` marks the current one. | | `use NAME` | Make another saved server the current one. | Nothing on the computer gets your access for free: a program, a web page or a bot can only ask, and only a person pressing Allow in the app (or in a browser signed in to the server) lets a terminal in. **Inside a bot's own shell** the command acts as that bot. It never uses your saved sign-in, and `login` refuses there. So one bot cannot delete or stop the others through your session by accident. It is not a wall against a bot with Full access, which runs as you. ## Which workspace, and as whom - `--url URL` or `OPENMAUSBOT_URL`: a workspace somewhere else. `https://` works anywhere; plain `http://` works only on this computer or a private network (a LAN address, Tailscale's 100.x or `*.ts.net`, `*.local`). - `--port N` or `OMB_PORT`: this computer, on that port. - Otherwise the server you signed in to with `login`, or else the command looks on this computer's usual ports (8799, 18799, 28799), as the desktop app uses them. Without a sign-in, a command on this computer can read from the desktop app (`bots`, `status`, `messages`, `export`, `events`) but every change is refused until you run `openmausbot login`. A server you started with `openmausbot serve` treats a command on its own computer as its owner, and needs no sign-in. For scripts and CI, a token in a file works anywhere: ```sh openmausbot connect https://maus.example.com --code 7KQ2-M9XD-H4TP --out ~/.openmausbot-token openmausbot doctor --url https://maus.example.com --token-file ~/.openmausbot-token ``` `connect` also takes the whole link the server printed (`https://maus.example.com/pair#code=…`), so `--code` can be left out then. Make the pairing code in the app's Settings → Phone & devices, or on a server with `openmausbot pair` (add `--client --ttl 24h` for a chat-only code that stays open up to a day; a code works once). On a server you started with `openmausbot serve`, `connect` makes the code itself (`--client` gives a token that can chat but not change settings). The token goes to a file only you can read, and is never printed. Pass it with `--token-file FILE` or `OPENMAUSBOT_TOKEN`; there is no `--token` flag, because a command line can be read by other programs. A token is never sent while the command is still looking for a server: with a token, name the server. For CI, make an access token that ends on a date you choose: ```sh openmausbot token create "Nightly CI" --scope client --expires 90d --out ci-token # on the server, or with an admin token openmausbot token list # name, scope, end date, last used (never the token) openmausbot token revoke ID # it stops working at once ``` A `login` or `connect` session renews itself while it is used, up to 180 days; an access token never renews and ends on its date. `--expires` is at most the server's session limit (180 days unless `OMB_SESSION_MAX_DAYS` says otherwise), and `--scope client`, the default, can chat and answer approvals but not change settings. Tokens are listed and revoked like any session (`openmausbot sessions`, and Settings), and the token itself is written only to `--out`. ## Output and exit codes Without `--json` you get plain lines. With `--json` you get exactly one JSON document on stdout, a failure included (`{ "ok": false, "error", "hint", "exitCode" }`). Progress goes to stderr as one JSON object per line; `--quiet` drops it. Everything printed, either way, has secrets removed (the same redaction the transcript uses). Durations are written `90`, `90s`, `5m`, `2h` or `30d`. | Exit code | Meaning | |---|---| | 0 | Done | | 1 | Failed, stopped or stalled, or you answered no | | 2 | The command line or a file is wrong, or a script left out `--yes` | | 3 | Someone must answer (a question or an approval card) | | 4 | Needs you signed in (`openmausbot login`); for `run` and `wait`, also timed out (the work keeps running) | | 5 | Not allowed, cannot reach the server, or the server is too old | | 6 | Busy (stop it first); for `team apply --check`, it found changes | | 7 | Not found; for `doctor --host`, this machine is missing something the server needs | | 8 | `doctor --data`: the data folder has a problem left (after `--fix`, one it could not repair) | | 130 | Ctrl-C (the work keeps running) | ## Commands Run `openmausbot help VERB` for any of these. A TARGET is a bot or room by name or id, or `--bot ID`, `--channel ID` or `--thread ID`; `--task ID` picks one of its conversations. | Command | What it does | |---|---| | `doctor [--wait 2m]` | Checks the server answers, is new enough, who you are to it (and when your session expires), that an engine is ready, and whether bots have a browser. On a shared server without a session (`docker compose exec omb openmausbot doctor`), it learns only how many engines are ready, not which (`GET /api/health/engines`). | | `doctor --host` | Checks this Linux machine can run the server and the bots' sandbox (below). | | `doctor --data [--fix] [--data-dir DIR]` | Checks this computer's data folder without the server; `--fix` applies the repairs that cannot lose data, while no server uses it ([self-hosting](self-hosting.md#the-doctor-checking-and-repairing-the-data)). | | `status` | Every bot at a glance: working, waiting on you, waiting on teammates, paused, failed or idle, with its computer and team. | | `bots`, `channels`, `models` | Your bots and what each is doing, your rooms, the engines and the models each offers. | | `bots get BOT` | One bot: its team, state, computer, model, approvals and conversations. | | `bots delete BOTS` | Deletes bots with their conversations (below). The MausBot bot and a busy bot are refused. | | `bots pause BOTS`, `bots resume BOTS` | Pauses bots: their work stops and nothing new starts, across restarts, until resumed. `--team` pauses the team itself, so bots added to it later are paused too; `--all` pauses every bot. | | `stop BOTS` (or `bots stop`) | Stops the work these bots are doing now, and pauses nothing: a new message or routine starts them again. | | `threads list BOT`, `threads clear BOT`, `threads delete BOT THREAD…` | A bot's conversations; `clear` deletes all of them and the bot starts one new, empty one. A conversation that is working is kept. | | `computers list`, `computers start BOT`, `computers sleep BOT` | Where each bot works and its cloud computer's state; create or wake a bot's cloud computer (the bot must be set to Cloud computer), or put it to sleep. | | `messages TARGET [--limit 30]` | The latest messages of a conversation. | | `send TARGET TEXT` | Sends one message and returns at once, to the conversation the bot or room has open. `--task new` starts a new conversation for it (`--title` names it, else the message's first line), and `--task ID` picks one. It says which conversation it went to. `--send-id ID` makes a retry safe: the same id never sends twice. | | `run TARGET TEXT` | Gives a bot or room one job and waits until it is done (below). | | `wait TARGET` | Waits on work already running. | | `interrupt TARGET [--tree]` | Presses Stop. `--tree` also stops every teammate still working on its job, in that teammate's own conversation. | | `export TARGET --out DIR` | Writes a conversation's job to a folder (below). | | `events` | The server's live events as JSON lines (below). | | `team apply FILE`, `team export --out FILE` | Makes the workspace match a team file, or writes one (below). | | `engine set KIND`, `engine list` | Gives the workspace an engine key without a screen (below). | | `connect [URL]` | Gets a token for a workspace elsewhere. | | `token create NAME`, `token list`, `token revoke ID` | Access tokens for CI that end on their date (above). | | `new-bot`, `new-channel`, `set-model`, `edit` | Make a bot or a room, change a bot's model, rewrite an earlier message. | | `mcp` | The OpenMausBot MCP server on stdin and stdout ([docs/mcp-server.md](mcp-server.md)). | The message for `send` and `run` can be the next word, `--text TEXT`, `--message-file FILE`, or `-` to read it from stdin. BOTS is one or more bot names or ids, `--team NAME`, or `--all`. The commands that delete or stop many things (`bots delete`, `threads clear`, `threads delete`, `stop --all`) first print exactly what they would touch, then ask. A script passes `--yes` instead (without it they exit 2), and `--dry-run` only prints the list. They need a named server: the one you signed in to, or `--url`/`--port`. There is no flag that skips a permission or an approval. ```text $ openmausbot bots delete --team QA --dry-run Would delete 3 bots on "Studio" (http://127.0.0.1:8799), with their conversations and files: QA Tester 3 (35d41705…), team QA QA Tester 2 (53cbe304…), team QA QA Tester 1 (2edb5834…), team QA Nothing was changed (--dry-run). ``` ## doctor --host Before you install a server, check the machine it will run on: ```text $ sudo openmausbot doctor --host --data-dir /srv/mausbot ok Ubuntu 24.04.1 LTS, kernel 6.8.0-45-generic ok x86_64 ok Docker 27.3.1 FAIL Bot sandbox: AppArmor blocks unprivileged user namespaces fix: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 (and put it in /etc/sysctl.d/ to keep it after a reboot) ok seccomp is available ok cgroup v2 ok 412 GB free for /srv/mausbot warn /srv/mausbot is not on an encrypted disk fix: use LUKS full-disk encryption, unless your provider encrypts the disk at rest ok 8 CPUs, 31 GB memory (a team of 20 needs 8 CPUs and 16 GB) ok Port 8799 is free for the server ok Ports 80 and 443 are free ok Clock is within 1 s of network time (signed requests allow 300 s) 1 problem, 1 warning. ``` It checks the system (Ubuntu 24.04 or 22.04, or Debian 12, are the ones we test), the processor (x86_64; arm64 runs a server but not a self-hosted Team server), Docker or Podman, that unprivileged user namespaces are allowed (the AppArmor and Debian switches), seccomp, cgroup v2, free disk for the data folder (`--data-dir`, else `OMB_DATA_DIR` or `~/.openmausbot`: at least 10 GB, and 100 GB for a Team server), disk encryption, CPUs and memory (a Team needs 4 CPUs and 8 GB), the server's port (`--port`, else 8799), ports 80 and 443 (required with `--domain HOST`, else only a warning), and the clock against network time (signed requests allow 300 seconds). It changes nothing. On a server that runs MausBot's own connector (a team on its own server), it also asks the connector for its checks (`mausbot-connector probe --json`, which starts the bots' box once under the home's own security settings) and lists any that fail. There the home runs under its own AppArmor profile, so AppArmor's server-wide switch can stay on: the user-namespace check passes when the connector's box check does, and otherwise says to run the install command again. A problem fails the check (exit 7) and says its fix on the next line; a warning does not. `--json` prints `{ ok, problems, warnings, checks: [{ id, status, message, fix }] }`. On macOS and Windows it says it checks Linux servers, and exits 7. ## run and wait ```sh openmausbot run "Room Lead" --message-file brief.md --timeout 45m --on-input exit --export ./out ``` `run` starts a new conversation (titled by `--title` or the message's first line) unless `--task current` or `--task ID` says otherwise, sends the message once, and waits for the whole job: the bot's own turn and every piece of work it handed to a teammate, and theirs in turn. Its first progress line names the conversation and when the job began (`since`), so a later `openmausbot wait --thread ID --since MS` can pick the same job up again. - `--wait job` (the default) waits for the bot and every teammate; `--wait turn` only for the bot's own turn; `--wait none` sends and returns. - `--on-input exit` (the default) stops waiting with exit 3 when someone must answer; `wait` keeps waiting for the answer; `stop` stops the job. - `--on-timeout leave` (the default) leaves the work running; `stop` stops it. - `--strict` fails the run (exit 1) if any teammate's part failed, even when the bot finished. - `--export DIR` writes the job to `DIR` once it is done. `DIR` must be new or empty, and that is checked before anything is sent; `--force` writes into a folder that already has files. A teammate the bot sent a one-way notice to, or one still working after the bot was stopped, does not hold the job open: nobody is waiting on it. A message no turn ran for at all (a room set to answer mentions, sent a message that names nobody; a queued message removed before its turn) is not a job done: `run` ends with `state: "idle"` and exit 1. With `--json` the result carries the job's `state` (`completed`, `idle`, `needs-input`, `failed`, `stalled` or `timed-out`), which the exit code follows (`idle` after `run` is exit 1, as above), the job tree, the final reply and the files it links. Its `status` keeps the words MCP clients already read: `settled` there only says the conversation stopped working, so a lead whose work failed is `settled` with `state: "failed"` and exit 1. `wait TARGET` takes the same options. If nothing is running it returns at once with exit 0. `--for turn` waits only for the conversation's own turn. `--since MS` (the number `run` prints, and puts in its "wait again" line) keeps watching the same job: if it ended while nobody was watching, `wait` says how it ended instead of "nothing is running". Ctrl-C prints that line too. If the server drops for a moment (a restart, a proxy in front of it), `run` and `wait` keep asking for the same job until their time runs out; a refusal (an expired token) ends them with exit 5 at once. Stopping a job (`interrupt --tree`, `--on-input stop`, `--on-timeout stop`) presses Stop in its conversation, which ends everything it handed out: teammates mid-turn, what they handed on, and work that never started. If a teammate's own conversation still holds part of it after that (a turn still running, waiting on its own teammates, parked on an answer, or about to run again), Stop is pressed there too. `stopped` (`teammates` for `interrupt --tree`) lists each teammate task that was at work and ended; work that never started is dropped without being listed. The waiting is done by the server: each request is held until the job changes, so a long wait costs one request at a time, not a poll loop. The same answer is available to anyone: `GET /api/threads/:id/job` (add `wait=MS&version=V` to hold it until the job changes from the version you have). ## export ```sh openmausbot export "Room Lead" --out ./rehearsal # its current conversation openmausbot export --thread 3f2a… --out ./rehearsal --root ROOT_ID ``` | Written | What it holds | |---|---| | `manifest.json` | What was written, and anything skipped and why | | `job.json` | The job tree: every piece of work, who did it, how it ended and what it said | | `transcripts/` | Every conversation of the job, as `.json` and `.md`, secrets removed, at most 2,000 messages each | | `files/` | The files the replies link to or attach (a report, screenshots), per conversation | | `screens/` | Screen captures the server kept | Each file is fetched under its own reply's permission, exactly as the app opens a link; a link to something outside that conversation's folders is skipped and listed in `manifest.json`. A reply that links a folder brings the files directly in it. Limits: `--max-files 200`, `--max-screens 100`, `--max-bytes 500MB` (counted on what is written, so a file that runs past it is skipped). A folder with files in it is refused unless `--force`, which replaces what an earlier export wrote there: the files its `manifest.json` lists are removed first, and nothing else in the folder is touched. ## events ```sh openmausbot events --job 3f2a… --until-settled > events.jsonl ``` One JSON line per event: messages as they are written and changed, threads, bots and rooms. `--kind` names the kinds to print instead of those (`--kind message,runtime` is messages and token-level events); `--screens` adds live screen frames. `--thread ID` (repeatable) keeps one conversation's events; `--job ID` follows every conversation of that job as it grows, and `--until-settled` ends when the job does, with its exit code. After a dropped connection it resumes from where it was; the server's first line says whether it could (`"resumed": false` means read the state again). A refusal (an expired token, a missing scope) ends it with exit 5 instead. The output is always JSON lines; `--jsonl` is accepted and changes nothing. ## engine ```sh openmausbot engine set claude --key-env ANTHROPIC_API_KEY --base-url https://gateway.example.com --install openmausbot engine list ``` KIND is `claude`, `openai`, `openrouter`, `openai-compatible` (needs `--base-url`), `xai`, `groq`, `greenference`, `modelgo`, `mistral` or `cerebras`. The key comes from an environment variable (`--key-env`) or a file (`--key-file`), is written once through the same setting the Settings screen uses, and is never printed or read back. An engine that already has a key is left alone unless `--rotate`, so a script can run this on every start. The server never shows the address of a key it has, so on such an engine a different `--base-url` is not written either (it says so): `--rotate` writes both. For `claude`, the key runs every Claude bot (engine `claude`); `--only-claude-api` keeps it to "Claude (API key)" bots (engine `claudeApi`). `--install` installs the engine's command if it is missing, and waits for the install to finish (minutes on a fresh machine). Changing keys needs a session with full access. ## The team file A team file says what the workspace should have: teams and their briefs, bots with their standing instructions, models, approval levels and computers, skills, rooms, and the engines they run on. Write it in YAML or JSON. ```sh openmausbot team apply launch-room.yaml # plan, then apply openmausbot team apply launch-room.yaml --dry-run # only the plan openmausbot team apply launch-room.yaml --check # exit 6 if anything would change (CI) openmausbot team export --team "Launch Room" --out exported.yaml ``` Apply prints its plan, then makes the changes: ```text team "Launch Room": create · brief set (5 lines) bot "Room Lead": create (Chief of Launch Room · claude/claude-sonnet-5-5 · Full access · computer local) bot "Priya": update title "Buyer" → "Skeptical procurement manager"; soul 3 lines changed bot "Old visitor": not in file (kept; --prune deletes it) Plan: 6 to create, 1 to change, 0 unchanged, 0 to delete. Applied: 6 created, 1 changed, 0 deleted. ``` Run it again and it prints `No changes.` and sends nothing: it compares the file with what the server holds, field by field. Bots are matched by name (any case), or by `was:` when you rename one; of two bots with one name, the one already in the file's team. A rename onto a name another bot has is refused. A field the file leaves out is left as it is (a new `model` on the same engine keeps the bot's effort). Teams are never deleted, nor skills the file does not list. Bots and rooms a team no longer lists are deleted only with `--prune`, and only in a team marked `prune: true`. Apply is not atomic: if a step is refused it stops, says what it had already done, and exits 1; applying again carries on. A bot that is in the middle of a turn is changed once it is idle, waiting up to `--wait-idle` (2 minutes) and then reporting it. Every change goes through the same requests the app makes, with the same checks. Apply adds no confirmations of its own: where the server needs one (Auto on this computer, a Chief's access to other teams), the file saying so is the confirmation. ### Fields ```yaml version: 1 # required engines: # optional; needs full access claude: { key: SECRET, baseUrl: URL | SECRET, everyClaudeBot: true, install: false } openai | openrouter | xai | groq | greenference | modelgo | mistral | cerebras: { key: SECRET } openaiCompatible: { key: SECRET, baseUrl: URL | SECRET } # SECRET is { env: NAME } or { file: PATH }. A key written in the file is refused. defaults: BOT FIELDS # every bot gets these unless it sets its own teams: - name: Launch Room # 1-60 characters brief: TEXT | { file: PATH } # the team's shared instructions prune: false # --prune may delete its bots and rooms the file leaves out bots: # at least one - name: Room Lead # 1-100 characters, unique was: Old name # rename that bot instead of making a new one team: Launch Room title: Launch rehearsal lead description: TEXT chief: true # Chief of Staff of its team (one per team); false removes it manages: [Support] # other teams this Chief is also in charge of (every bot reaches every bot anyway) soul: TEXT | { file: PATH } # standing instructions, at most 24,000 bytes model: claude/claude-sonnet-5-5 # INSTANCE/MODEL; openmausbot models lists them effort: none | low | medium | high | xhigh | max approval: ask | edits | auto | full # a new bot starts at full; Custom is set in the desktop app computer: auto | off | browser | local | vm | cloud cwd: /work/room # a full path that exists on the server browser: true | false | { enabled: true, profile: guest } tools: { allow: [SELECTOR], deny: [SELECTOR] } # docs/tool-selection.md; {} means every tool skills: - { file: skills/launch-report/SKILL.md, enabled: true } rooms: - name: Rehearsal team: Launch Room members: [Room Lead, Priya] # bot names brief: TEXT | { file: PATH } responder: everyone | mentions | BOT NAME ``` Paths are relative to the team file. Apply refuses (exit 2), naming where: an unknown field, a duplicate name, two Chiefs in one team, `manages` without `chief`, a model not written as `INSTANCE/MODEL`, a `cwd` that is not a full path on the server (`/work/room`, or `C:\work\room` on a Windows server; `~` is refused too: it would not mean the same there), a missing file or environment variable, a key written into the file, and anything longer than the app takes (a name or title on more than one line or over 100 or 200 characters, a soul or team brief over 24,000 bytes, a room brief over 12,000 characters, a skill over 256 KiB). It warns about a bot with no `computer`: on `auto` it may ask which computer to use, and nobody is there to answer a headless run. An engine's key, and a base URL kept as a secret, are read only when they have to be written: when the engine has no key yet, or with `--rotate-secrets` (on an engine that has a key, the plan says its base URL could not be compared). Souls, briefs and skills are read with LF line ends, and paths in the file may use either separator, so the same file applies alike from a Windows checkout and from Linux CI. Before it writes anything, apply also checks the file against the server (exit 1): every `model` must be one its engine offers, every room member a bot that exists or that the file makes, and every `tools` selection one the bot's engine can hold. Claude, Codex and the other agent engines limit only MCP tools (`mcp:SERVER:TOOL`); a `native:` selector for one of them would stop every turn it runs, so apply refuses it (docs/tool-selection.md lists which engines can limit built-in tools). `tools: {}` or `{ deny: [] }` means every tool: the bot's selection is cleared. `team export` writes the workspace in this format, skills as `SKILL.md` files beside it and engine keys as `{ env: SET_ME }` placeholders, so applying an export to the same workspace prints `No changes.`. A key written into a soul, a brief or a skill is taken out (`«redacted N chars»`), as the app's own team export takes it out, and the export says where; apply leaves a field with that mark as it is, so the secret stays only on the server. ### Example: Launch Room One Room Lead and the visitors who rehearse a launch, on a sandbox with no Claude login: the key runs every Claude bot. ```yaml # launch-room.yaml — openmausbot team apply launch-room.yaml version: 1 engines: claude: key: { env: ANTHROPIC_API_KEY } # or { file: /run/secrets/anthropic } baseUrl: { env: ANTHROPIC_BASE_URL } # your gateway; a plain https:// address works too everyClaudeBot: true # every Claude bot (engine "claude") runs on this key install: true # install Claude Code if the sandbox lacks it defaults: team: Launch Room model: claude/claude-haiku-5-5 approval: full # nobody is there to answer a permission card computer: browser # works only in its own built-in browser browser: { enabled: true, profile: guest } # a fresh temporary profile per bot cwd: /work/visitors # where screenshots go (create it first) teams: - name: Launch Room prune: true brief: | We rehearse a product launch before it happens. Visitors use the site the way a first-time visitor would. Never sign up with real details, pay, post or email anyone. Never ask the person anything: if something blocks you, say exactly what and stop. Save a screenshot at every step as -.png in your folder, and end your report with a Markdown list linking each one. bots: - name: Room Lead chief: true title: Launch rehearsal lead description: Hands the site to every visitor, then writes the launch report. model: claude/claude-sonnet-5-5 effort: medium computer: local cwd: /work/room browser: false soul: { file: souls/room-lead.md } skills: - file: skills/launch-report/SKILL.md - name: Priya title: Skeptical procurement manager soul: | You are Priya, 41, who buys software for a 200-person company. You distrust vague claims and look for pricing, security and who else uses it before anything else. - name: Marcus title: Rushed founder on a phone-sized screen soul: | You are Marcus, 29, running a two-person startup. You give a site 30 seconds, skim headlines, and try the main button first. Use a 390x844 viewport. ``` Then rehearse, wait for every visitor, and keep the report, transcripts and screenshots: ```sh openmausbot run "Room Lead" "Rehearse the launch of https://example.com with every visitor, then write report.md." \ --timeout 45m --export ./rehearsal ``` A Room Lead can brief up to 64 teammates in one turn before any of them reports back. The visitors read sites nobody vetted. A Claude bot keeps its built-in tools (a shell, file edits) whatever its `tools` say, so run them where those tools can do no harm, such as a throwaway sandbox like Launch Room's, or give them an engine that can limit built-in tools. ## In CI ```yaml # .github/workflows/rehearse.yml (a sketch) - run: npm install -g openmausbot @anthropic-ai/claude-code - run: openmausbot serve --no-pair --data-dir "$RUNNER_TEMP/omb" & env: { OMB_ANTHROPIC_API_KEY: "${{ secrets.ANTHROPIC_API_KEY }}" } # the workspace's Claude key from the start - run: openmausbot doctor --wait 2m # the server answers and an engine is ready - run: openmausbot team apply team.yaml - run: openmausbot run "Release checker" "Check the deploy at ${{ env.URL }}" --timeout 20m --strict --export ./out - uses: actions/upload-artifact@v4 with: { name: release-check, path: ./out } ``` `doctor --wait` waits for an engine too, so the server gets its key in its own environment, as here (`OMB_ANTHROPIC_API_KEY`; the team file's `engines:` section, or `openmausbot engine set`, can set it later instead). The step fails when the job fails (exit 1), needs someone (exit 3) or runs out of time (exit 4). To drive a workspace that is already running elsewhere, set `OPENMAUSBOT_URL` and pass a token made with `openmausbot connect` as a secret file (`--token-file`). ## For other agents `openmausbot mcp` serves the same operations as MCP tools on stdin and stdout ([docs/mcp-server.md](mcp-server.md)): `wait_for_conversation` waits on the same job, and returns the same result, as `wait`.