feat: ParticleOS-like layout: /usr image, encrypted btrfs root

The image now holds only the ESP and a verity-protected /usr (A/B). At
first boot, systemd-repart in the initrd makes the root filesystem: btrfs,
encrypted with a TPM key sealed to the signed PCR 11 policy, with /var as
its own subvolume. A TPM is required. systemd.image_policy= accepts only
an encrypted root and a verity-checked /usr, and FactoryReset=yes lets
factory-reset.target wipe it.

/etc is writable but nearly empty: mkosi.finalize keeps the build's /etc
in /usr/share/factory/etc and systemd-tmpfiles links it in at boot. That
removes etc-shadow.mount, the host key on /var, fstab and /var/lib/agent.
/var now survives reboots.

systemd-firstboot replaces agent-setup: it asks for the root password on
the screen and offers a recovery key. Machines are named agent-???? from
the kernel command line. The user is now agent, with its home in
/home/agent and ssh keys in the default places. sshd.path starts sshd
only once root or agent has a key.

The test VM needs swtpm. The package cache moves to a podman volume
(AGENTS.md). No existing VMs can update to this layout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Job79andClaude Opus 5.5 committed 2026-11-19 21:09:31 +01:00
1 parent db8fb0d5a4
commit c80e843cb5
39 files changed
+229 -342

No files matched your search

+18
View File
@@ -0,0 +1,18 @@
# Root filesystem
#
# systemd-repart makes it in the initrd at first boot, from the free space
# after /usr, and grows it when the disk grows. It holds all state: /etc
# (mkosi.finalize) and /var, which is its own btrfs subvolume. It is encrypted
# with a key in the TPM, so a TPM is required. The key is sealed to the signed
# PCR 11 policy of our UKIs (SignExpectedPcr= in mkosi.conf), and the initrd
# unlocks it at every boot.
#
# FactoryReset makes a factory reset wipe it: root runs systemctl start
# factory-reset.target, and at the next boot it is made anew, as at first boot.
[Partition]
Type=root
Format=btrfs
Subvolumes=/var
MakeDirectories=/var
Encrypt=tpm2
FactoryReset=yes
-6
View File
@@ -1,6 +0,0 @@
# Grow /var
#
# systemd-repart grows the /var partition to fill the disk at boot.
# x-systemd.growfs in /etc/fstab then grows its filesystem.
[Partition]
Type=var
@@ -8,8 +8,3 @@ Kind=!*
[Network]
DHCP=yes
[DHCPv4]
# UseHostname=no keeps the hostname asked at setup (agent-boot) instead of the
# DHCP server's.
UseHostname=no
@@ -5,19 +5,16 @@
enable systemd-networkd.service
enable systemd-resolved.service
enable sshd.service
# sshd.path starts sshd once there is an ssh key, so Fedora's preset of
# sshd.service is overruled.
enable sshd.path
disable sshd.service
# getty@.service is the login on the screen, which Fedora disables (tty1, and
# tty2-6 through its autovt@ alias).
enable getty@.service
enable agent-setup@.service tty1 ttyS0
enable etc-shadow.mount
enable agent-boot.service
enable claude-remote.path
enable systemd-sysupdate-update.timer
enable systemd-sysupdate-reboot.timer
# These services do nothing here, but Fedora enables them: no PAM or crypto
# changes on a read-only /etc, and no system or config extensions.
# authselect-apply-changes would rewrite /etc/authselect, which links into the
# read-only /usr (mkosi.finalize), and fails.
disable authselect-apply-changes.service
disable fips-crypto-policy-overlay.service
disable systemd-sysext.service
disable systemd-confext.service
@@ -1,17 +0,0 @@
# Apply setup
#
# Runs /usr/libexec/agent-boot at every boot. Before the setup is done there
# is nothing to apply, so agent-setup starts this once it is.
[Unit]
Description=Apply agent setup
ConditionPathExists=/var/lib/agent/hostname
After=systemd-tmpfiles-setup.service
Before=sshd.service claude-remote.service
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/libexec/agent-boot
[Install]
WantedBy=multi-user.target
@@ -1,25 +0,0 @@
# First-boot setup
#
# Runs /usr/libexec/agent-setup on the screen (tty1) and the serial console
# (ttyS0) at once, so it can be answered on either. Whichever is answered first
# stops the other.
[Unit]
Description=Agent first-boot setup on %I
ConditionPathExists=!/var/lib/agent/hostname
After=systemd-tmpfiles-setup.service
Before=getty@%i.service serial-getty@%i.service
[Service]
Type=oneshot
ImportCredential=agent.*
ExecStart=/usr/libexec/agent-setup
StandardInput=tty
StandardOutput=tty
TTYPath=/dev/%I
TTYReset=yes
TTYVHangup=yes
# SuccessExitStatus counts being stopped by the other console as success.
SuccessExitStatus=SIGTERM
[Install]
WantedBy=multi-user.target
@@ -6,7 +6,7 @@
Description=Start Claude Remote Control once logged in
[Path]
PathExists=/var/lib/agent/claude/.credentials.json
PathExists=/home/agent/.claude/.credentials.json
[Install]
WantedBy=multi-user.target
@@ -1,17 +1,16 @@
# Claude Remote Control
#
# Runs Claude Code in the background, in Claude's home, so it can be used from
# claude.ai/code or the Claude app. claude-remote.path starts it once Claude is
# logged in.
# Runs Claude Code in the background, as the user agent in its home, so it can
# be used from claude.ai/code or the Claude app. claude-remote.path starts it
# once Claude is logged in.
[Unit]
Description=Claude Code Remote Control
Wants=network-online.target user@1000.service
After=network-online.target user@1000.service agent-boot.service
After=network-online.target user@1000.service
[Service]
User=claude
User=agent
WorkingDirectory=~
EnvironmentFile=/etc/environment
Environment=XDG_RUNTIME_DIR=/run/user/1000
ExecStart=/usr/bin/claude remote-control --name %H
Restart=always
@@ -1,16 +0,0 @@
# Root password
#
# /etc is read-only, so agent-setup writes the shadow file to /var and this
# mounts it over /etc/shadow.
[Unit]
Description=Root password from /var
ConditionPathExists=/var/lib/agent/etc/shadow
RequiresMountsFor=/var
[Mount]
What=/var/lib/agent/etc/shadow
Where=/etc/shadow
Options=bind
[Install]
WantedBy=local-fs.target
@@ -0,0 +1,14 @@
# Start sshd once there is a key
#
# sshd starts only once root or the user agent has an ssh key, so a new VM
# has no open port. Root adds the keys after the first boot (README.md). The
# ssh.authorized_keys.root credential also fills root's, such as for mkosi ssh.
[Unit]
Description=Start sshd once an ssh key is set
[Path]
PathExists=/home/agent/.ssh/authorized_keys
PathExists=/root/.ssh/authorized_keys
[Install]
WantedBy=multi-user.target
@@ -1,7 +0,0 @@
# sshd after setup
#
# sshd needs the host key, which agent-boot makes once the setup is done.
# agent-setup then starts sshd.
[Unit]
After=agent-boot.service
ConditionPathExists=/var/lib/agent/ssh_host_ed25519_key
@@ -1,6 +1,6 @@
# Root update
# /usr update
#
# Writes the next version of the root filesystem to the unused root partition.
# Writes the next version of /usr to the unused /usr partition.
# Verify=yes: SHA256SUMS.gpg must be signed by a key in
# /usr/lib/systemd/import-pubring.pgp, and SHA256SUMS checks each download.
# The files come from .gitea/workflows/os.yml.
@@ -11,12 +11,12 @@ Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.root-%a.@u.raw.zst
MatchPattern=agent_@v.usr-%a.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agent_@v
MatchPartitionType=root
MatchPartitionType=usr
PartitionFlags=0
ReadOnly=1
@@ -1,6 +1,6 @@
# Root verity update
# /usr verity update
#
# Writes the dm-verity hashes that go with 10-root.transfer, which explains
# Writes the dm-verity hashes that go with 10-usr.transfer, which explains
# Verify=yes.
[Transfer]
ProtectVersion=%A
@@ -9,12 +9,12 @@ Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.root-%a-verity.@u.raw.zst
MatchPattern=agent_@v.usr-%a-verity.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agent_@v_verity
MatchPartitionType=root-verity
MatchPartitionType=usr-verity
PartitionFlags=0
ReadOnly=1
@@ -1,12 +1,12 @@
# UKI update
#
# Installs the next UKI, which systemd-boot then boots by default. For
# Verify=yes, see 10-root.transfer.
# Verify=yes, see 10-usr.transfer.
#
# The new UKI gets three tries (boot counting: the +@l-@d in its name).
# systemd-bless-boot marks it good once a boot reaches boot-complete.target.
# If no boot does, systemd-boot goes back to the previous UKI, and with it to
# the previous root partition, because each UKI holds its root hash. No
# the previous /usr partition, because each UKI holds its usr hash. No
# Mode=0444: systemd-boot can't rename a read-only file.
[Transfer]
ProtectVersion=%A
@@ -1,5 +1,5 @@
# Claude user
# Agent user
#
# The user Claude runs as. /etc/subuid and /etc/subgid give it the ids that
# rootless podman needs.
u claude 1000 "Claude" /var/home/claude /bin/bash
u agent 1000 "Agent" /home/agent /bin/bash
+7 -15
View File
@@ -1,16 +1,8 @@
# Agent directories
# Agent home
#
# What survives a reboot and what doesn't. Claude can only write to the wiped
# directories, /tmp and its own config.
# /var/lib/agent keeps the setup answers, the ssh keys and Claude's login.
# agent-boot wipes the rest of Claude's config.
d /var/lib/agent 0755 root root -
d /var/lib/agent/claude 0700 claude claude -
# D wipes Claude's home, with its podman storage, and temporary files at every
# boot.
D /var/home/claude 0700 claude claude -
D /var/tmp 1777 root root -
# linger starts Claude's user manager at boot, for rootless podman and its own
# services.
f /var/lib/systemd/linger/claude
# The home of the user agent (mkosi.extra/usr/lib/sysusers.d/agent.conf), with
# Claude's login and podman storage.
d /home/agent 0700 agent agent -
# linger starts the user manager of agent at boot, for rootless podman and
# Claude's own services.
f /var/lib/systemd/linger/agent
-12
View File
@@ -1,12 +0,0 @@
#!/bin/bash
# Apply setup
#
# Runs at every boot (agent-boot.service) and right after the setup. /etc is
# read-only, so the hostname asked at setup is set again on every boot. Makes
# the ssh host key the first time. Wipes Claude's config except its login, so
# Claude starts fresh but logged in.
set -euo pipefail
cd /var/lib/agent
hostnamectl hostname --transient "$(cat hostname)"
[[ -f ssh_host_ed25519_key ]] || ssh-keygen -q -t ed25519 -N '' -f ssh_host_ed25519_key
find claude -mindepth 1 -maxdepth 1 ! -name .credentials.json ! -name .claude.json -exec rm -rf {} +
-52
View File
@@ -1,52 +0,0 @@
#!/bin/bash
# First-boot setup
#
# Asks for the root password and the hostname (agent-setup@.service). /etc is
# read-only, so the answers go to /var/lib/agent. The password goes into a
# shadow file there, which etc-shadow.mount puts over /etc/shadow. agent-boot
# applies the rest at every boot. Root adds the ssh keys afterwards
# (README.md).
#
# With the credential agent.password, it asks nothing and takes the answers
# from the credentials agent.password and agent.hostname. mkosi vm passes them
# (mkosi.conf).
set -euo pipefail
# cred prints the credential agent.<name>, and fails if it isn't passed.
cred() { cat "${CREDENTIALS_DIRECTORY:-/nonexistent}/agent.$1" 2>/dev/null; }
if pw=$(cred password); then
# flock lets only one of the two consoles do the setup.
exec 9>/run/agent-setup.lock
flock -n 9 || exit 0
name=$(cred hostname) || true
else
echo "== Agent setup =="
while :; do
read -rsp "Root password: " pw; echo
read -rsp "Again: " pw2; echo
[[ -n $pw && $pw == "$pw2" ]] && break
echo "Passwords do not match, try again."
done
read -rp "Hostname [agent]: " name
fi
install -d -m 0700 /var/lib/agent/etc
# etc-shadow.mount is stopped first: an interrupted setup may have started it,
# and then cp would copy the shadow file onto itself.
systemctl stop etc-shadow.mount
cp /etc/passwd /etc/shadow /var/lib/agent/etc/
echo "root:$pw" | chpasswd --prefix /var/lib/agent
systemctl start etc-shadow.mount
# hostname is written last: its presence marks the setup as done.
echo "${name:-agent}" > /var/lib/agent/hostname
systemctl start agent-boot.service sshd.service
cat <<'EOF'
Done. Log in as root and add your ssh key for the user claude to
/var/lib/agent/authorized_keys (for root: root_authorized_keys there). Then
log in with ssh claude@<this VM>, run claude and log in with your account.
Remote Control then starts by itself.
EOF
# systemctl stop ends the setup on the other console, which then shows its
# login.
systemctl --no-block stop "agent-setup@*.service"