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
- It does not sleep. No energy settings, no lid, no laptop in a bag.
- It starts at boot, with nobody logged in. On a Mac, Angelia's service starts at login, so after a reboot it waits for one. On Linux, a user service with linger starts at boot.
- Your Mac stays yours. The agents work in the server's folders, not on the computer you use every day.
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 box. A Hetzner VPS with Ubuntu 26.04 (24.04 works too), x86. The guide was measured on x86 only. Its swap step assumes a 4 GB server; 2 GB is too small once the optional desktop and Chrome run.
- The way in. Tailscale only. The Hetzner firewall and
ufwdrop all inbound traffic from the internet, and the Tailscale policy lets you reach the server but not the server reach your devices. Angelia opens no port at all: its API is a Unix socket. - Two users.
adminhas sudo, installs packages and runs nothing.angeliahas no sudo and runs everything: the daemon, Claude Code, and the optional extras. - The service.
angelia service installwrites a systemd user unit, enables it and starts it. Linger makes it start at boot. It restarts the daemon after a failure. - The chat. WhatsApp or Telegram on your phone, as on the Mac. Nothing changes on the chat side.
- Optional. A small desktop with Chrome for agents that drive a browser, Syncthing to pass files back and forth, Claude Remote Control, and a twice-daily sync of the workspace to a private repo.
The steps, in short
Each step in the server guide ends with a check. Do not start the next step until it passes.
- Create the server with your SSH key and a firewall that lets in only your own IP, for now.
- The base system: updates, automatic security patches, swap, the
adminuser, and SSH with keys only and no root. - Tailscale, then close the door: join the tailnet with a tag, then drop every public inbound rule.
- The
angeliauser, with no sudo and with linger. - 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.
- Claude Code, logged in from your laptop over SSH.
- 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:
angelia initoffers the service on macOS only. On Linux, runangelia service installyourself.- Claude Code ignores a profile's extra folders (
add_dirs) until the workspace has passed its trust dialog. The guide gives a one-line fix.
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:
- The service: active, with linger on.
- A reboot with nobody logged in: the daemon was up 11 seconds after boot, and WhatsApp reconnected.
/restartfrom a group: the chat heard "Restarting now" and then "Angelia is back up". The restarter ran as its own unit, and systemd counted no restarts of the service.
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:
- It does not start out of the box on Ubuntu 26.04. Claude Code's sandbox on Linux is bubblewrap, and Ubuntu's AppArmor rules block what it needs. The guide's fix gives Claude Code its own copy of
bwrapwith its own AppArmor profile, named in Claude Code's managed settings (the bwrap step). - With that step, it holds in
acceptEdits. Measured with Claude Code 2.1.327: a write to the home folder, a read of Angelia's API token and a request to a domain not on the list were all refused. - It does not hold in
bypassPermissions. There, the sandbox still blocks writes, but not reads or network.angelia check-configdoes not know this yet: it accepts a group open to everyone inbypassPermissionswhen the sandbox is on, because that holds on macOS. On Linux, do not rely on it.
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
- Scheduled jobs.
angelia jobs installis macOS only. On Linux, write systemd timers that callangelia jobs run <profile> <job>. Arun:job of a profile withsandbox: trueis refused on Linux. - Voice replies.
angelia speakuses the voice built into macOS. - The pi backend. Its sandbox is macOS's own.
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