SeiraDocs
Self-hosting

Deploy on a VPS

From a blank Linux server to Seira running around the clock, reachable from your laptop, the desktop app and your phone.

This guide moves the whole Seira server and its agents to the VPS. To keep Seira on your current computer and use only a remote desktop container, follow Your own VPS (BYO).

Three ways in, one login

A public address with one command, your own domain with Docker, or your Tailscale network. Whichever you pick, devices pair once with a short code and stay signed in: a session lasts 30 days, and using it with half that or less left renews it to a full 30, up to 180 days from pairing. A device in regular use re-pairs twice a year; one that goes quiet for a month re-pairs. No password.

From a blank Linux server to Seira 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:

curl -fsSL https://raw.githubusercontent.com/seira-bot/seira/main/deploy/install.sh | sudo sh -s -- --domain seira.example.com

The installer (deploy/install.sh) does path B below for you and ends with Seira answering at https://seira.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:

CheckPasses when
Operating systemUbuntu 22.04 or 24.04
Processorx86-64, 2 cores or more
Memory4 GB or more (8 GB suggested)
Free disk20 GB or more, where the install and Docker keep their files
DockerDocker 24 or newer with the Compose plugin, running, not rootless
Ports80 and 443 are free
DNSthe domain resolves to this server's public address
OutboundHTTPS reaches the image registries (ghcr.io, pkg-containers.githubusercontent.com, Docker Hub), Let's Encrypt and raw.githubusercontent.com
User namespacesswitched on, for the bots' sandbox
Bots' sandboxAppArmor is on with its tools, as it is on a stock Ubuntu
Clockwithin five minutes of the internet's
Versiona Seira release to install was found

To run only the checks, add --check:

curl -fsSL https://raw.githubusercontent.com/seira-bot/seira/main/deploy/install.sh | sudo sh -s -- --check --domain seira.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):

PathWhat
compose.yaml, Caddyfilethe same server-plus-Caddy setup as path B, Caddy in its own container reaching the server over a socket; written again on every run
.envyour settings: DOMAIN, the pinned version (OMB_IMAGE) and anything you add, such as who may sign in with an email. The installer keeps your lines
data/everything Seira stores: chats, bots, engine sign-ins, paired devices. Never touched once it exists
caddy/the HTTPS certificates
update.shthe 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://seira.example.com answers with a valid certificate, and prints the address.

The bots' sandbox. A Seira 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 Seira 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:

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 Seira. 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.

You needWho can reach itBest for
A. Public address, no domain (serve --tunnel)a Seira account (email code)anyone with a pairing code, over HTTPSthe fastest path; a phone on cellular
B. Your own domain (Docker + Caddy)a domain name, ports 80/443anyone with a pairing code, over HTTPSa permanent address you own
C. Your Tailscale network (serve --tailscale)Tailscale on the server and your devicesonly your tailnetthe most private; nothing public at all

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:

    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:

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 seira with home /home/seira. From an administrator shell, create it if it does not already exist, then switch to it:

sudo useradd --create-home --shell /bin/bash seira
sudo -iu seira

The login shell also changes into /home/seira; 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 seira; 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.

npx @seira-bot/seira login          # once: an emailed code signs this machine in and reserves its address
npx @seira-bot/seira serve --tunnel # runs the server there and prints the pairing link with a QR code

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 @seira-bot/seira 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://seira.example.com.

The installer 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 seira, value the server's public IP). After a few minutes ping seira.example.com should answer with that IP. Ports 80 and 443 must be open; most providers open them by default.

  2. Install Docker:

    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:

    git clone https://github.com/seira-bot/seira && cd seira/deploy
    cp .env.example .env
    nano .env                # DOMAIN=seira.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:

    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://seira.example.com shows a page asking for a pairing code. That is correct: nothing works until you pair.

In this path, every npx @seira-bot/seira … command below is run inside the container instead:

docker compose exec omb openmausbot pair --label "My MacBook"

On ARM64: Raspberry Pi 4/5 and ARM servers

The image is published for both linux/amd64 and linux/arm64, and Docker pulls the one that matches the machine, so the steps above are the same on an ARM64 server or a Raspberry Pi 4 or 5. Use a 64-bit system (Raspberry Pi OS 64-bit or Ubuntu Server for ARM; uname -m prints aarch64) and at least 4 GB of RAM. When you change ENGINES, docker compose build builds the image on the machine itself.

On ARM64 the bots' browser is Debian's Chromium, because Chrome for Testing has no Linux ARM64 build. Once it runs, open https://seira.example.com from any browser and pair it as below.

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 seira shell:

npx @seira-bot/seira serve --tailscale

Tailscale terminates HTTPS with its own certificate and the pairing link uses the server's MagicDNS name (https://seira.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:

sudo -H npx --yes @seira-bot/seira browser install --with-deps

Then install the browser in the service account's home, from the seira shell:

npx --yes @seira-bot/seira 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. If the service account has no browser and the built-in browser is on, serve on an x64 or arm64 server downloads Chrome for Testing (about 190 MB) into its data directory when it starts. That needs unzip, and the system libraries from the first command are still needed.

On Ubuntu 24.04, AppArmor may also require administrator sandbox setup. The one-click installer downloads the browser; it does not grant these OS permissions.

Then turn the browser on under Settings → Experimental, and per bot. Each bot gets its own isolated session whose logins persist across restarts.

Install and sign the engines in

The npm Seira 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 seira shell, for Claude:

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 Seira'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:

npx @seira-bot/seira 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 Seira 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); 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:

npx @seira-bot/seira devices               # id, device, scope, last seen, expires
npx @seira-bot/seira devices revoke ID     # signs that device out and closes its stream at once
npx @seira-bot/seira status                # what the server says about itself

Keep it running

npx @seira-bot/seira serve is a plain foreground process. For systemd (paths A and C), install a chosen release first, from the seira shell. Replace X.Y.Z with the published version you want to run:

npm install --global --prefix "$HOME/.local" @seira-bot/seira@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:

# /etc/systemd/system/openmausbot.service
[Unit]
Description=Seira server
After=network-online.target

[Service]
User=seira
WorkingDirectory=/home/seira
Environment=HOME=/home/seira
Environment=PATH=/home/seira/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/usr/bin/env seira serve --tunnel
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
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 @seira-bot/seira 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 Seira's own Clouds have run for 48 hours first. The image tag stable and 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 seira/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.

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 Seira 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 <name>.

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 seira/deploy:

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:

curl -fsSL https://raw.githubusercontent.com/seira-bot/seira/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/seira-bot/seira@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; seira doctor on a version without it), and Caddy runs again.
  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.

./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 withMeaning
0Updated, or already on that version
1The update failed; the old version and its data are back
2The old version or its data could not be brought back; read the last lines it printed, then ./update.sh --rollback
3Another update is running
4Nothing was changed (could not download, not enough disk, the folder cannot be written, a question not answered yes, refused)
5Nothing 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
130Interrupted 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 ("version"), and note the one you run now (seira --version). From the administrator shell, replacing X.Y.Z:

sudo systemctl stop openmausbot
sudo -iu seira sh -c 'umask 077; tar czf ~/openmausbot-before-update.tgz -C ~ .openmausbot && chmod 600 ~/openmausbot-before-update.tgz'
sudo -iu seira npm install --global --prefix ~seira/.local @seira-bot/seira@X.Y.Z
sudo systemctl start openmausbot
curl -sf http://127.0.0.1:8799/api/health && sudo -iu seira seira 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):

sudo systemctl stop openmausbot
sudo -iu seira npm install --global --prefix ~seira/.local @seira-bot/seira@OLD
sudo -iu seira 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 @seira-bot/seira@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 turn running at that moment does not, so update between runs.

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:

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 seira/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:

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):

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:

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:

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 Seira 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 @seira-bot/seira login on this machine first; the credentials are per machine.

The server does not start and says its data "was written by a newer Seira". 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 @seira-bot/seira logout && npx @seira-bot/seira 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 <token> 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.

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://<address>/.well-known/openmausbot/environment is public and shows its id, label, version and capabilities; npx @seira-bot/seira 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. 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:

find /home/seira/.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:

sudo install -d -o root -g root -m 0755 /opt/openmausbot-browser
sudo cp -R /home/seira/.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.

abi <abi/4.0>,
include <tunables/global>

profile openmausbot-chrome /opt/openmausbot-browser/chrome-VERSION/chrome flags=(unconfined) {
  userns,
}

Load the profile:

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:

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 seira 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.

On this page