Angelia on a Linux server
This guide covers a Hetzner VPS running Ubuntu 26.04 (24.04 works too), with these pieces:
- Tailscale is the only way in.
- Claude Code and Angelia run as a user that has no sudo.
- Optional: a small desktop with Chrome for agents that drive a browser.
- Optional: Syncthing to move files between your laptop and the server.
- Optional: Claude Remote Control.
- Optional: a twice-daily sync of the workspace to a private repo.
Each step ends with a Check. Do not start the next step until the check passes.
The shape
admin | Your login. It has sudo and installs packages. Nothing runs as admin. |
angelia | No sudo. It runs the Angelia daemon, Claude Code, Chrome, VNC and Syncthing as systemd user units, with linger. |
| Inbound | None from the internet. The Hetzner firewall and ufw both drop everything; Tailscale gets through without an open port. |
| VNC, Syncthing GUI | Bound to 127.0.0.1 only. You reach them through an SSH tunnel over Tailscale. |
Everything angelia can read, an agent with a shell can read too. On Linux the sandbox for profiles works only with the extra bwrap step in step 8, not in bypassPermissions, and it is experimental. So the plan below keeps the secrets on this box few and narrow. Read Security before you pair any chat.
0. Create the server (Hetzner console)
A new Hetzner account may have to pass a verification first, by credit card or ID document, before it can create a server. Turn on two-factor authentication for the account too: whoever gets into it controls the server.
- Project. Create a project for it (here
angelia), so its firewall, keys and billing stay apart from anything else. - Firewall (Firewalls → Create Firewall). One inbound rule: TCP 22 from your current IP only (
curl -s https://api.ipify.org). You remove it in step 2. Leave outbound open.- The form starts with TCP 22 and ICMP from any address. Remove both "Any" sources and the ICMP rule.
- In the source field, Enter confirms the address but can also submit the whole form. Check the rules on the firewall's page afterwards.
- Server (Servers → Add Server).
- Type: x86. This guide was measured on x86 only. Google ships Chrome for arm64 Linux too, but no step here was run on ARM. Measured 2026-11-17: the cheaper Cost-Optimized (CX) line was out of stock. In the Regular Performance line, CPX22 (2 vCPU, 4 GB, 80 GB) was $19.49/mo and CPX32 (4 vCPU, 8 GB) $35.49. CPX12 (2 GB) is too small once the desktop and Chrome from step 6 run.
- Size can only grow. Rescaling to a smaller type fails once the disk is bigger, so start small.
- Location: Helsinki has no surcharge. Nuremberg and Falkenstein add $3.50 to $6.50/mo for about 10 ms less latency from the Middle East, which a chat bot does not notice.
- Image: Ubuntu 26.04 LTS (systemd 259, tmux 3.6). 24.04 works too.
- The rest: public IPv4 ($0.60/mo) and IPv6 on, your SSH public key added (then no root password is ever sent), the firewall from above selected.
- Backups. Optional. A backup or snapshot holds every secret on the box (Claude login, WhatsApp session,
ghtoken), so treat it as sensitive.
Check: ssh root@<public-ip> works with your key and asks for no password.
1. Base system (as root, once)
export DEBIAN_FRONTEND=noninteractive
apt update && apt full-upgrade -y
apt install -y unattended-upgrades ufw git tmux jq curl ca-certificates
echo 'unattended-upgrades unattended-upgrades/enable_auto_updates boolean true' | debconf-set-selections
dpkg-reconfigure -f noninteractive unattended-upgrades
timedatectl set-timezone Asia/Jerusalem # yours; timers and logs follow it
# Swap, 4 GB (the RAM of a CPX22): several agents and an npm ci will otherwise stall the box
fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab
# Your admin user, with your key, and sudo without a password
adduser --disabled-password --gecos '' admin
usermod -aG sudo admin
install -d -m 700 -o admin -g admin ~admin/.ssh
install -m 600 -o admin -g admin /root/.ssh/authorized_keys ~admin/.ssh/
echo 'admin ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/90-admin && chmod 440 /etc/sudoers.d/90-admin && visudo -c
admin has no password at all. Getting in already takes your SSH key or your tailnet login, and nothing runs as admin. If you want sudo to ask for a password anyway, run passwd admin and drop the sudoers line.
Test admin from a second terminal before you lock root out: ssh admin@<public-ip> sudo -n true must succeed. Then:
# SSH: keys only, no root
cat > /etc/ssh/sshd_config.d/10-hardening.conf <<'EOF'
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
AllowUsers admin angelia
X11Forwarding no
AllowAgentForwarding no
EOF
sshd -t && systemctl reload ssh
Check:
ssh admin@<public-ip> sudo -n trueworks.ssh root@<public-ip>saysPermission denied (publickey).sudo sshd -T | grep -E '^(permitrootlogin|passwordauthentication|x11forwarding|allowagentforwarding) 'printsnofor all four. TCP forwarding stays on, since tunnels need it.
2. Tailscale, then close the door (as admin)
On your laptop: install Tailscale (brew install --cask tailscale, or the App Store) and sign in. Signing in the first time creates your tailnet.
In the admin console (Access controls → JSON editor), replace the default policy. The default lets every device reach every other, so a compromised server could open ports on your laptop. Put in your laptop's Tailscale IP (tailscale ip -4 on it):
{
"tagOwners": {
"tag:server": ["autogroup:admin"],
},
"grants": [
// Your own devices, to each other (tagged servers are not part of autogroup:self).
{"src": ["autogroup:member"], "dst": ["autogroup:self"], "ip": ["*"]},
// You, to the server. No rule has tag:server as src, so it starts no connection.
{"src": ["autogroup:member"], "dst": ["tag:server"], "ip": ["*"]},
],
"ssh": [
{"action": "check", "src": ["autogroup:member"], "dst": ["autogroup:self"], "users": ["autogroup:nonroot", "root"]},
],
"tests": [
{"src": "tag:server", "deny": ["<laptop-tailscale-ip>:22"]},
],
}
- The tag must exist before the server joins.
--advertise-tagsfails for a tag the policy does not name. A tagged node's key does not expire, so the server will not drop off the tailnet after 180 days. - The
testsblock checks the policy on every save. A policy that lets the server reach your laptop is refused. - No Tailscale SSH for the server. You reach it with plain
sshand your key, over its tailnet address. That keeps two locks, the tailnet and the key, and works for scripts. Tailscale SSH'scheckmode would ask for a browser login instead.
On the server:
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --advertise-tags=tag:server --hostname=angelia # prints a login link: open it, Connect
tailscale ip -4 # the server's tailnet address
From here on, use ssh admin@<tailnet-ip>, or ssh admin@angelia with MagicDNS. Then close everything public:
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow in on tailscale0
sudo ufw --force enable
In the Hetzner console, delete the TCP 22 rule. The firewall now has no inbound rules; keep it attached as a second wall.
Check:
ssh admin@<tailnet-ip>works from your laptop.ssh admin@<public-ip>times out.- On the server,
timeout 5 bash -c '</dev/tcp/<laptop-tailscale-ip>/22'fails.tailscale pingstill answers, since it is not a connection the policy governs. sudo ss -tulpnshows onlytailscaledandsshdon0.0.0.0/[::].ufwdropssshd's port from the internet.
3. The angelia user (as admin)
sudo adduser --disabled-password --gecos '' angelia # no sudo, no password
sudo chmod 700 ~angelia
sudo loginctl enable-linger angelia # its units run at boot, with nobody logged in
sudo -l -U angelia # must say: not allowed to run sudo
id angelia # angelia (and users on 26.04). Never add sudo, docker, lxd or adm
Check:
ssh angelia@<tailnet-ip>gives you a shell. Copy your key first:sudo install -d -m 700 -o angelia -g angelia ~angelia/.ssh && sudo install -m 600 -o angelia -g angelia ~/.ssh/authorized_keys ~angelia/.ssh/.- In that shell,
systemctl --user statusanswers. loginctl show-user angelia -p LingersaysLinger=yes.
From here on, every command runs as angelia unless it starts with sudo. For those, open a second ssh admin@<tailnet-ip>.
4. Node and git
Node from NodeSource puts it at /usr/bin/node. That path survives Node upgrades, and the service file records it. The NodeSource script runs as root:
# as admin
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs gh
# unattended-upgrades takes only Ubuntu's own origins by default; add NodeSource
printf '%s\n' 'Unattended-Upgrade::Origins-Pattern {' ' "site=deb.nodesource.com";' '};' | sudo tee /etc/apt/apt.conf.d/52unattended-upgrades-nodesource
Then, as angelia, keep global npm packages in its own home, so npm i -g never needs sudo:
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile && . ~/.profile
umask 077 && echo 'umask 077' >> ~/.profile # new files private by default
git config --global user.name "Angelia (server)"
git config --global user.email "<you>@users.noreply.github.com"
GitHub, narrow. Give the server its own SSH key: ssh-keygen -t ed25519 -C angelia-server. Then pick one:
Deploy keys. Add the key as a deploy key on each repo the server needs, with write access only where it must push. You can revoke it alone.
A machine account, when agents open pull requests across several repos. Measured here: a dedicated bot user with write access to the org's repos. Log
ghin as the bot. The device-code login works over SSH, so no token is pasted anywhere:ssh -t angelia@<tailnet-ip> 'gh auth login --hostname github.com --git-protocol ssh --web'- Answer "Upload your SSH public key" with
~/.ssh/id_ed25519.pub, and open github.com/login/device signed in as the bot, not as yourself. - Ubuntu's
gh2.46 has no--skip-ssh-key. - With no keyring on the server, the token lands in
~/.config/gh/hosts.yml(mode 600). The deny floor keeps agents' file tools out of it. - Then drop the key-upload scope. The login granted
admin:public_key, which lets the token add more SSH keys to the bot. A key added that way outlives the token. Remove the scope withgh auth refresh -h github.com -r admin:public_keyand approve the code again as the bot.
- Answer "Upload your SSH public key" with
Check:
node --versionshows 24.22.1 or newer (measured: 24.22.3). Ubuntu 26.04's ownnodejsis 22.22.1, too old for Angelia.which nodeprints/usr/bin/node.sudo unattended-upgrade --dry-run -d 2>&1 | grep -i 'allowed origins'includessite=deb.nodesource.com.npm prefix -gprints~/.localin full (echo ~/.local).ssh -T git@github.comnames the deploy key's repo, or the bot's account.- With a machine account:
gh auth statuslists scopes withoutadmin:public_key(measured:gist,read:org,repo).
5. Claude Code
curl -fsSL https://claude.ai/install.sh | bash # lands in ~/.local/bin
From your laptop, log in with a real terminal (the login is interactive):
ssh -t angelia@<tailnet-ip> '~/.local/bin/claude' # /login; full login, not a setup token
For profiles with sandbox: true, Claude Code's sandbox on Linux is bubblewrap, and it needs socat for its proxy. As admin:
sudo apt install -y bubblewrap socat
Ubuntu 24.04+ restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns = 1). It also ships an AppArmor profile for bwrap, so bwrap still works. Check it as angelia: bwrap --ro-bind / / --dev /dev --proc /proc --unshare-all echo ok must print ok (measured on 26.04). That does not make the sandbox work yet: on 26.04 sandboxed commands also need the bwrap copy from step 8.
The login prints a URL. Open it on your laptop and paste the code back. Credentials land in ~/.claude/.credentials.json; make sure it is mode 600.
Check:
claude -p "say ok"answers.stat -c %a ~/.claude/.credentials.jsonprints600.
6. Optional: a desktop for the browser (xfce, TigerVNC, Chrome)
Skip this unless agents need a browser (--chrome), or you need to step in for a login or a captcha. Angelia runs without it. On a 4 GB server it costs about 0.5 GB of RAM while it runs. Measured 2026-11-17 on 26.04: installed, then turned off with systemctl --user disable --now desktop vnc.
# as admin
sudo apt install -y xfce4 xfce4-terminal dbus-x11 tigervnc-standalone-server
curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] https://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-stable
printf '%s\n' 'Unattended-Upgrade::Origins-Pattern {' ' "site=dl.google.com";' '};' | sudo tee /etc/apt/apt.conf.d/52unattended-upgrades-chrome
The last line lets unattended-upgrades patch Chrome too. On an ARM server, write arch=arm64 in the deb line.
As angelia, add two user units: the X server, and the desktop on it. The socket's folder must exist before the first start.
mkdir -m 700 ~/.vnc
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/vnc.service <<'EOF'
[Unit]
Description=TigerVNC display :1 on a Unix socket only angelia can open
[Service]
ExecStart=/usr/bin/Xtigervnc :1 -rfbport -1 -rfbunixpath %h/.vnc/vnc.sock -rfbunixmode 0600 -SecurityTypes None -geometry 1600x1000 -depth 24 -nolisten tcp
Restart=on-failure
[Install]
WantedBy=default.target
EOF
cat > ~/.config/systemd/user/desktop.service <<'EOF'
[Unit]
Description=xfce on :1
After=vnc.service
Requires=vnc.service
[Service]
Environment=DISPLAY=:1
ExecStartPre=/bin/sleep 2
ExecStart=/usr/bin/dbus-launch --exit-with-session /usr/bin/startxfce4
Restart=on-failure
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now vnc desktop
There is no VNC password and no TCP port: the server listens on a Unix socket that only angelia can open, and you reach it with your SSH key over the tailnet. With no password, every process of the angelia user can open that socket too, agents included (see Security, point 3).
ssh -N -L 5901:<angelia-home>/.vnc/vnc.sock angelia@<tailnet-ip> # then open vnc://localhost:5901
<angelia-home> is the angelia user's home folder (echo ~angelia on the server).
macOS Screen Sharing may refuse a server without a VNC password. TigerVNC's viewer (brew install --cask tigervnc-viewer) connects.
Inside the VNC desktop:
- Open Chrome.
- Sign in with a dedicated Google account, not your main one.
- Install the Claude in Chrome extension and log in.
- Leave this Chrome running. Sessions started with
--chromedrive it.
Check:
ss -tlnpshows no VNC port, and~/.vnc/vnc.sockissrw-------.- The tunnel shows the xfce desktop.
- After
sudo reboot, the desktop comes back on its own.
7. Optional: Syncthing (laptop ⇄ server)
Skip this unless you want to hand files to agents, and take results back, without scp. Angelia runs without it.
- Who dials whom. The laptop dials the server (
tcp://<server-tailnet-ip>:22000). Tailscale lets the replies back, so the tailnet policy needs no grant fromtag:server. - Homebrew on macOS:
brew services start syncthingstays down until/opt/homebrew/var/logexists.
# as admin
sudo apt install -y syncthing
# as angelia
systemctl --user enable --now syncthing
mkdir -p ~/sync/in ~/sync/out
The GUI listens on 127.0.0.1:8384. Reach it with ssh -N -L 8384:127.0.0.1:8384 angelia@<tailnet-ip>. In the GUI:
- Settings → GUI. Set a user and password.
- Settings → Connections.
- Listen address:
tcp://<server-tailscale-ip>:22000. - Turn off global discovery, relaying and NAT traversal. Sync then goes only over the tailnet.
- Listen address:
- Add your laptop as a device, by its device ID, with the address left at
dynamic: the server does not dial it. On the laptop, give the server's address astcp://<server-tailnet-ip>:22000. - Share the folders.
~/sync/inis Receive Only on the server: you hand files in.~/sync/outis Send Only on the server: results come out.
On the laptop, keep the synced out folder away from anything that runs or opens files on its own: not ~, not the Desktop, not a watched folder.
Check:
- A file dropped into the laptop's
inappears on the server. ss -tlnpshows 8384 only on127.0.0.1, and 22000 only on the Tailscale IP.
8. Angelia
Linux support ships in 0.3.26 and is marked experimental until the runbook checks below pass on a real server.
curl -fsSL https://useangelia.com/install | sh # checks the release signature; installs under ~/.local; then runs angelia init
angelia --version # 0.3.26 or newer
angelia check-config
angelia service install # writes ~/.config/systemd/user/angelia.service, enables it, starts it
WhatsApp allows one linked device per running copy. Stop the Mac's daemon first (angelia service uninstall there), or pair a separate number.
The installer ends with angelia init, the wizard, unless an instance already exists. The WhatsApp QR prints in this terminal. Run the installer with ssh -t: that last step opens /dev/tty, and without one it prints cannot open /dev/tty after installing.
Trust the workspace once. Claude Code ignores a profile's add_dirs until the folder has passed its trust dialog. The log line reads Ignoring 1 permissions.additionalDirectories entry … this workspace has not been trusted. Set the flag without the dialog:
jq '.projects["'"$HOME"'/.angelia/workspace"].hasTrustDialogAccepted = true' ~/.claude.json > ~/.claude.json.new && mv ~/.claude.json.new ~/.claude.json
Expect a tmux version warning if Ubuntu's tmux is older than 3.7 (24.04 has 3.4, 26.04 has 3.6). Angelia still runs.
Check: run the six steps in runbook → Linux server over Tailscale:
- the service;
- a reboot with nobody logged in;
/restartkeeping tmux panes;angelia update;/restartwith a$in the config path;- a
.inboxlink being refused.
Measured 2026-11-17 on Ubuntu 26.04.1, systemd 259, Angelia 0.3.26:
- Service:
active, linger on. - Reboot with nobody logged in: the daemon was up 11 s 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 (angelia is up under systemdindaemon.out), andNRestarts=0.- Not yet measured:
angelia update(no newer release), a$in the config path, and the.inboxlink.
Send the maintainers your distro and systemd version (systemctl --version | head -1), so they can drop the word "experimental".
Moving an instance from a Mac
Measured 2026-11-17, moving a 0.3.25 Mac instance to 0.3.26 here.
On the Mac. Back up the instance (
cp -a ~/.angelia ~/.angelia.bak-<date>), then runangelia service uninstallandangelia jobs remove <profile>for each profile with jobs. The WhatsApp link must run in one place only.Copy it over the tailnet:
rsync -a --chmod=Du=rwx,Dgo=,Fu=rw,Fgo= --exclude api.sock --exclude daemon.pid --exclude status.json --exclude sessions.json ~/.angelia/ angelia@<tailnet-ip>:.angelia/wa/moves with it, so WhatsApp needs no new pairing.sessions.jsonstays behind: its Claude sessions live in the Mac's~/.claude.
On the server.
- Rewrite the paths:
grep -rIl /Users/<you> --exclude-dir=wa ~/.angelia | xargs sed -i "s#/Users/<you>#$HOME#g". - Clone every
add_dirsrepo to the same place under$HOME. - Run
angelia check-configandangelia accept --check, which only lists the changes. Thenangelia accept, andangelia compile <profile> --writefor each profile. The Linux deny rules (keyrings,.config/google-chrome,.config/systemd/user) arrive only with that compile. - Run
angelia service install.
- Rewrite the paths:
Jobs do not move.
angelia jobs installis macOS only. Write systemd timers that callangelia jobs run <profile> <job>, or leave the jobs off. Arun:job of a profile withsandbox: trueis refused on Linux: its sandbox is macOS only for now.
sandbox: true on Ubuntu 26.04
Measured 2026-11-17 with Claude Code 2.1.327 and Angelia 0.3.26.
1. It does not start. bwrap itself works, but every sandboxed command fails with apply-seccomp: write /proc/self/setgroups (nested userns is capability-restricted …).
- The kernel log shows
apparmor="DENIED" profile="unpriv_bwrap" capability=sys_admin. - Ubuntu's
bwrap-userns-restrictprofile runs everything inside an unprivileged bwrap underunpriv_bwrap, which hasaudit deny capability. - An allow in
local/unpriv_bwrapdoes not lift thatdeny. AppArmor 4'spriority=can override it, but then for every program that runs underunpriv_bwrap. The copy below opens one binary only.
The fix, in a root shell (sudo -i as admin), gives Claude a bwrap copy under its own profile. Ubuntu's /usr/bin/bwrap keeps its restrictive one:
install -d -m 755 /usr/local/lib/claude-bwrap && install -m 750 -o root -g angelia /usr/bin/bwrap /usr/local/lib/claude-bwrap/bwrap
printf '%s\n' 'abi <abi/4.0>,' 'include <tunables/global>' 'profile claude-bwrap /usr/local/lib/claude-bwrap/bwrap flags=(unconfined) {' ' userns,' '}' > /etc/apparmor.d/claude-bwrap
apparmor_parser -r /etc/apparmor.d/claude-bwrap
echo 'DPkg::Post-Invoke { "[ -x /usr/bin/bwrap ] && install -m 750 -o root -g angelia /usr/bin/bwrap /usr/local/lib/claude-bwrap/bwrap || true"; };' > /etc/apt/apt.conf.d/99claude-bwrap
# Point Claude Code at the copy. If the file exists already, add the key to it instead.
install -d -m 755 /etc/claude-code
printf '%s\n' '{' ' "sandbox": { "bwrapPath": "/usr/local/lib/claude-bwrap/bwrap" }' '}' > /etc/claude-code/managed-settings.json
chmod 644 /etc/claude-code/managed-settings.json
- Why managed settings. Claude Code reads
sandbox.bwrapPathonly from managed settings (/etc/claude-code/managed-settings.jsonon Linux), so no user, project or local file can point the sandbox at another binary. That is why the key did nothing in~/.claude/settings.jsonor--settings: the denial still namedunpriv_bwrap. Root owns the file, so no agent can change it. - Not a
bwraplink in~/.local/bin. That folder is on the service'sPATH, and the agent of any profile without the sandbox can write there: it could swap the binary for every sandboxed profile. - It applies to every Claude Code session on the box,
admin's too. It only names the binary; it does not turn the sandbox on. Onlyangeliaand root can run the copy (mode 750, groupangelia), so a sandboxed session of any other user, such asadmin, fails. - The cost: that one binary may create user namespaces, as every program could before Ubuntu 24.04. Mode 750 and group
angeliakeep it toangeliaand root. - Check: in a
claudesession asangelia,/statuslistsEnterprise managed settings (file)under setting sources. Then ask Claude, in a sandboxed profile, to runtouch ~/sandbox-probe: it fails withRead-only file system, andsudo dmesg | grep unpriv_bwrapshows no new denial. The measurement below used aPATHlink; the managed-settings route is from the Claude Code settings reference, so run this check.
2. Once it starts, it holds in acceptEdits, and not in bypassPermissions. Probes from a sandboxed Bash in a compiled profile:
| Probe | acceptEdits | bypassPermissions |
|---|---|---|
Write to ~ | refused (Read-only file system) | refused |
| Write in the profile folder | allowed | allowed |
Open ~/.angelia/api.token (Read(...) deny) | refused (Permission denied) | readable |
curl https://example.com (not in allowedDomains) | refused (deny network-outbound) | 200 |
- Do not use
bypassPermissionswith the sandbox on Linux. With it, the sandbox still blocks writes but not reads or network. angelia check-configdoes not know this yet. It lets a group open to everyone (allow_from: "*") runbypassPermissionswhensandbox: true, because that holds on macOS. Do not rely on it on Linux.- Shell commands still ask. Since Claude Code 2.1.324,
sandbox.autoAllowBashIfSandboxeddefaults tofalse, so a sandboxed command goes through the profile's permission mode like any other. Do not set it totrueon a profile other people write in. Note thatechoand other read-only commands run without asking.
9. Optional: Claude Remote Control in ~/.angelia
A Claude session on the server that you open from claude.ai/code or the Claude app, for looking after the instance (logs, the table, angelia commands) without SSH. It starts at boot.
As angelia, once: trust the folder, then answer Remote Control's one-time consent at a real terminal.
jq '.projects["'"$HOME"'/.angelia"].hasTrustDialogAccepted = true' ~/.claude.json > ~/.claude.json.new && mv ~/.claude.json.new ~/.claude.json
ssh -t angelia@<tailnet-ip> 'cd ~/.angelia && ~/.local/bin/claude remote-control --name angelia-server --permission-mode default'
# answer y to "Enable Remote Control?", wait until it is connected, then Ctrl+C
Without that consent the service exits with "Enable Remote Control?" got no answer.
Then add the unit:
# ~/.config/systemd/user/claude-rc.service
[Unit]
Description=Claude Remote Control in ~/.angelia
After=network-online.target
[Service]
WorkingDirectory=%h/.angelia
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=%h/.local/bin/claude remote-control --name angelia-server --permission-mode default
Restart=always
RestartSec=30
[Install]
WantedBy=default.target
systemctl --user daemon-reload && systemctl --user enable --now claude-rc
Restart=always, noton-failure. Remote Control gives up and exits after about 10 minutes without a network, and its exit code is not documented.- The account matters. Remote Control needs the full login from step 5, not a setup token. The session appears under that account's claude.ai/code.
- This session is not an Angelia profile. None of the deny floor applies to it: it can read
~/.angelia/env,wa/andapi.token. - Who can drive it. Anyone who gets into that claude.ai account can. Keep the account's 2FA on, and keep the session's permission mode at
default, neverbypassPermissions.
Check:
systemctl --user is-active claude-rcprintsactive, andNRestarts=0.journalctl --user -u claude-rcshowsCapacity: 0/32and aclaude.ai/code?environment=…link.angelia-serveris listed in claude.ai/code. Measured 2026-11-18 with Claude Code 2.1.327.
10. Optional: sync the workspace to a private repo twice a day
The workspace is the instance's memory: profiles, instructions and the table. A server lost without it is lost for good.
- The
.gitignorewritten byangelia initkeeps secrets out:.state/,.inbox/, logs,.envfiles, keys,*credentials*.json,*token*.json,auth.jsonandsecrets/. A profile's.claude/settings.local.jsonis generated settings and is committed: no token lives there. The daemon gives each agent its token in the environment at launch. angelia workspace syncscans before it commits. It runs the same secret scan asangelia workspace commitand leaves a secret-shaped file out, and says so. Do not replace it with a plaingit add -Aandgit commit, which skip the scan.- Check before the first push:
git -C ~/.angelia/workspace ls-files | grep -E '(^|/)(\.state|\.inbox|secrets)/|(^|/)\.env'must print nothing.
The repo. Create a private repo with the server's GitHub identity:
gh repo create <org>/angelia-workspace --private
That needs the gh login of a machine account. With deploy keys there is no gh login: create the private repo in the browser, and add the server's key there as a deploy key with write access.
The script, ~/.local/bin/angelia-workspace-sync (mode 700). It merges origin/main first, then lets Angelia commit and push. On a conflict, or when the merge would overwrite a change not yet saved, it stops and saves nothing:
#!/bin/sh
set -eu
cd "$HOME/.angelia/workspace"
git remote get-url origin >/dev/null 2>&1 || git remote add origin git@github.com:<org>/angelia-workspace.git
git fetch -q origin
if git rev-parse -q --verify origin/main >/dev/null; then
git merge -q --no-edit origin/main || { git merge --abort || true; echo "merge failed; nothing saved" >&2; exit 1; }
fi
exec angelia workspace sync --quiet
angelia workspace sync prints what it did, such as saved 3 files, pushed, and nothing at all with --quiet when there was nothing to save. It fails when the commit or the push fails, so the unit shows the failure.
The units, in ~/.config/systemd/user/:
angelia-workspace-sync.service:Type=oneshot,Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin,ExecStart=%h/.local/bin/angelia-workspace-sync.angelia-workspace-sync.timer:OnCalendar=*-*-* 16,23:00:00,Persistent=true(a sync missed while the server was down runs at boot),WantedBy=timers.target.
systemctl --user enable --now angelia-workspace-sync.timer
A merged table does not take effect on its own. A routing.yaml changed on GitHub and merged here still waits for angelia accept (or /restart confirm), because the daemon runs on the accepted copy.
Check:
systemctl --user start angelia-workspace-syncexits without an error, andjournalctl --user -u angelia-workspace-sync -n 5showssaved 1 file, pushedorsaved N files, pushed(or no line, when there was nothing new).- After a run that saved files,
git -C ~/.angelia/workspace log -1 --format=%s origin/mainshowsWorkspace sync <date>: 1 fileorWorkspace sync <date>: N files. systemctl --user list-timersshows the next run.git -C ~/.angelia/workspace ls-tree -r --name-only origin/main | grep -E '(^|/)(\.state|\.inbox|secrets)/|(^|/)\.env'prints nothing.
Security
Done by the steps above
- No root anywhere it matters.
- Root cannot log in.
adminhas sudo but runs nothing.angeliahas no sudo and belongs to no privileged group.docker,lxdandadmare each as good as root, or close to it.- Nothing Angelia needs,
service installand/restartincluded, asks for sudo. The one exception is linger, which you set in step 3.
- No public port.
- The Hetzner firewall and
ufwboth drop inbound traffic. - Angelia opens no port at all. Its API is a Unix socket under
~/.angelia. - If you set up the optional desktop or Syncthing: VNC listens on a Unix socket only
angeliacan open (with no password, so everyangeliaprocess can: see point 3 under "What stays open"), and Syncthing's GUI on localhost and its sync port on the tailnet only.
- The Hetzner firewall and
- The server cannot reach your devices. No Tailscale grant has
tag:serveras its source. SSH to the server needs both your tailnet login and your key; the policy'stestsblock refuses any change that lets the server reach your laptop. - Private files. The home folder is 700, so other users cannot open what is in it.
umask 077in~/.profilecovers your login shells only: systemd user units do not read~/.profile, so the daemon and the units keep their own umask. Angelia keeps~/.angelia/envat 600, and Claude keeps its credentials at 600. - Angelia's deny floor keeps the agents' file tools away from:
- Claude's
.credentials.json,~/.ssh,gh's login and Angelia's own secrets. - Chrome's and Firefox's profiles, and the keyrings.
~/.config/systemd/user, so an agent cannot plant a unit that runs at boot.
- Claude's
- Patches.
unattended-upgradescovers the OS, and the NodeSource and Chrome repositories through the origins added in steps 4 and 6. Angelia's updates are signed (angelia update). Claude Code updates itself.
What stays open, and what to do about it
- A shell reads everything
angeliacan. The deny floor stops the file tools and a plaincat. It does not stop a script the agent writes.sandbox: truecloses that gap on macOS. On Linux it closes it only with the bwrap step from step 8, not inbypassPermissions, and it is experimental. So, on this box:- No
bypassPermissionson any profile someone else can message. UseacceptEditsordefaultthere, so a shell command asks you first. - Keep
bypassPermissionsfor a profile only you talk to. - Do not run
claude --dangerously-skip-permissionson anything that reads chat or web content. Prompt injection then has the whole account.
- No
- Make each credential worth little if it leaks. Assume an agent can read them all:
- The Claude login.
- A dedicated Google account in Chrome.
- Deploy keys where you can: each reaches one repo.
- A machine account's
ghlogin from step 4 is an OAuth token withrepo,gistandread:org, and those scopes cannot be dropped. It reaches every repo the bot can, so give the bot access only to the repos the server needs. - No cloud API keys on this box: no Hetzner token and no AWS keys. Whoever holds them can rebuild the server.
- The browser is an agent's tool. Whatever that Chrome is logged into, an agent with
--chromecan use. Log it into only what you would let the agent do alone.- The VNC socket has no password (
-SecurityTypes None). Any process of theangeliauser, an agent's script included, can open it and drive the desktop and the logged-in Chrome. - Stop the desktop when you do not need it:
systemctl --user stop desktop vnc.
- The VNC socket has no password (
- The WhatsApp session in
~/.angelia/wa/is as good as the linked device. Reading it would mean getting past the deny floor (point 1). Hetzner snapshots copy it too. - Synced files are inputs. Anything in
~/sync/incan carry a prompt injection, like any other file. Do not put it in a bypass profile'sadd_dirs. - Remote Control, if you set it up (step 9), is not an Angelia profile, so no deny floor applies to it. It puts
~/.angelia/env,wa/andapi.tokenbehind your claude.ai login. Keep 2FA on that account. - Other users' processes are visible. By default
psshowsadmin's processes too.angeliacannot touch them. To hide them, mount/procwithhidepid=invisible; that can upset polkit and logind, so test it before you rely on it.
Quick audit (run any time)
sudo ss -tulpn # on 0.0.0.0/[::] only tailscaled and sshd; ufw drops sshd's port from the internet
sudo ufw status verbose # deny incoming; allow in on tailscale0
sudo -l -U angelia; id angelia # no sudo; no extra groups
sudo stat -c '%a %n' ~angelia ~angelia/.angelia ~angelia/.angelia/env ~angelia/.claude/.credentials.json
# 700 700 600 600
sudo grep -h '^Permit\|^Password' /etc/ssh/sshd_config.d/*.conf