Angelia

Docs · docs/linux-server.md on GitHub

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

adminYour login. It has sudo and installs packages. Nothing runs as admin.
angeliaNo sudo. It runs the Angelia daemon, Claude Code, Chrome, VNC and Syncthing as systemd user units, with linger.
InboundNone from the internet. The Hetzner firewall and ufw both drop everything; Tailscale gets through without an open port.
VNC, Syncthing GUIBound 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.

  1. Project. Create a project for it (here angelia), so its firewall, keys and billing stay apart from anything else.
  2. 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.
  3. 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.
  4. Backups. Optional. A backup or snapshot holds every secret on the box (Claude login, WhatsApp session, gh token), 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 true works.
  • ssh root@<public-ip> says Permission denied (publickey).
  • sudo sshd -T | grep -E '^(permitrootlogin|passwordauthentication|x11forwarding|allowagentforwarding) ' prints no for 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-tags fails 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 tests block 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 ssh and your key, over its tailnet address. That keeps two locks, the tailnet and the key, and works for scripts. Tailscale SSH's check mode 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 ping still answers, since it is not a connection the policy governs.
  • sudo ss -tulpn shows only tailscaled and sshd on 0.0.0.0/[::]. ufw drops sshd'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 status answers.
  • loginctl show-user angelia -p Linger says Linger=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 gh in 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 gh 2.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 with gh auth refresh -h github.com -r admin:public_key and approve the code again as the bot.

Check:

  • node --version shows 24.22.1 or newer (measured: 24.22.3). Ubuntu 26.04's own nodejs is 22.22.1, too old for Angelia.
  • which node prints /usr/bin/node.
  • sudo unattended-upgrade --dry-run -d 2>&1 | grep -i 'allowed origins' includes site=deb.nodesource.com.
  • npm prefix -g prints ~/.local in full (echo ~/.local).
  • ssh -T git@github.com names the deploy key's repo, or the bot's account.
  • With a machine account: gh auth status lists scopes without admin: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.json prints 600.

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:

  1. Open Chrome.
  2. Sign in with a dedicated Google account, not your main one.
  3. Install the Claude in Chrome extension and log in.
  4. Leave this Chrome running. Sessions started with --chrome drive it.

Check:

  • ss -tlnp shows no VNC port, and ~/.vnc/vnc.sock is srw-------.
  • 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 from tag:server.
  • Homebrew on macOS: brew services start syncthing stays down until /opt/homebrew/var/log exists.
# 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:

  1. Settings → GUI. Set a user and password.
  2. Settings → Connections.
    • Listen address: tcp://<server-tailscale-ip>:22000.
    • Turn off global discovery, relaying and NAT traversal. Sync then goes only over the tailnet.
  3. 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 as tcp://<server-tailnet-ip>:22000.
  4. Share the folders.
    • ~/sync/in is Receive Only on the server: you hand files in.
    • ~/sync/out is 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 in appears on the server.
  • ss -tlnp shows 8384 only on 127.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;
  • /restart keeping tmux panes;
  • angelia update;
  • /restart with a $ in the config path;
  • a .inbox link 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.
  • /restart from a group: the chat heard "Restarting now" and then "Angelia is back up". The restarter ran as its own unit (angelia is up under systemd in daemon.out), and NRestarts=0.
  • Not yet measured: angelia update (no newer release), a $ in the config path, and the .inbox link.

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.

  1. On the Mac. Back up the instance (cp -a ~/.angelia ~/.angelia.bak-<date>), then run angelia service uninstall and angelia jobs remove <profile> for each profile with jobs. The WhatsApp link must run in one place only.

  2. 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.json stays behind: its Claude sessions live in the Mac's ~/.claude.
  3. 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_dirs repo to the same place under $HOME.
    • Run angelia check-config and angelia accept --check, which only lists the changes. Then angelia accept, and angelia compile <profile> --write for each profile. The Linux deny rules (keyrings, .config/google-chrome, .config/systemd/user) arrive only with that compile.
    • Run angelia service install.
  4. Jobs do not move. angelia jobs install is macOS only. Write systemd timers that call angelia jobs run <profile> <job>, or leave the jobs off. A run: job of a profile with sandbox: true is 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-restrict profile runs everything inside an unprivileged bwrap under unpriv_bwrap, which has audit deny capability.
  • An allow in local/unpriv_bwrap does not lift that deny. AppArmor 4's priority= can override it, but then for every program that runs under unpriv_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.bwrapPath only from managed settings (/etc/claude-code/managed-settings.json on 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.json or --settings: the denial still named unpriv_bwrap. Root owns the file, so no agent can change it.
  • Not a bwrap link in ~/.local/bin. That folder is on the service's PATH, 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. Only angelia and root can run the copy (mode 750, group angelia), so a sandboxed session of any other user, such as admin, fails.
  • The cost: that one binary may create user namespaces, as every program could before Ubuntu 24.04. Mode 750 and group angelia keep it to angelia and root.
  • Check: in a claude session as angelia, /status lists Enterprise managed settings (file) under setting sources. Then ask Claude, in a sandboxed profile, to run touch ~/sandbox-probe: it fails with Read-only file system, and sudo dmesg | grep unpriv_bwrap shows no new denial. The measurement below used a PATH link; 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:

ProbeacceptEditsbypassPermissions
Write to ~refused (Read-only file system)refused
Write in the profile folderallowedallowed
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 bypassPermissions with the sandbox on Linux. With it, the sandbox still blocks writes but not reads or network.
  • angelia check-config does not know this yet. It lets a group open to everyone (allow_from: "*") run bypassPermissions when sandbox: true, because that holds on macOS. Do not rely on it on Linux.
  • Shell commands still ask. Since Claude Code 2.1.324, sandbox.autoAllowBashIfSandboxed defaults to false, so a sandboxed command goes through the profile's permission mode like any other. Do not set it to true on a profile other people write in. Note that echo and 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, not on-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/ and api.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, never bypassPermissions.

Check:

  • systemctl --user is-active claude-rc prints active, and NRestarts=0.
  • journalctl --user -u claude-rc shows Capacity: 0/32 and a claude.ai/code?environment=… link.
  • angelia-server is 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 .gitignore written by angelia init keeps secrets out: .state/, .inbox/, logs, .env files, keys, *credentials*.json, *token*.json, auth.json and secrets/. A profile's .claude/settings.local.json is generated settings and is committed: no token lives there. The daemon gives each agent its token in the environment at launch.
  • angelia workspace sync scans before it commits. It runs the same secret scan as angelia workspace commit and leaves a secret-shaped file out, and says so. Do not replace it with a plain git add -A and git 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-sync exits without an error, and journalctl --user -u angelia-workspace-sync -n 5 shows saved 1 file, pushed or saved 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/main shows Workspace sync <date>: 1 file or Workspace sync <date>: N files.
  • systemctl --user list-timers shows 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.
    • admin has sudo but runs nothing.
    • angelia has no sudo and belongs to no privileged group. docker, lxd and adm are each as good as root, or close to it.
    • Nothing Angelia needs, service install and /restart included, asks for sudo. The one exception is linger, which you set in step 3.
  • No public port.
    • The Hetzner firewall and ufw both 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 angelia can open (with no password, so every angelia process can: see point 3 under "What stays open"), and Syncthing's GUI on localhost and its sync port on the tailnet only.
  • The server cannot reach your devices. No Tailscale grant has tag:server as its source. SSH to the server needs both your tailnet login and your key; the policy's tests block 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 077 in ~/.profile covers your login shells only: systemd user units do not read ~/.profile, so the daemon and the units keep their own umask. Angelia keeps ~/.angelia/env at 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.
  • Patches. unattended-upgrades covers 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

  1. A shell reads everything angelia can. The deny floor stops the file tools and a plain cat. It does not stop a script the agent writes. sandbox: true closes that gap on macOS. On Linux it closes it only with the bwrap step from step 8, not in bypassPermissions, and it is experimental. So, on this box:
    • No bypassPermissions on any profile someone else can message. Use acceptEdits or default there, so a shell command asks you first.
    • Keep bypassPermissions for a profile only you talk to.
    • Do not run claude --dangerously-skip-permissions on anything that reads chat or web content. Prompt injection then has the whole account.
  2. 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 gh login from step 4 is an OAuth token with repo, gist and read: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.
  3. The browser is an agent's tool. Whatever that Chrome is logged into, an agent with --chrome can use. Log it into only what you would let the agent do alone.
    • The VNC socket has no password (-SecurityTypes None). Any process of the angelia user, 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.
  4. 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.
  5. Synced files are inputs. Anything in ~/sync/in can carry a prompt injection, like any other file. Do not put it in a bypass profile's add_dirs.
  6. 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/ and api.token behind your claude.ai login. Keep 2FA on that account.
  7. Other users' processes are visible. By default ps shows admin's processes too. angelia cannot touch them. To hide them, mount /proc with hidepid=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