# Deploy OpenMausBot on a VPS To keep MausBot and its agents on your current computer and use a VPS only as a bot’s remote desktop, see [Bring Your Own VPS](byo-vps.md) and the [published setup guide](https://docs.openmausbot.com/docs/computers/byo-vps). From a blank Linux server to OpenMausBot running on it around the clock, reachable from your laptop, the desktop app and your phone, with your bots working while every laptop is closed. It assumes nothing beyond being able to open a terminal and paste commands. About twenty minutes, most of it waiting. ## Quick start: one command on your own domain For a fresh Ubuntu 22.04 or 24.04 server (x86-64, at least 2 CPUs, 4 GB of memory and 20 GB of free disk) and a domain name whose A record already points at it: ```sh curl -fsSL https://raw.githubusercontent.com/milind-soni/OpenMausBot/main/deploy/install.sh | sudo sh -s -- --domain maus.example.com ``` The installer ([`deploy/install.sh`](https://github.com/milind-soni/OpenMausBot/blob/main/deploy/install.sh)) does path B below for you and ends with MausBot answering at `https://maus.example.com`. **It checks the server first, and changes nothing while it checks.** Each check that fails prints one sentence saying what to fix, and nothing is installed until all pass: | Check | Passes when | |---|---| | Operating system | Ubuntu 22.04 or 24.04 | | Processor | x86-64, 2 cores or more | | Memory | 4 GB or more (8 GB suggested) | | Free disk | 20 GB or more, where the install and Docker keep their files | | Docker | Docker 24 or newer with the Compose plugin, running, not rootless | | Ports | 80 and 443 are free | | DNS | the domain resolves to this server's public address | | Outbound | HTTPS reaches the image registries (`ghcr.io`, `pkg-containers.githubusercontent.com`, Docker Hub), Let's Encrypt and `raw.githubusercontent.com` | | User namespaces | switched on, for the bots' sandbox | | Bots' sandbox | AppArmor is on with its tools, as it is on a stock Ubuntu | | Clock | within five minutes of the internet's | | Version | a MausBot release to install was found | To run only the checks, add `--check`: ```sh curl -fsSL https://raw.githubusercontent.com/milind-soni/OpenMausBot/main/deploy/install.sh | sudo sh -s -- --check --domain maus.example.com ``` If Docker is missing, the installer asks before installing it with Docker's official script (`get.docker.com`); `--install-docker` says yes ahead of time. It installs nothing else on the server. **Then it installs** everything under one folder, `/opt/openmausbot` (`--dir` picks another): | Path | What | |---|---| | `compose.yaml`, `Caddyfile` | the same server-plus-Caddy setup as path B, Caddy in its own container reaching the server over a socket; written again on every run | | `.env` | your settings: `DOMAIN`, the pinned version (`OMB_IMAGE`) and anything you add, such as [who may sign in with an email](self-hosting.md#sign-in-with-your-email). The installer keeps your lines | | `data/` | everything MausBot stores: chats, bots, engine sign-ins, paired devices. Never touched once it exists | | `caddy/` | the HTTPS certificates | | `update.sh` | the update command, once this repository has it (see below) | | `compose.box.yaml`, `box/` | the sandbox's settings and the files that prepare the server for it | `update.sh` and the sandbox's files are this repository's own, taken from the tag of the version being installed so they match it, and from `main` only when that tag does not have them. The installer says which it used. It runs the newest release, pinned by its version; once a `stable` channel is published it follows that instead. If that version has no bots' sandbox, the checks (`--check` too) say so before anything is downloaded. It never runs `latest`, which follows every commit. It then waits until the server reports healthy and `https://maus.example.com` answers with a valid certificate, and prints the address. **The bots' sandbox.** A MausBot version with the hardened profile runs every bot in a sandbox, away from the server's settings, keys and other bots' files, and Docker's defaults do not let a container build one. For such a version the installer prepares the server (a seccomp profile in `/etc/mausbot` and an AppArmor profile in `/etc/apparmor.d`, the two the MausBot connector installs), starts the server with the four security settings in `compose.box.yaml` (no `--privileged`, no added capability), and then runs the server's own self-check, which among other things confirms that a bot cannot read `config.json`. If a check fails that means a bot could reach something it must not, or that bots would not work, the installer names it and does not report success; so does a self-check that gives no answer, or a check the installer has never heard of. Five checks that are about neither (the kernel keyring, the sandbox's host name, the CPU list, a hosting provider's address, and reaching the public internet) only print a note. For a version without the hardened profile it says the sandbox is not there yet; run the install command again after updating to one that has it. `--no-sandbox` skips all of this, for a server only you sign in to on a host without AppArmor. **Sign in as the first admin** with a one-time link made on the server. Run in a terminal, the installer makes one and prints it when it finishes. It does not when its output goes anywhere else, such as a log, because whoever reads the link can sign in as the admin until it is used or expires. To make one yourself: ```sh cd /opt/openmausbot && sudo docker compose exec omb openmausbot pair --label "First admin" ``` Open the link it prints, or paste it into the desktop app under **+ → Connect to a server**. To sign in with an emailed code instead, run the installer with `--email you@example.com`. - **Update:** `sudo /opt/openmausbot/update.sh`, which backs the data up, checks the new version's health and puts the old one back if it fails. The installer places it once this repository has it and prints the command when it finishes; until then, running the install command again moves to the newest release. `update.sh` pins the version by digest in `.env`, and a later run of the installer keeps that pin. - **Repair:** run the install command again. It checks the server, rewrites its own files and leaves `.env` and `data/` alone. That also moves an install made before Caddy got its own container: Caddy then shared the server's network, and HTTPS went down whenever the server restarted without it. - **Stop:** `--uninstall` stops the server and removes its containers. It deletes nothing: your data stays in `/opt/openmausbot/data`. - **Every other command in this guide** that starts `docker compose` for path B works from `/opt/openmausbot`. - **What the installer contacts:** the registries and Let's Encrypt from the table, GitHub's release list, this repository's files on `raw.githubusercontent.com`, and `cloudflare.com/cdn-cgi/trace` to learn the server's public address for the DNS check. It sends no telemetry. - **Behind a load balancer or NAT** that forwards ports 80 and 443 to the server, set `OMB_INSTALL_SKIP_DNS=1` to skip the DNS check. The installer also accepts the one-time code of a server connected to MausBot. That offering is not available yet. Not on Ubuntu, or prefer to do it by hand? Use one of the three ways below. ## Three ways in, by hand Three ways to make the server reachable are covered. Pick one; the rest of the guide is the same. The short version of every path, including `--lan` and your own cloudflared or proxy (`--public-url`), is at the top of [Self-hosting](self-hosting.md#pick-a-way-in); this guide adds the server setup around it. | | You need | Who can reach it | Best for | |---|---|---|---| | **A. Public address, no domain** (`serve --tunnel`) | an OpenMausBot account (email code) | anyone with a pairing code, over HTTPS | the fastest path; a phone on cellular | | **B. Your own domain** (Docker + Caddy) | a domain name, ports 80/443 | anyone with a pairing code, over HTTPS | a permanent address you own | | **C. Your Tailscale network** (`serve --tailscale`) | Tailscale on the server and your devices | only your tailnet | the most private; nothing public at all | Only need the phone app? Add `--relay` to path B or C on a machine signed in with `openmausbot login --relay` (never on a machine with a path A address), or use it on its own: the app pairs by QR through MausBot Relay, end-to-end encrypted, with no domain, open port or VPN. See [Phones through MausBot Relay](phone-relay-server.md). Whichever you pick, the login is the same: you **pair** each device once with a short code and it stays signed in. A session lasts 30 days; using it with half that or less left renews it to a full 30, up to 180 days from pairing (`OMB_SESSION_TTL_DAYS` and `OMB_SESSION_MAX_DAYS` change both numbers). There is no password. ## Hetzner launch check (2026-09-07) Path A was exercised on a blank Hetzner CX43 (x86-64, Ubuntu 24.04), using Node 24.20.0 and Codex 0.153.4. The published 0.1.60 baseline was followed by local candidate fixes from this change; these results do not certify the unmodified published 0.1.60 package. The paired web UI completed a real GPT-6-Astra chat, two automatically scheduled routine runs, and a browser title/screenshot test. The browser needed the Ubuntu sandbox setup below. A full reboot restored the service and managed tunnel automatically; the existing paired device, bots, chats, and paused schedule remained available. A new real chat turn also succeeded. A stopped application-data backup restored with matching file hashes and SQLite integrity. The restored copy was not started; provider reauthentication and browser-login migration were not tested. Docker, Tailscale, ARM64, other providers, and capacity limits were outside this run. ## What runs on a server, and what does not Runs fully on the server: every engine CLI (Claude Code, Codex, Grok, custom ACP engines), chats, rooms, bot-to-bot coordination, routines, connected apps and custom MCP servers, webhooks, Company Brain, computer use on cloud or container computers, text-to-speech, and the web UI (the server serves it itself). Needs the desktop app instead: dictation and controlling the server's own desktop. Bots browse on a server too, once the browser engine is installed (below). ## Before you start 1. **A server.** Any Linux VPS: Ubuntu 22.04 or 24.04, 2 CPUs and 4 GB of RAM is plenty. You need `sudo` or root. Hetzner, DigitalOcean, Lightsail, a Mac mini in a cupboard: all fine. 2. **Node 24 or newer** for paths A and C (`node --version`). On Ubuntu: ```sh curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs ``` Path B uses Docker instead and needs no Node on the host. 3. **Your engine accounts.** Bots run on the same engine CLIs you use on your laptop, with your subscriptions. You sign them in on the server once, the same way. Connect to the server for everything below: ```sh ssh root@YOUR_SERVER_IP ``` For paths A and C, use the same unprivileged Linux account for setup and the running service. The examples below use `maus` with home `/home/maus`. From an administrator shell, create it if it does not already exist, then switch to it: ```sh sudo useradd --create-home --shell /bin/bash maus sudo -iu maus ``` The login shell also changes into `/home/maus`; run setup there, not from `/root`. Run the `npx` commands and engine sign-ins below in this account. Keep a separate administrator shell for system packages and systemd. If you already signed in as root, sign in again as `maus`; those accounts have different homes and credentials. ## Path A: a public address with one command No domain, no proxy, no open port. The server gets an address like `https://c-7f3a9c.openmausbot.com` through a Cloudflare tunnel; only traffic through the tunnel reaches it, and that traffic still has to pair. ```sh npx openmausbot setup # once: choose AI access, connect, and choose a model npx openmausbot account login # once: an emailed code signs this machine in and reserves its address npx openmausbot serve --tunnel # runs the server there and prints the pairing link with a QR code ``` `setup` connects an AI provider; it is separate from the OpenMausBot account. Use Codex's device-code option over SSH, or enter a hidden API key for a chat-only connection. More engines can be added later. See [CLI setup](cli-onboarding.md). `login` asks for your email, sends an 8-digit code, and prints the address it reserved for this machine. `serve --tunnel` downloads `cloudflared` on the first run (a pinned version with a verified digest, into `~/.openmausbot`), starts the server, connects the tunnel, and after a few seconds prints `tunnel: live at https://…`. Leave it running; see "Keep it running" for a service. The account credentials live in `~/.openmausbot/tunnel-account.json`, readable only by your user. `npx openmausbot account logout` releases the address. Skip to "Install and sign the engines in". ## Path B: your own domain, with Docker One container for the server plus Caddy for HTTPS at `https://maus.example.com`. The [installer](#quick-start-one-command-on-your-own-domain) does these steps for you on Ubuntu. Do them by hand on another system, to build your own image with `ENGINES`, or to see what it does. 1. **Point a name at the server.** In your DNS provider add an **A record** (name `maus`, value the server's public IP). After a few minutes `ping maus.example.com` should answer with that IP. Ports 80 and 443 must be open; most providers open them by default. 2. **Install Docker:** ```sh curl -fsSL https://get.docker.com | sh docker compose version # prints a version; if "command not found", log out and back in ``` 3. **Get the deploy files and set the name:** ```sh git clone https://github.com/milind-soni/OpenMausBot && cd OpenMausBot/deploy cp .env.example .env nano .env # DOMAIN=maus.example.com ; ENGINES=@anthropic-ai/claude-code @openai/codex ``` `ENGINES` lists the engine CLIs baked into your image, separated by spaces. Change it later and rebuild if you add one. 4. **Start it:** ```sh docker compose pull omb && docker compose up -d ./update.sh # move to the stable version (see "Update") docker compose ps # omb "healthy", caddy "running" ``` Caddy requests the certificate on its own; give it a minute. Then `https://maus.example.com` shows a page asking for a pairing code. That is correct: nothing works until you pair. In this path, every `npx openmausbot …` command below is run inside the container instead: ```sh docker compose exec omb openmausbot pair --label "My MacBook" ``` ## Path C: only your Tailscale network From the administrator shell, install Tailscale on the server and sign in (`curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up`). Enable HTTPS certificates for your tailnet once at https://login.tailscale.com/admin/dns (HTTPS Certificates), then run this from the `maus` shell: ```sh npx openmausbot serve --tailscale ``` Tailscale terminates HTTPS with its own certificate and the pairing link uses the server's MagicDNS name (`https://maus.tail1234.ts.net`). `serve` runs `tailscale serve` in the foreground, so the share ends when it stops. Only devices on your tailnet can reach it, which is a very good property for a server that can run tools. ## Give the bots a browser (optional) Bots can browse on a server. Docker (path B) ships the engine and Chrome in the image. For paths A and C, install Linux system libraries once from the administrator shell: ```sh sudo -H npx --yes openmausbot browser install --with-deps ``` Then install the browser in the service account's home, from the `maus` shell: ```sh npx --yes openmausbot browser install ``` The administrator's browser download is in a different home; it does not install the service account's browser. Both commands must finish successfully. On Ubuntu 24.04, AppArmor may also require [administrator sandbox setup](#ubuntu-2404-browser-sandbox). The one-click installer downloads the browser; it does not grant these OS permissions. Then turn the browser on under Settings → Computers, and per bot. Each bot gets its own isolated session whose logins persist across restarts. ## Install and sign the engines in The npm OpenMausBot package does not install model engine CLIs. For paths A and C, install the engine you use in the service account, then sign it in. For example, from the `maus` shell, for Claude: ```sh npm install --global --prefix "$HOME/.local" @anthropic-ai/claude-code export PATH="$HOME/.local/bin:$PATH" claude ``` For Codex, use `@openai/codex` as the npm package and run `codex login --device-auth` to sign in from a headless server. Complete the CLI's account flow in your browser. Repeat only for the engines you use. For path B, run the installed CLI inside the container, for example `docker compose exec omb claude`. Engine logins belong to the service user's home (for example `~/.codex` and `~/.claude`), separately from OpenMausBot's `~/.openmausbot`. Keep that home when restarting or upgrading. The systemd example below includes `~/.local/bin` in PATH. ## Pair your first device `serve` already printed a pairing block when it started in a terminal (a service prints none into its log). For another device later: ```sh npx openmausbot pair --label "Kitchen iPad" ``` ``` Pairing code RR8Y-BLR6-H939 works once, until 10:59 · everything Link https://c-7f3a9c.openmausbot.com/pair#code=RR8Y-BLR6-H939 Desktop app + → Connect to a server, paste the link Phone scan with your camera or the MausBot app ``` - **A browser:** open the link. The code is filled in; press **Connect**. That browser is paired for 30 days, renewed on use as above. - **The desktop app:** choose **+ → Connect to a server** and paste the link, or type the address and the code. The rail at the window's left edge switches between your own machine and every server you added. - **The phone:** scan the QR code from the iOS app's pairing screen, or paste the whole link into its address field. A code from `pair --phone` can chat, approve, and read; creating bots, changing models, and connecting apps stay with you in the server's UI. Worth knowing: a code works **once**, for **10 minutes** (`--ttl 24h` keeps it open up to a day, for a device you set up later; it is still single use, and a server restart ends every open code); the link only works on that address (typing the code by hand: open `…/pair` and enter it); five wrong codes in five minutes from one address lock pairing there for five minutes; `--phone` mints a code for a device that may chat and approve but not change settings or pair others. ## Manage devices Every paired device is a session: ```sh npx openmausbot devices # id, device, scope, last seen, expires npx openmausbot devices revoke ID # signs that device out and closes its stream at once npx openmausbot account status # the address others use, and whether it answers as this server ``` ## Keep it running `npx openmausbot serve` is a plain foreground process. `npx openmausbot service install --tunnel` (or `--tailscale`) writes a unit like the one below for you, with a copy of the release it runs beside your data. To write it by hand for systemd (paths A and C), install a chosen release first, from the `maus` shell. Replace `X.Y.Z` with the published version you want to run: ```sh npm install --global --prefix "$HOME/.local" openmausbot@X.Y.Z ``` Stop the foreground server with Ctrl-C before enabling the service. From the administrator shell, save this as `/etc/systemd/system/openmausbot.service`: ```ini # /etc/systemd/system/openmausbot.service [Unit] Description=OpenMausBot server After=network-online.target [Service] User=maus WorkingDirectory=/home/maus Environment=HOME=/home/maus Environment=PATH=/home/maus/.local/bin:/usr/local/bin:/usr/bin:/bin ExecStart=/home/maus/.local/bin/openmausbot serve --tunnel Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` ```sh sudo systemctl daemon-reload && sudo systemctl enable --now openmausbot journalctl -u openmausbot -f # the server's log, including "tunnel: live at …" ``` Use `--tailscale` instead of `--tunnel` for path C. A service is not a terminal, so `serve` writes no pairing code into the journal; mint one with `npx openmausbot pair` when you need it. Docker (path B) restarts on its own (`restart: unless-stopped`). Adjust the account, home, and PATH if yours differ; Node 24 must be available on that PATH. The service runs the installed CLI directly, so a restart uses the same release without an npm install prompt or an implicit upgrade. ## Update A self-hosted server follows the **stable** channel: a released version that MausBot's own Clouds have run for 48 hours first. The image tag `stable` and [`stable.json`](https://raw.githubusercontent.com/milind-soni/OpenMausBot/channels/stable.json) name it. The tag `latest` follows every change on `main`; it is for trying things out, not for a server you rely on. **Check for updates** in the app compares your server with the stable version. To hear of every release as soon as it is published instead, set `OMB_UPDATE_CHANNEL=newest` in the server's environment. ### From the app: Update server On a Docker install, the server's admins can update it from **Settings → Updates → Update server**, in the desktop app or a browser. It runs the `update.sh` described below: the stable version, a copy of the data first, and the old version and its data back when the new one is not healthy. The app asks first (the server restarts, so anything running stops, and it says how many chats have a bot answering), shows "Updating the server…" while the server is away, reconnects by itself, then says which version it runs now, or that it went back and why. After 15 minutes without the server it says so, with the commands to see its log and to go back. In the desktop app, once the server is newer than the app, the same row offers the app's own update. With `OMB_UPDATE_CHANNEL=newest` the app shows the command instead, because `update.sh` takes the stable version. A server on a build of main (the `latest` image, which a checkout runs when `.env` names no `OMB_IMAGE`) gets no button: the app says so, with `sudo ./update.sh`, which moves it to the stable version once that is newer than the build. The installer sets this up, and every run of the installer refreshes it. In a checkout of this repository, add it from `OpenMausBot/deploy` (it needs systemd, and restarts the server once), and run the same command again after each `git pull`: until you do, the button runs nothing and the app shows this command. ```sh git pull && sudo ./update-runner.sh --install ``` That places `/usr/local/sbin/openmausbot-update-runner`, the systemd units `openmausbot-update.path` and `openmausbot-update.service`, and root's folder `/var/lib/openmausbot-update`: root's own copy of `update.sh`, which is what the button runs, `request`, which the server's container writes, and `status`, which it reads and cannot write. One install per server: a second folder is refused until `--remove` on the first, and `--remove` for any other folder removes nothing. A checkout gets `docker-compose.override.yml` to mount the two (an override of your own, or a link, is left alone, and the script says what to add). `sudo ./update-runner.sh --remove` takes it all away. **A checkout's owner decides what root runs.** The button's update runs as root, but in your checkout: its Compose files and `.env` decide what `docker compose up` starts. So whoever owns that folder can change what root runs when the app asks for an update. `--install` accepts a folder owned by root or by someone in the `docker` group (who can run anything as root through Docker already), and anyone else only with `--trust-folder-owner`. The folder, and every folder above it, may be changed by root and that owner only: not by everyone (unless it has its sticky bit, as `/tmp` does), and not by a group other than root's or the owner's own private group (the one Ubuntu and Fedora give each user, which their default umask makes new folders writable by). The runner checks all this again at every run, and runs nothing when it no longer holds; the refusal names the folder, its owner, group and mode, and the app shows it with the `--install` command. A fresh server installed with the installer passes as it is. On an update the app asked for, `update.sh` writes nothing through a link there (`.update`, `.env`, the Compose files and its temporary files), nor into a `.update` that belongs to anyone but you or the folder's owner; your own run of `./update.sh` uses links there as before. **Who can ask.** Only an admin's own signed-in session sees and presses the button; members never see it, and Clouds that MausBot runs never show it. The request itself is a file in a folder of the server's user, and until the bots' sandbox is on for self-hosted servers, bots run as that user: anything running on the server as that user, a bot or a prompt injection included, can leave the same file. So the runner treats whoever asks as hostile. What any number of requests can cause: - For each stable image that is out, at most one update: the server stops, its data is copied, the new version starts, and if it is not healthy the old version and the copy come back. That stable image is then not tried again from the app on this server until you run `./update.sh` yourself or another stable image is out. So a compromised server can keep one stable release from being tried from the app, by making it fail on purpose; whoever presses the button is told, with the command to try it by hand. It is taken only when the running image's own label is not newer (never by the version the server says it runs; when the two disagree nothing changes); a stable image that names the same version as the running one under a new digest (a re-published image) is taken too. - At most three copies of the data: the two newest that updates from the app made, and the last one your own run of `./update.sh` made, which an update from the app never removes. While the next copy is made and checked, that is about three times the data plus the new copy; `update.sh` refuses to start when the disk has no room for it, and the app then says so, with the commands to list and remove old copies (below). - Updates that stop the server at most once every four minutes. A run with nothing to do stops nothing and does not count, and for five minutes the same answer is given without asking GitHub or the registry again (when the server's own check knows of a newer version, only GitHub is asked whether the stable image changed); any two runs are at least 30 seconds apart. A run during which the server restarts by itself counts as one that stopped it, so it can delay an admin's press by up to four minutes. - Nothing while `/etc/mausbot/policy.json` holds updates (`"updates": "hold"`). It cannot choose a version, image, URL, flag or path, cannot downgrade or roll back (an update an earlier run left unfinished waits for you at a terminal), and cannot write the runner's status, `update.sh`, `.env` or the Compose files. So the most it can cause is one stop, copy and restart (and rollback, when the version fails here) per stable release, which the admins would have pressed for anyway. **Copies of the data.** An update asked for from the app keeps your own last copy and its own two newest ones. A run of `./update.sh` at a terminal removes all but its own once that one has been checked, as above. To see them: `docker volume ls --filter label=com.mausbot.role=update-backup`; to remove one yourself: `docker volume rm `. Without the runner (no systemd, an npm install, Podman) the app shows the command to run on the server instead. ### Path B (Docker): one command, with a way back From `OpenMausBot/deploy`: ```sh git pull && ./update.sh ``` `git pull` brings the current `update.sh` and `docker-compose.yml`; the server image comes from the stable channel, not from your checkout. An install that has no checkout, with its `compose.yaml`, `.env` and `data/` in one folder such as `/opt/openmausbot`, runs the same script on that folder: ```sh curl -fsSL https://raw.githubusercontent.com/milind-soni/OpenMausBot/main/deploy/update.sh -o update.sh sudo bash update.sh --dir /opt/openmausbot ``` An install made with the installer (`deploy/install.sh`) already has `update.sh` in its folder: `sudo /opt/openmausbot/update.sh`. Until a first version has been made stable, `./update.sh` takes the newest release instead, as **Check for updates** does then. The data may be a Docker volume or a folder on the server; the copy keeps every file's owner and mode either way. The script then: 1. Downloads the stable image, by its digest. If that fails it stops, and nothing has changed. It also stops, changing nothing, when that version is older than the one your server says it runs (see "From `latest` to stable" below). 2. Checks there is room for a copy of your data where Docker keeps its volumes, stops the server, checks that it has stopped, and copies everything under `/data` into a new Docker volume named for the update (`deploy_data-before-update-20261110T120000Z`; `openmausbot_data-before-update-…` for `/opt/openmausbot`). It then compares the copy with the data, every file by checksum; a copy that does not match is thrown away, the server is started again, and nothing has changed. The copy from the update before is removed only after this one has matched. The server is down from here until step 4; how long depends on how much data there is. 3. Writes the image into `.env` (`OMB_IMAGE=ghcr.io/milind-soni/openmausbot@sha256:…`) and starts it. An install the installer made while Caddy still shared the server's network gets the installer's current `compose.yaml` and `Caddyfile` here, as a run of the installer would write them (the rollback puts the old ones back). For this repository's `docker-compose.yml`, `git pull` brings the current one; `--check` says when it is needed. 4. Waits, up to two minutes (`OMB_UPDATE_WAIT_S` for longer), until the new server answers `/api/health` steadily, says it is the new version, can still start a bot if it could before (the server's own count of ready engines, `GET /api/health/engines`, which a hardened server answers too; `openmausbot doctor` on a version without it), and Caddy runs again. If it does not, the new version's doctor runs on the data (`openmausbot doctor --data --fix`: in the server's container while it is up, else in a one-off one with the server stopped). When the doctor repaired something, the new version is started once more and step 4 is tried again. [What the doctor checks and repairs](self-hosting.md#the-doctor-checking-and-repairing-the-data). 5. If any of that fails: puts back the data from the copy, `.env` and the old image, starts the old version, and tells you what went wrong. Your server is as it was before step 1, `.env` included, byte for byte. Only when `.env` named a tag that moves (the installer's `stable`, `latest`, or no image at all) does it now name the old version by its digest instead: that tag may have moved since, and a later run of the installer would otherwise follow it. `--rollback` does the same. The copy is put into a new folder inside the data and checked there before it takes the data's place, so a restore that fails (a full disk, say) leaves both the data and the copy as they were: the server stays stopped, the update's journal is kept, and `./update.sh --rollback` tries again once the cause is fixed. A closed terminal or a dropped SSH session does not stop an update: it carries on, and `deploy/.update/update.log` says how it ended. Each step is written to `deploy/.update/journal` before it starts. Ctrl-C undoes the update at once: before the new version starts, nothing has changed; after, the old version and its data are put back. When an update was cut short some other way (a reboot, a killed process), the next `./update.sh` keeps the new version if that is up and healthy. If it is not, it says which version and data going back would put back, and that everything made on the server since that update would be lost, and asks: `yes` goes back, `keep` leaves the server as it is (the copy stays for `--rollback`), and anything else, or no answer at all, changes nothing. Run again after a finished update, it says there is nothing to do. Two runs at once are refused. ```sh ./update.sh --check # what would change; changes nothing ./update.sh --version 0.1.151 # one released version instead of the stable one ./update.sh --rollback # the version and the data from before the last update ./update.sh --allow-older # go ahead although that version is not newer than the one running ``` `--rollback` is for an update that passed its checks and still turned out wrong. It asks first, because everything made since the update (chats, files, settings) is replaced by the copy; `--yes` answers for you. The copy is kept until the next update has made and checked its own. The script's own log is `deploy/.update/update.log`. | The script ends with | Meaning | | --- | --- | | `0` | Updated, or already on that version | | `1` | The update failed; the old version and its data are back | | `2` | The old version or its data could not be brought back; read the last lines it printed, then `./update.sh --rollback` | | `3` | Another update is running | | `4` | Nothing was changed (could not download, not enough disk, the folder cannot be written, a question not answered `yes`, refused) | | `5` | Nothing was changed: the version asked for is older than the one running, or one of the two versions cannot be told; `--allow-older` goes ahead | | `130` | Interrupted with Ctrl-C before the new version started: nothing was changed, and the server was started again | ### From `latest` to stable A server started from the `latest` image runs a build of `main`. Its image is labelled with the branch, not a version, so `update.sh` goes by the version the server itself reports, which is that of the release it was built after, or of the next one. Such a build may already hold changes made after that release, and may have written data in ways the release does not read. So `update.sh` moves it to stable only once the stable version is newer than the version the server reports; until then it says so and changes nothing (exit `5`). Nothing else is needed: the first `./update.sh` after a newer version is made stable moves the server onto it and pins it by digest. To move now anyway, run `./update.sh --allow-older`; the data is copied first, and `--rollback` puts the `latest` build and its data back. If you built the image yourself (`docker compose up -d --build`, with `ENGINES` baked in), `update.sh` refuses to replace it without being told to: keep updating with `git pull && docker compose up -d --build`, or move to the published image with `./update.sh --replace-local-build`. Building needs about 6 GB of memory: on a smaller server, add swap first or use the published image. Engines you install from **Settings → Engines** live on the data volume and survive either way. ### Paths A and C (npm with the service above): the same steps by hand There is no one-command updater for an npm install yet. Do what the script does: copy the data first, install one named version, check it, and keep the way back. Take the stable version number from [`stable.json`](https://raw.githubusercontent.com/milind-soni/OpenMausBot/channels/stable.json) (`"version"`), and note the one you run now (`openmausbot --version`). From the administrator shell, replacing `X.Y.Z`: ```sh sudo systemctl stop openmausbot sudo -iu maus sh -c 'umask 077; tar czf ~/openmausbot-before-update.tgz -C ~ .openmausbot && chmod 600 ~/openmausbot-before-update.tgz' sudo -iu maus npm install --global --prefix /home/maus/.local openmausbot@X.Y.Z sudo systemctl start openmausbot curl -sf http://127.0.0.1:8799/api/health && sudo -iu maus openmausbot doctor ``` If the install fails, or the last line does not end with the server answering and an engine ready, go back (replace `OLD` with the version you noted): ```sh sudo systemctl stop openmausbot sudo -iu maus npm install --global --prefix /home/maus/.local openmausbot@OLD sudo -iu maus sh -c 'mv ~/.openmausbot ~/.openmausbot-failed-update && tar xzf ~/openmausbot-before-update.tgz -C ~' sudo systemctl start openmausbot ``` A service restart by itself does not update the installed package. For foreground `npx` usage, name the release: `npx --yes openmausbot@X.Y.Z serve --tunnel`. ### How far behind a server may fall The desktop and phone apps are built to work with any server version that was the stable one within the last 90 days. An older server keeps running, but the app tells you it is behind, and newer features may not work until you update it. Update at least every 90 days. Routines and queued work survive a restart. A teammate turn running at that moment runs again once at the next start, told to check what it already did, and the bot that asked for it is told. A person's own turn and a running routine are not run again: the conversation says it was interrupted. Update between runs where you can. ## Back up Stop the server before copying its SQLite database: Ctrl-C for a foreground process, or `sudo systemctl stop openmausbot` from the administrator shell for the service above. Stop any engine processes and managed desktops still writing files you intend to back up. For paths A and C, this backs up application state (bots, chats, routines, tunnel credentials, and paired sessions). Run it from the service account's shell: ```sh umask 077 backup_dir=$(mktemp -d "$PWD/openmausbot-backup.XXXXXX") tar czf "$backup_dir/openmausbot-data.tgz" -C "$HOME" .openmausbot chmod 600 "$backup_dir/openmausbot-data.tgz" ``` A full backup also needs your engine credential/configuration paths, such as `~/.codex`, `~/.claude` and `~/.claude.json`, and browser session state under `~/.agent-browser` if used. Include the paths that exist for your installed CLIs, any configured home/data-directory overrides, and workspaces outside the app directory. These are not included in the command above. For path B, the whole `/data` volume includes the container's CLI homes. From `OpenMausBot/deploy`, stop the whole project before archiving, and start it again after; `deploy_data` is the default volume name, so use your actual volume name if you changed the Compose project: ```sh docker compose stop backup_dir=$(mktemp -d "$PWD/openmausbot-backup.XXXXXX") docker run --rm -v deploy_data:/data:ro -v "$backup_dir":/b alpine sh -c 'umask 077; tar czf /b/openmausbot-data.tgz -C /data . && chmod 600 /b/openmausbot-data.tgz' docker compose start ``` To restore that archive, with the project stopped, replace what is in the volume with it (`openmausbot-backup.XXXXXX` is the folder the backup made): ```sh docker compose stop docker run --rm -v deploy_data:/data -v "$PWD/openmausbot-backup.XXXXXX":/b:ro alpine sh -c 'find /data -mindepth 1 -delete && tar xzpf /b/openmausbot-data.tgz -C /data' docker compose start ``` With the installer, the data is the folder `/opt/openmausbot/data`. This backs it up, with `.env`, into an archive in `/opt/openmausbot/backups`, the whole project stopped and started again around it. The folder is `700` and the archive `600` whatever the server's umask or the folder's default ACLs, since the archive holds every chat, key and session: ```sh cd /opt/openmausbot && sudo docker compose stop && sudo sh -c 'set -e; install -d -m 700 backups; f="backups/backup-$(date -u +%Y%m%dT%H%M%SZ).tgz"; (umask 077; tar --warning=no-file-ignored -czf "$f" data .env); chmod 600 "$f"'; sudo docker compose start ``` Copy the archive to another machine and keep it private. `--warning=no-file-ignored` keeps tar from listing the sockets in the data folder, which are not data: the server makes them again when it starts. To restore an archive, replace `backups/backup-20261110T153000Z.tgz` with its name. The data as it is now is moved aside to `data.before-restore`, and the archive's data takes its place, with its owner and permissions. An archive without a `data/` folder changes nothing: ```sh cd /opt/openmausbot && sudo docker compose stop && sudo sh -c 'set -e; tar -tzf backups/backup-20261110T153000Z.tgz data/ >/dev/null; rm -rf data.before-restore; mv data data.before-restore; tar -xzpf backups/backup-20261110T153000Z.tgz data'; sudo docker compose start ``` Once MausBot runs on the restored data, remove the old copy: `sudo rm -rf /opt/openmausbot/data.before-restore`. The restore leaves `.env` as it is. On a new server, install first with the same `--domain`, then restore. Each path B backup creates a fresh private folder in the current directory, so it cannot overwrite an older archive with more permissive access. Keep the archive inside that folder privately on another machine. Restore paths A and C with the server stopped, using the same paths and original ownership. After backup or restore, start the service with `sudo systemctl start openmausbot`. Stop and start the Docker project as a whole, as above, rather than `omb` on its own. ## The rules the setup relies on Read this before putting anything else in front of the server. - The server only ever listens on loopback (`127.0.0.1:8799`). Never publish that port yourself. The tunnel, Caddy and Tailscale each reach it from the same machine; path B's Caddy, in its own container, reaches it over a Unix socket (`OMB_TUNNEL_SOCKET`), and a request on that socket always counts as a remote one. - A request that arrives through a proxy or the tunnel is treated as remote and needs a session, whatever headers it carries. A proxy of your own (nginx, Traefik, Cloudflare Tunnel) must forward the real `Host` and add `X-Forwarded-For` and `X-Forwarded-Proto`, must not buffer the event stream, and must **not** rewrite `Host` to `127.0.0.1`. - Pairing is the login. Want a second wall in front of it? Path B's `Caddyfile` has a commented `basic_auth` block for a shared password. - The session cookie is marked `Secure`; do not serve this over plain HTTP on the public internet. - The one thing a stranger can read is `/.well-known/openmausbot/environment` (the server's id, label, version, capabilities) and `/api/health` (only the app name). Everything else answers "pair this device". ## Troubleshooting **`serve --tunnel` says "no account on this machine yet".** Run `npx openmausbot account login` on this machine first; the credentials are per machine. **The server does not start and says its data "was written by a newer OpenMausBot".** An older version was started on data a newer one had already changed, which happens when a version is put back without its data. Nothing was changed. Install the version the message names (or a newer one), or put back the copy of the data from before that update. **The tunnel stays on "retrying".** The server is running and usable locally; the public hop is not verified yet. Wait a minute (Cloudflare needs a moment on a fresh address), then check `journalctl`/the terminal for the reason. If it never comes up, `npx openmausbot account logout && npx openmausbot account login` issues a fresh address. **Path B: the page never loads or shows a certificate error.** Caddy could not get a certificate. Check that the name resolves to the server and that ports 80 and 443 are open; `docker compose logs caddy` shows the reason. **"forbidden: pair this device to use the server remotely" / "this request came through a proxy".** Expected before pairing, and for tools that call the API without a session. Pair the device. Scripts send `Authorization: Bearer ` with the token from the pairing response instead of a cookie. **Pairing code refused.** It expired (10 minutes, or its `--ttl`) or was used. Mint a new one. "Too many wrong codes. Try again at 11:19." means wait until then. **More errors** (from the desktop's Connect to a server sheet and the CLI's Reach line) are in the [troubleshooting table](self-hosting.md#troubleshooting). **A bot says the engine is not signed in.** Sign that engine in again on the server. **What does the server think it is?** `https://
/.well-known/openmausbot/environment` is public and shows its id, label, version and capabilities; `npx openmausbot account status` prints the same on the server. **Something else.** `journalctl -u openmausbot --since -10m` (or `docker compose logs omb --tail 100`) shows the server's startup lines. Paste them with your question in the community channel. ### Ubuntu 24.04 browser sandbox If Chrome reports `No usable sandbox!` and `sudo journalctl -k --since -10m` shows an AppArmor `DENIED` for `userns`, the browser download is installed but Ubuntu is blocking its sandbox. [Chromium documents this restriction](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md). Do not add `--no-sandbox` or disable `kernel.apparmor_restrict_unprivileged_userns` globally. For paths A and C, an administrator can allow only a trusted, root-owned Chrome copy. Find the service user's downloaded executable: ```sh find /home/maus/.agent-browser/browsers -type f -name chrome -executable ``` Use its actual `chrome-VERSION` directory in every path below; `VERSION` is a placeholder, not a fixed Chrome release. Copy the whole directory, including its libraries, to a new location that the service user cannot modify: ```sh sudo install -d -o root -g root -m 0755 /opt/openmausbot-browser sudo cp -R /home/maus/.agent-browser/browsers/chrome-VERSION /opt/openmausbot-browser/ sudo chown -R root:root /opt/openmausbot-browser/chrome-VERSION sudo chmod -R go-w /opt/openmausbot-browser/chrome-VERSION ``` Save this as the root-owned `/etc/apparmor.d/openmausbot-chrome`, replacing `VERSION` with the same value. Keep the exact executable path: a wildcard under the writable service home would also allow replacement executables. ```text abi , include profile openmausbot-chrome /opt/openmausbot-browser/chrome-VERSION/chrome flags=(unconfined) { userns, } ``` Load the profile: ```sh sudo apparmor_parser -r /etc/apparmor.d/openmausbot-chrome ``` Add the following line under `[Service]` in the systemd unit above, again using the exact installed version, then run `sudo systemctl daemon-reload` and `sudo systemctl restart openmausbot`: ```ini Environment=AGENT_BROWSER_EXECUTABLE_PATH=/opt/openmausbot-browser/chrome-VERSION/chrome ``` For a foreground server, export `AGENT_BROWSER_EXECUTABLE_PATH` to that same path in the `maus` shell before starting `serve`. After a Chrome update, copy the new version and update both the AppArmor profile and service environment; the root-owned copy is not updated by the browser installer. Keep `kernel.apparmor_restrict_unprivileged_userns=1`.