Angelia

Koren Gast · Updated

How to run Claude Code on a Linux server (VPS)

Claude Code on a laptop answers only while the laptop is awake. A small Linux server is always on, and it comes back by itself after a reboot. Since version 0.3.26, Angelia runs there as a systemd user service, so the chats on your phone reach a Claude Code that never sleeps. Linux support is experimental, and this page says what that means. I built Angelia; the Linux service and the server guide are by Yoav, an outside contributor (more below).

Short version: rent an Ubuntu VPS, make Tailscale the only way in, run Claude Code and Angelia as a user that has no sudo, and pair a WhatsApp or Telegram chat. The full server guide has every command, with a check after each step. This page is the overview.

Why a server and not the Mac

The cost: the server holds your secrets (the Claude login, the WhatsApp session, a GitHub key), and it does not have what your Mac has, such as your logged-in browser and your local repos. You clone the repos the agents need onto it. If you have a Mac that stays home and on, running Claude Code 24/7 on your own machine is less work.

The shape of the setup

The steps, in short

Each step in the server guide ends with a check. Do not start the next step until it passes.

  1. Create the server with your SSH key and a firewall that lets in only your own IP, for now.
  2. The base system: updates, automatic security patches, swap, the admin user, and SSH with keys only and no root.
  3. Tailscale, then close the door: join the tailnet with a tag, then drop every public inbound rule.
  4. The angelia user, with no sudo and with linger.
  5. Node and git. Node comes from NodeSource: Ubuntu 26.04's own Node is too old for Angelia. GitHub access is narrow, with a deploy key or a machine account.
  6. Claude Code, logged in from your laptop over SSH.
  7. Angelia and its service.

The Angelia part. Start the installer from your laptop with ssh -t: its setup wizard needs a terminal, and the WhatsApp QR code prints there. Then, as angelia on the server, install the service.

# from your laptop
ssh -t angelia@<tailnet-ip> 'curl -fsSL https://useangelia.com/install | sh'
# on the server, as angelia
angelia check-config
angelia service install

Two things differ from a Mac:

WhatsApp allows one linked device per running copy. Stop the Mac's daemon first (angelia service uninstall there), or pair a second number. To bring an existing instance over, the guide moves it from a Mac with rsync: the WhatsApp session moves with it, so there is no new pairing.

What was measured, and what was not

On 2026-11-17, on Ubuntu 26.04.1 with systemd 259 and Angelia 0.3.26:

Not measured yet: angelia update (there was no newer release to update to), a $ in the config path, and a .inbox folder that is a link being refused. These three, and the sandbox limits below, are why Linux is still called experimental. The runbook lists the six checks. If you run them on your own server, send your distro and systemctl --version: that is how the word goes away.

The sandbox on Linux

A profile's deny rules stop the agent's file tools, not every program the agent runs. A script it writes can read anything the angelia user can. On macOS, sandbox: true closes that gap. On Linux, it is not that simple:

So on a server: no bypassPermissions on any profile someone else can message, and few, narrow secrets on the box. Use a dedicated Google account in its Chrome, deploy keys that each reach one repo, and no cloud API keys. The guide's security section lists what the steps close and what stays open.

What still needs a Mac

The server guide uses Claude Code. Ubuntu's tmux is older than 3.7, so Angelia prints a version warning; it still runs. Windows is not supported yet.

Who built the Linux part

Yoav (@yoavtpr on GitHub) wrote Angelia's systemd user service (pull request #43) and the server guide (#46), measured on a real Ubuntu 26.04 server. I reviewed both and merged them. Thank you, Yoav.

Try Angelia

curl -fsSL https://useangelia.com/install | sh

It checks the release's signature, then a wizard pairs your first chat. Free and open source (MIT). Server guide · Security model · GitHub