Hesperan

Server guide

Run your bots on your own server.

They keep working while your Mac is closed.

Version 1.3.4 · Free · Early Access · x86_64 31 MB · ARM64 22 MB

MacLinux serverbots run hereiPhone

What works on a server.

Works

  • Chats, from the Mac and iPhone apps
  • Your ChatGPT or Claude plan, API keys, local models (Ollama)
  • Routines, Telegram, memory, skills, extensions
  • Projects and coding tools
  • Each bot's own browser, with live view
  • Approvals, Stop everything, activity log, data export
  • iPhone notifications, with away from home on

Different on a server

  • Bots' own computers: they need a Mac
  • Commands and folders on your Mac
  • Moving your Mac's bots to a server
  • One-click plan sign-in from the Mac app: for now you sign in on the server once

What you need

  • A 64-bit Linux computer that stays on: x86_64 or ARM64 (such as a Raspberry Pi 5), 2 GB of memory
  • Docker with Compose, or Node.js 22.12 or newer
  • Your free Hesperan account
  • Hesperan Bots on your Mac, or the iPhone app. The versions don't have to match.
  • The same home network or Tailscale. Away from home works without opening a port.

Get the package

  1. On the download page, choose Server for Linux (x86_64) or (ARM64). Not sure? uname -m on the server.
  2. No browser on the server? The download page has a command to paste.

Install it

With Docker easiest

In the folder with the package
tar -xzf hesperan-bots-server-*-linux-*.tar.gz
cd hesperan-bots-server-*-linux-*/
docker compose up -d --build
docker compose logs hesperan-bots    # the pairing link
  • The first start takes a few minutes.
  • All data is in the volume hesperan-bots_hesperan-data.
  • A name for your devices: HESPERAN_SERVER_NAME=Home server in .env next to compose.yaml, then docker compose up -d

Without Docker

Needs Node.js 22.12+ and Chromium (sudo apt install chromium)
tar -xzf hesperan-bots-server-*-linux-*.tar.gz
cd hesperan-bots-server-*-linux-*/
sudo ./install.sh
journalctl -u hesperan-bots-server -n 40    # the pairing link
  • Data: /var/lib/hesperan-bots · Settings: /etc/hesperan-bots/server.env
  • Ubuntu 24.04: if the bots' browsers don't start, add HESPERAN_CHROMIUM_NO_SANDBOX=1 to server.env. The log says so.

The log shows a pairing link (hesperan://pair…). Its code works once, for 5 minutes. A new one: hesperan-bots-server pair (Docker: docker compose exec hesperan-bots hesperan-bots-server pair).

Pair your Mac

  1. In Hesperan Bots 1.1.0 or newer: I have a Hesperan Bots server on the welcome screen, or Settings → Server → Pair with your server.
  2. Paste the pairing link, or enter address with port, code and verification key.
  3. Check that the 4-digit number matches the server's log.
  4. Choose Use my server. Your Mac's own bots stay untouched; switch back in Settings → Server.

And your iPhone

In the iPhone app: Pair, then scan the QR code or paste the link. A paired Mac shows the QR code in Settings → Devices. Try the iPhone app (TestFlight beta)

Choose a model

  • Your ChatGPT or Claude plan: install Codex or Claude Code on the server and sign in there once.
  • Or an API key, or Ollama on the server or in your network: Settings → Models in the app.

Away from home

Devices reach the server through hesperan.com, encrypted end to end. No router port needed.

Sign the server in once
hesperan-bots-server sign-in
# Docker: docker compose exec -it hesperan-bots hesperan-bots-server sign-in
  1. Open the address it prints and sign in. Copy the final 127.0.0.1 address back into the terminal. (Or from a paired Mac: Settings → Account → Sign in.)
  2. Pair with hesperan-bots-server pair --away, then allow the device: hesperan-bots-server allow 4821

Day to day.

Everyday commands

WhatWith DockerWithout Docker
How it's doingdocker compose exec hesperan-bots hesperan-bots-server statussudo -u hesperan-bots hesperan-bots-server status
A pairing code… hesperan-bots-server pairthe same
Paired devices… hesperan-bots-server devicesthe same
Remove a lost device… hesperan-bots-server remove "My iPhone"the same
The logdocker compose logs -f hesperan-botsjournalctl -u hesperan-bots-server -f
Stop and startdocker compose stop / docker compose up -dsudo systemctl stop / start hesperan-bots-server
Update./update.shsudo hesperan-bots-server update

Updates

A signed-in server checks twice a day and shows new versions in status. Make a backup first.

From the app: Settings → Server → Update server. The server tries the new version and goes back by itself if it doesn't start. Where it can't (not signed in, running as root), the app shows the command to run, with a button to copy it.

  • Without Docker, root then finishes the update: a small helper from install.sh installs that version into /opt/hesperan-bots, checked against hesperan.com, and restarts once more. Servers installed before it get it with one sudo hesperan-bots-server update. Turn it off: sudo systemctl disable --now hesperan-bots-server-update.path
  • With Docker, run ./update.sh now and then: it also renews the image (Chromium, the system).

On the server itself:

  • Docker: ./update.sh. It downloads and checks the package itself; it needs curl.
  • Docker, once, for folders from 1.3.2 and before: their update.sh still trusts the container. For this one update, download the package on your account page and run ./update.sh <file> with it.
  • Without Docker: sudo hesperan-bots-server update. It also brings /opt up to date after an update from the app.
  • Not signed in: download the package, then ./update.sh <file> or sudo hesperan-bots-server update --from <file>

Backup and restore

Backup with Docker
docker compose stop
docker run --rm -v hesperan-bots_hesperan-data:/data -v "$PWD":/backup debian tar -czf /backup/hesperan-backup.tgz -C /data .
docker compose up -d
Backup without Docker
sudo systemctl stop hesperan-bots-server
sudo tar -czf hesperan-backup.tgz -C /var/lib/hesperan-bots .
sudo systemctl start hesperan-bots-server

To restore, unpack into the empty data folder or volume while the server is stopped. The backup holds the key to your saved logins: keep it private.

Uninstall

  • Docker: docker compose down, then docker volume rm hesperan-bots_hesperan-data to delete the data
  • Without Docker: sudo ./install.sh --remove (also removes the update helper), then sudo rm -rf /var/lib/hesperan-bots and sudo userdel hesperan-bots
  • Remove the server from your Mac, iPhone and account page.

Questions? Short answers · hello@hesperan.com