Koren Gast · Updated 18 November 2026

# 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](https://useangelia.com/guides/claude-code-linux-server/#credits)).

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](https://useangelia.com/docs/linux-server/) 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](https://useangelia.com/guides/claude-code-24-7/) 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 `ufw` drop 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.** `admin` has sudo, installs packages and runs nothing. `angelia` has no sudo and runs everything: the daemon, Claude Code, and the optional extras.
- **The service.** `angelia service install` writes 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](https://useangelia.com/docs/linux-server/) ends with a check. Do not start the next step until it passes.

1. [Create the server](https://useangelia.com/docs/linux-server/#0-create-the-server-hetzner-console) with your SSH key and a firewall that lets in only your own IP, for now.
2. [The base system](https://useangelia.com/docs/linux-server/#1-base-system-as-root-once): updates, automatic security patches, swap, the `admin` user, and SSH with keys only and no root.
3. [Tailscale, then close the door](https://useangelia.com/docs/linux-server/#2-tailscale-then-close-the-door-as-admin): join the tailnet with a tag, then drop every public inbound rule.
4. [The `angelia` user](https://useangelia.com/docs/linux-server/#3-the-angelia-user-as-admin), with no sudo and with linger.
5. [Node and git](https://useangelia.com/docs/linux-server/#4-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](https://useangelia.com/docs/linux-server/#5-claude-code), logged in from your laptop over SSH.
7. [Angelia](https://useangelia.com/docs/linux-server/#8-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 init` offers the service on macOS only. On Linux, run `angelia service install` yourself.
- 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](https://useangelia.com/docs/linux-server/#8-angelia).

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](https://useangelia.com/docs/linux-server/#moving-an-instance-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.
- **`/restart` from 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](https://useangelia.com/docs/runbook/#linux-server-over-tailscale) 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 `bwrap` with its own AppArmor profile, named in Claude Code's managed settings ([the bwrap step](https://useangelia.com/docs/linux-server/#sandbox-true-on-ubuntu-2604)).
- **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-config` does not know this yet: it accepts a group open to everyone in `bypassPermissions` when 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](https://useangelia.com/docs/linux-server/#security) lists what the steps close and what stays open.

## What still needs a Mac

- **Scheduled jobs.** `angelia jobs install` is macOS only. On Linux, write systemd timers that call `angelia jobs run <profile> <job>`. A `run:` job of a profile with `sandbox: true` is refused on Linux.
- **Voice replies.** `angelia speak` uses 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](https://github.com/yoavtpr)) wrote Angelia's systemd user service ([pull request #43](https://github.com/korengast/angelia/pull/43)) and the server guide ([#46](https://github.com/korengast/angelia/pull/46)), measured on a real Ubuntu 26.04 server. I reviewed both and merged them. Thank you, Yoav.

## More guides

- [How to run Claude Code 24/7 on your own machine](https://useangelia.com/guides/claude-code-24-7/)
- [How to control Claude Code from your phone](https://useangelia.com/guides/claude-code-from-phone/)
- [Claude Code notifications and approvals on your phone](https://useangelia.com/guides/claude-code-phone-notifications/)
- [Claude Code on WhatsApp and Telegram: four ways compared](https://useangelia.com/guides/claude-code-whatsapp-telegram/)

## 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](https://useangelia.com/docs/linux-server/) · [Security model](https://useangelia.com/docs/security/) · [GitHub](https://github.com/korengast/angelia)

Angelia · open source, MIT [Docs](https://useangelia.com/docs/) · [info@useangelia.com](mailto:info@useangelia.com) · [GitHub](https://github.com/korengast/angelia)
