Skip to content

Install on a server

On a Linux server with systemd:

Terminal window
curl -fsSL https://hotline.dev/install | sh -s -- --server

It downloads the server build for your architecture, checks it against the release’s checksums, installs hotline to /usr/local/bin, writes the unit below, and starts the desk. It asks for sudo when it needs it, and for the listen address and public URL, or takes them as --listen and --public-url. Once the desk is up it shows a pairing QR, so keep your phone handy.

The desk runs as you, whether you ran the installer as yourself or with sudo, so it sees the claude and codex you installed and signed in to. Run as root with nobody behind it, as on a fresh VPS, it uses the one person’s account on the machine if there is exactly one. Otherwise it creates a hotline service account and tells you how to set up a harness for it (sudo -u hotline -H bash, then install and sign in). The desk never runs as root. To choose, pass --user:

Terminal window
curl -fsSL https://hotline.dev/install | sh -s -- --server --user "$USER"

The unit then runs as you, with your home, and puts ~/.local/bin and ~/.npm-global/bin first on its PATH. --user hotline asks for the separate account. It only applies to a first install; an upgrade never changes who the desk runs as. A desk that runs as you runs its teammates’ tools as you, so use the service account on a server that is shared or holds anything you wouldn’t hand an agent. Harnesses and the account the desk runs as covers moving a desk that is already installed.

The installer detects an existing install and reports its version and the available version. It asks before updating when a terminal is attached; --yes skips that question, as does running without a terminal. An install already at the requested version is left alone unless you pass --force. Pass --listen and --public-url again to change them (add --force when keeping the same version); if the desk won’t start with the new values, the previous unit goes back.

For a server that only relays and runs no agents, a Raspberry Pi say, add --relay:

Terminal window
curl -fsSL https://hotline.dev/install | sh -s -- --server --relay

A re-run keeps what the server is: one installed with --relay is updated only with --relay, and one installed without it is never made a relay by the installer. Each says so and stops before changing anything.

A teammate without a computer can have a web browser of its own on the server, as it does on the desktop: it reads pages, fills forms and signs in with the logins you give it, and you watch and take control from your phone or your desktop app. See Desk browser. It needs WebKitGTK, a virtual display (Xvfb) and fonts, about 500 MB on Ubuntu or Debian, x86_64 or ARM, so it is opt-in. Add --browser:

Terminal window
curl -fsSL https://hotline.dev/install | sh -s -- --server --browser

A first install at a terminal asks instead. To add the browser to a server installed without it, run the installer again with --browser. On a server already on the latest release it only adds the packages and restarts the desk. A relay runs no teammates, so --relay --browser is refused. On a distribution without apt-get, install WebKitGTK 4.1, Xvfb and fonts yourself, then sudo systemctl restart hotline. The desk says what it found when it starts:

Terminal window
journalctl -u hotline | grep Browser:
Browser: on for teammates without a computer (WebKitGTK 2.50.4).

Without them the line says Browser: off and why (see Troubleshooting), the desk runs as before, and its teammates have no browser. A server never shares your own browsers’ cookies: when a teammate asks to be signed in, you give it a login or take control and sign in yourself. See Sign-ins.

The browser is hotline-browser, installed beside hotline and started by the desk at a teammate’s first page. Each teammate’s pages run in a process of their own, on a private display no other user on the server can reach. The browser takes about 450 MB of memory with one teammate on a simple page, and a teammate browsing heavy sites takes 500 to 600 MB of its own. If it stops, the desk starts it again at the next page; one that keeps stopping waits first, from a second doubling up to a minute, and the teammate is told how long.

For a server installed at /usr/local/bin/hotline with the hotline systemd unit:

Terminal window
hotline update --check # report the installed and available versions
sudo /usr/local/bin/hotline update # install the latest server release

To choose a particular release, including an intentional downgrade:

Terminal window
sudo /usr/local/bin/hotline update --version X.Y.Z

The updater downloads the server archive for your architecture, verifies its SHA-256 checksum, and replaces only the binaries, hotline and the browser’s hotline-browser, with an atomic rename. The room, pairings and systemd unit stay untouched. If the unit is running, it restarts and the updater checks that the desk comes back; a failed start restores the previous binary and tries to restart it. A stopped unit stays stopped. Without root, the command prints the exact sudo command to run; --check never needs root and never changes the install.

Rollback restores the executable, not room-data changes a newer release may have made. Keep an encrypted backup of the room, taken with the service stopped, before upgrading or downgrading. If recovery also fails, the updater preserves the old binary and prints its backup path; inspect journalctl -u hotline before recovering manually.

This command is only for the Linux server binary. Desktop installs use the app’s updater or their package manager; hotline update does not overwrite .deb, .rpm, AppImage, macOS app or Windows setup installations.

Older releases, including 0.26.0, do not have hotline update. For that first upgrade, rerun the installer once:

Terminal window
curl -fsSL https://hotline.dev/install | sh -s -- --server

It keeps the existing room, pairings and unit. Use hotline update after that. An older binary without --version may be reported as unknown when its running desk’s version is not readable; the installer still offers the upgrade.

The rest of this page is the same install done by hand.

Each release from 0.26.0 carries hotline-server_<version>_linux_x86_64.tar.gz and hotline-server_<version>_linux_aarch64.tar.gz, each with the hotline binary, the browser’s hotline-browser and a systemd unit. To build it yourself instead:

Terminal window
cargo build --release -p hotline-cli # target/release/hotline
cargo build --release -p hotline-browser # the browser, which needs libwebkit2gtk-4.1-dev
Terminal window
tar xzf hotline-server_*_linux_x86_64.tar.gz
sudo install -m 0755 hotline-server_*/hotline /usr/local/bin/hotline
sudo install -m 0755 hotline-server_*/hotline-browser /usr/local/bin/hotline-browser
sudo useradd --system --create-home --home-dir /var/lib/hotline --shell /usr/sbin/nologin hotline
sudo install -m 0644 hotline-server_*/hotline.service /etc/systemd/system/hotline.service
sudo systemctl edit --full hotline # set --listen and --public-url, below
sudo systemctl daemon-reload
sudo systemctl enable --now hotline

The unit runs as the hotline account with the room at /var/lib/hotline/room. It sets HOME, PATH and HOTLINE_DATA_DIR itself and reads no login shell, so add to its PATH what your teammates need: a Node install for harnesses run through npx, for example.

--listen and --public-url are both required.

Terminal window
hotline serve --store file --listen 192.0.2.10:9443 --public-url https://desk.example:9443
  • --listen is exactly one local IP and a fixed port. Wildcards (0.0.0.0), port zero and falling back to another address are refused. IPv6 goes in brackets: --listen '[2001:db8::10]:9443'. If the address isn’t up yet at boot, the desk waits for it.
  • --public-url is where the phone connects: an https:// address with a DNS name or IP, or a TLS proxy in front of the desk. It goes into the pairing QR. Don’t put credentials or a query in it.
  • TLS is self-signed unless you pass --tls-cert fullchain.pem --tls-key key.pem, which the account the desk runs as must be able to read. --tls self says the default out loud. The phone trusts the server’s key, not its certificate, so rotating certificates never breaks a pairing.
  • --store file keeps secrets as owner-only files under the room. Encrypt the disk, and its snapshots and backups. native uses the OS credential store, which a server usually doesn’t have.

Open the port in your firewall for the phones that will connect, and nothing else. Only a phone holding a pairing gets past the handshake; to anything else the port offers nothing but TLS and a closed door.

Terminal window
sudo -u "$(systemctl show -p User --value hotline)" HOTLINE_DATA_DIR=/var/lib/hotline/room hotline status

A fresh room says No teammate can run yet: connect a model provider. That is expected: pair your phone, then connect a model.