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

+6 -4
View File
@@ -38,21 +38,23 @@ jobs:
- name: Compress - name: Compress
working-directory: mkosi.output working-directory: mkosi.output
run: | run: |
zstd -q --rm -9 agent_*.root-*.raw zstd -q --rm -9 agent_*.usr-*.raw
qemu-img convert -c -m 16 -W -O qcow2 "$(basename agent_*.efi .efi).raw" agent.qcow2
sha256sum agent_*.efi agent_*.root-*.raw.zst > SHA256SUMS
- name: Sign - name: Sign
working-directory: mkosi.output working-directory: mkosi.output
env: env:
KEY: ${{ secrets.SIGNING_KEY }} KEY: ${{ secrets.SIGNING_KEY }}
run: | run: |
sha256sum agent_*.efi agent_*.usr-*.raw.zst > SHA256SUMS
export GNUPGHOME=$(mktemp -d) export GNUPGHOME=$(mktemp -d)
gpg -q --batch --import <<< "$KEY" gpg -q --batch --import <<< "$KEY"
gpg -q --batch -o SHA256SUMS.gpg --detach-sign SHA256SUMS gpg -q --batch -o SHA256SUMS.gpg --detach-sign SHA256SUMS
- name: Build qcow2
working-directory: mkosi.output
run: qemu-img convert -c -O qcow2 "$(basename agent_*.efi .efi).raw" agent.qcow2
- name: Publish - name: Publish
working-directory: mkosi.output working-directory: mkosi.output
run: | run: |
curl -fsS -H "$AUTH" -X DELETE "$PKG" || true curl -fsS -H "$AUTH" -X DELETE "$PKG" || true
for f in agent_*.efi agent_*.root-*.raw.zst agent.qcow2 agent_*.manifest SHA256SUMS.gpg SHA256SUMS; do for f in agent_*.efi agent_*.usr-*.raw.zst agent.qcow2 agent_*.manifest SHA256SUMS.gpg SHA256SUMS; do
curl -fsS -o /dev/null -H "$AUTH" --upload-file "$f" "$PKG/$f" curl -fsS -o /dev/null -H "$AUTH" --upload-file "$f" "$PKG/$f"
done done
-1
View File
@@ -1,3 +1,2 @@
mkosi.output/ mkosi.output/
mkosi.key mkosi.key
mkosi.pkgcache/
+9 -7
View File
@@ -7,8 +7,8 @@ every change.
- Keep it simple. Prefer fewer files, fewer lines and the defaults. Delete what - Keep it simple. Prefer fewer files, fewer lines and the defaults. Delete what
isn't needed. isn't needed.
- Divide code and config into parts (files, directories, config sections) that - Divide code and config into parts (files, directories, sections) that each
each stand on their own: reading one alone tells you what it does and why. stand on their own: reading one part alone tells you what it does and why.
- Each fact lives in one place. Elsewhere, refer to it by path instead of - Each fact lives in one place. Elsewhere, refer to it by path instead of
repeating it. repeating it.
- Write plain English in short sentences. - Write plain English in short sentences.
@@ -40,8 +40,8 @@ the file that uses them.
write clean code instead of many comments. write clean code instead of many comments.
- Put a comment right above the line or block it is about. - Put a comment right above the line or block it is about.
- Write full sentences that start with the name of what they describe: - Write full sentences that start with the name of what they describe:
`# PackageCacheDirectory keeps downloaded packages between builds.` or `# ManifestFormat lists the packages and versions in the image.` or
`# cred prints the credential agent.<name>, and fails if it isn't passed.` `# link prints the tmpfiles line for /etc/$1.`
- Wrap comments at 80 columns. - Wrap comments at 80 columns.
## Testing ## Testing
@@ -52,22 +52,24 @@ run mkosi in a privileged podman container that boots systemd:
```sh ```sh
podman build -t mkosi-vm - <<'END' podman build -t mkosi-vm - <<'END'
FROM registry.fedoraproject.org/fedora:45 FROM registry.fedoraproject.org/fedora:45
RUN dnf install -y mkosi qemu-kvm-core edk2-ovmf systemd-repart \ RUN dnf install -y mkosi qemu-kvm-core edk2-ovmf systemd-repart swtpm \
openssh-clients socat && \ openssh-clients socat && \
dnf install -y $(mkosi dependencies) dnf install -y $(mkosi dependencies)
CMD ["/sbin/init"] CMD ["/sbin/init"]
END END
podman run -d --name mkosi --privileged --systemd=always -v <repo>:/repo \ podman run -d --name mkosi --privileged --systemd=always -v <repo>:/repo \
-w /repo mkosi-vm -v mkosi-cache:/root/.cache/mkosi -w /repo mkosi-vm
podman exec mkosi mkosi genkey # once, if there is no mkosi.key podman exec mkosi mkosi genkey # once, if there is no mkosi.key
podman exec -d -t mkosi sh -c 'mkosi -f vm > mkosi.output/vm.log 2>&1' podman exec -d -t mkosi sh -c 'mkosi -f vm > mkosi.output/vm.log 2>&1'
podman exec mkosi mkosi ssh -- systemctl --failed podman exec mkosi mkosi ssh -- systemctl --failed
``` ```
podman resolves paths on the host, so `<repo>` is the repository's path there. podman resolves paths on the host, so `<repo>` is the repository's path there.
The volume `mkosi-cache` keeps mkosi's package cache when the container is
made again, so builds don't download every package anew.
`mkosi vm` needs a terminal, hence `-d -t`; its console goes to the log. `mkosi vm` needs a terminal, hence `-d -t`; its console goes to the log.
`mkosi ssh` runs a command as root, once the VM has booted. For the user `mkosi ssh` runs a command as root, once the VM has booted. For the user
`claude`, run `su - claude -c '<command>'`. `agent`, run `su - agent -c '<command>'`.
`mkosi.version` gives every run a new version, so `mkosi vm` without `-f` fails `mkosi.version` gives every run a new version, so `mkosi vm` without `-f` fails
with "has not been built yet". To boot an existing build without a rebuild, pin with "has not been built yet". To boot an existing build without a rebuild, pin
+23 -17
View File
@@ -5,24 +5,30 @@ It is a minimal Fedora image built with
[mkosi](https://github.com/systemd/mkosi). You control Claude from [mkosi](https://github.com/systemd/mkosi). You control Claude from
claude.ai/code or the Claude app (Remote Control), or log in with ssh. claude.ai/code or the Claude app (Remote Control), or log in with ssh.
- **Resets at reboot:** the homes of Claude and root, `/tmp` and all containers - **Read-only OS:** `/usr` is read-only, so Claude can't change the OS. Secure
are wiped at every boot. Only the setup answers, the ssh keys and Claude's Boot verifies the UKI (kernel, initrd and command line), which holds the
login survive (`/var/lib/agent`). dm-verity hash that verifies `/usr`.
- **Read-only OS:** the root filesystem is read-only, so Claude can't change - **Encrypted with a TPM:** everything that isn't read-only, such as `/etc`,
the OS. All state lives on `/var`. `/var` and `/home`, is encrypted. The TPM unlocks it only for those signed
- **Tools in containers:** Claude runs as the user `claude`, without root, and UKIs.
runs its toolchains in containers with podman. The host has only git, ssh and - **Tools in containers:** Claude runs as the user `agent`, without root, and
basic command-line tools. runs its toolchains in containers with podman.
- **Self-updating:** the `os` rebuilds weekly and updates with - **Self-updating:** the image rebuilds weekly. A bad update rolls back by
systemd-sysupdate. itself.
## Install ## Install
Download [the disk image](https://git.plabble.org/api/packages/Job79/generic/agent/latest/agent.qcow2), Download [the disk image](https://git.plabble.org/api/packages/Job79/generic/agent/latest/agent.qcow2),
resize it to the disk size you want and boot it with UEFI. At first boot, the resize it to the disk size you want and boot it with UEFI and a TPM. At first
console asks for a root password and a hostname. Then log in as root, add an boot, the screen offers a recovery key for the encrypted disk and asks for a
ssh key for the user `claude` and run Claude once to sign in. The VM then shows root password. Then log in as root and put your ssh key in
up in claude.ai/code and the Claude app under its hostname. `/home/agent/.ssh/authorized_keys` (for root: `~/.ssh/authorized_keys`), which
starts sshd. Run `claude` once as `agent` to sign in. The VM then shows up in
claude.ai/code and the Claude app under its hostname: `agent-` and four hex
digits.
To start over, run `systemctl start factory-reset.target` as root. It reboots
and wipes `/etc` and `/var`, and the VM sets itself up as at first boot.
## Development ## Development
@@ -32,10 +38,10 @@ mkosi build
``` ```
`mkosi.output/` then holds the disk image (`agent_<version>.raw`) and the UKI `mkosi.output/` then holds the disk image (`agent_<version>.raw`) and the UKI
and root partitions that make up an update. and /usr partitions that make up an update.
To build and boot a test VM (needs `qemu-kvm-core edk2-ovmf openssh-clients To build and boot a test VM (needs `qemu-kvm-core edk2-ovmf swtpm
socat`): openssh-clients socat`):
```sh ```sh
mkosi -f vm # opens its console: log in as root, password root mkosi -f vm # opens its console: log in as root, password root
+38 -33
View File
@@ -2,9 +2,10 @@
# #
# A Fedora VM image that runs Claude Code in the background. mkosi.extra/ is # A Fedora VM image that runs Claude Code in the background. mkosi.extra/ is
# copied to /, mkosi.repart/ defines the disk and mkosi.sandbox/ adds the # copied to /, mkosi.repart/ defines the disk and mkosi.sandbox/ adds the
# Claude Code package repository. The root filesystem, /etc included, is # Claude Code package repository. /usr is read-only and replaced whole by
# read-only and replaced whole by updates. All state lives on /var. Claude # updates. The root filesystem holds the state: /var, and an /etc that is
# can't change the OS, so it runs its tools in containers. # mostly links into /usr (mkosi.finalize). Claude can't change the OS, so it
# runs its tools in containers.
# mkosi.extra/etc/claude-code/ sets Claude Code up for that: # mkosi.extra/etc/claude-code/ sets Claude Code up for that:
# managed-settings.json lets it run without permission prompts, and CLAUDE.md # managed-settings.json lets it run without permission prompts, and CLAUDE.md
# tells it about this machine. # tells it about this machine.
@@ -22,12 +23,6 @@ SplitArtifacts=uki,partitions
# builds a CVE affects. .gitea/workflows/os.yml publishes it with the image. # builds a CVE affects. .gitea/workflows/os.yml publishes it with the image.
ManifestFormat=json ManifestFormat=json
[Build]
# PackageCacheDirectory keeps downloaded packages between builds, also when
# mkosi runs in a throwaway container (AGENTS.md). dnf still installs the
# newest versions.
PackageCacheDirectory=mkosi.pkgcache
[Content] [Content]
Bootable=yes Bootable=yes
Bootloader=systemd-boot Bootloader=systemd-boot
@@ -81,31 +76,44 @@ Locale=C.UTF-8
# it installs. # it installs.
UnifiedKernelImageFormat=%i_%v UnifiedKernelImageFormat=%i_%v
# KernelCommandLine sets: # KernelCommandLine sets:
# - console= shows the console on the screen and on the serial port. # - console= shows the console on the serial port and the screen. The last
# - systemd.machine_id=firmware takes the machine ID from the VM's firmware. # one, the screen, is /dev/console, where systemd-firstboot asks for the root
# mkosi.extra/etc/machine-id is empty, so no boot counts as the first. # password at first boot.
# - systemd.firstboot=no leaves the questions to agent-setup. # - rw mounts the root filesystem writable. The initrd finds it by its
# partition type (mkosi.extra/usr/lib/repart.d/50-root.conf).
# - systemd.hostname= names each machine agent- and four hex digits from its
# machine ID, from the initrd on. It wins over /etc/hostname, so hostnamectl
# renames only until the next boot.
# - systemd.image_policy= makes the initrd use only an encrypted root
# filesystem (or none yet, at first boot) and a verity-checked /usr.
# Otherwise someone with the disk could put in a plain root filesystem with
# their own /etc. Our UKI would boot it, and with PCR 11 unchanged, their
# code could unseal the key of the real one.
# - SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST lets systemd handle more mount # - SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST lets systemd handle more mount
# changes per second. At the default of 5, it holds back mounts at boot and # changes per second. At the default of 5, it holds back mounts at boot and
# delays / and /var by up to a second each. The kernel passes it to systemd # delays / and /usr by up to a second each. The kernel passes it to systemd
# as environment. # as environment.
KernelCommandLine= KernelCommandLine=
console=tty0
console=ttyS0,115200n8 console=ttyS0,115200n8
console=tty0
quiet quiet
systemd.machine_id=firmware rw
systemd.firstboot=no systemd.hostname=agent-????
systemd.image_policy=root=encrypted+absent:usr=verity:esp=unprotected
SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST=50 SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST=50
# KernelInitrdModules are the modules the initrd needs to find and mount the # KernelInitrdModules are the modules the initrd needs to find the disks of a
# disks of a VM. # VM, mount /usr and make, unlock and mount the root filesystem.
KernelInitrdModules= KernelInitrdModules=
virtio_blk virtio_blk
virtio_scsi virtio_scsi
sd_mod sd_mod
nvme nvme
tpm_tis
tpm_crb
dm-verity dm-verity
dm-crypt
erofs erofs
ext4 btrfs
# KernelModules keeps all modules but the hardware drivers, then the drivers a # KernelModules keeps all modules but the hardware drivers, then the drivers a
# VM needs (disks, network, screen) and those of rootless podman's networks # VM needs (disks, network, screen) and those of rootless podman's networks
# (pasta). The last matching line wins. Keyboard, USB and a basic screen are # (pasta). The last matching line wins. Keyboard, USB and a basic screen are
@@ -129,12 +137,6 @@ KernelModules=
# - System.map is only for debugging the kernel. # - System.map is only for debugging the kernel.
# - The udev hwdb holds hardware names and quirks, nothing a VM needs. # - The udev hwdb holds hardware names and quirks, nothing a VM needs.
# - homed, userdbd and nsresourced are unused services. # - homed, userdbd and nsresourced are unused services.
# - sshd-keygen would write host keys to the read-only /etc. sshd uses one host
# key on /var instead (mkosi.extra/etc/ssh/sshd_config.d).
# - /afs is the mount point for the AFS network filesystem.
# - /buildroot holds dnf's lock file, left by mkosi: it passes dnf5
# persistdir=/buildroot/var/lib/dnf and dnf5 puts the install root in front
# of it again.
RemoveFiles= RemoveFiles=
/usr/lib/modules/*/System.map /usr/lib/modules/*/System.map
/usr/lib/udev/hwdb.bin /usr/lib/udev/hwdb.bin
@@ -142,9 +144,6 @@ RemoveFiles=
/usr/lib/systemd/system/systemd-homed* /usr/lib/systemd/system/systemd-homed*
/usr/lib/systemd/system/systemd-userdbd.* /usr/lib/systemd/system/systemd-userdbd.*
/usr/lib/systemd/system/systemd-nsresourced.* /usr/lib/systemd/system/systemd-nsresourced.*
/usr/lib/systemd/system/sshd-keygen*
/afs
/buildroot
[Validation] [Validation]
# SecureBoot signs systemd-boot and the UKI, and puts our keys on the ESP. # SecureBoot signs systemd-boot and the UKI, and puts our keys on the ESP.
@@ -154,12 +153,17 @@ RemoveFiles=
SecureBoot=yes SecureBoot=yes
SecureBootKey=mkosi.key SecureBootKey=mkosi.key
SecureBootCertificate=mkosi.crt SecureBootCertificate=mkosi.crt
# SignExpectedPcr signs the PCR 11 values that each UKI will measure, with
# mkosi.key. The TPM then unlocks the root filesystem only for UKIs we signed,
# also after updates (mkosi.extra/usr/lib/repart.d/50-root.conf).
SignExpectedPcr=yes
[Runtime] [Runtime]
# Runtime sets up the test VM of mkosi vm (AGENTS.md). Ephemeral boots a copy, # Runtime sets up the test VM of mkosi vm (AGENTS.md). Ephemeral boots a copy,
# so test runs don't change the built image. Credentials answer the setup # so test runs don't change the built image. Credentials sets the root
# (mkosi.extra/usr/libexec/agent-setup). mkosi ssh logs in as root with # password, and systemd.firstboot=no skips the questions at first boot, such
# mkosi.key, which mkosi also authorizes for root in the VM. # as the offer of a recovery key. mkosi ssh logs in as root with mkosi.key,
# which mkosi also authorizes for root in the VM.
Ephemeral=yes Ephemeral=yes
CPUs=4 CPUs=4
RAM=8G RAM=8G
@@ -168,4 +172,5 @@ RuntimeSize=40G
# doesn't use hvc0: with Secure Boot, systemd-stub ignores the console= mkosi # doesn't use hvc0: with Secure Boot, systemd-stub ignores the console= mkosi
# passes. # passes.
QemuArgs=-serial chardev:console QemuArgs=-serial chardev:console
Credentials=agent.password=root agent.hostname=agent-test Credentials=passwd.plaintext-password.root=root
KernelCommandLineExtra=systemd.firstboot=no
+5 -3
View File
@@ -9,6 +9,8 @@ You run on a small Fedora VM made for you, as the user `claude`, without root.
`podman run -d --name dev -v ~:/w -w /w quay.io/fedora/fedora:45 sleep infinity`, then `podman run -d --name dev -v ~:/w -w /w quay.io/fedora/fedora:45 sleep infinity`, then
`podman exec dev dnf install -y gcc` and `podman exec dev make`. `podman exec dev dnf install -y gcc` and `podman exec dev make`.
- On the host: git, ssh, curl, tar/gzip/xz/zstd, find, diff, ps, ip. - On the host: git, ssh, curl, tar/gzip/xz/zstd, find, diff, ps, ip.
- **Everything resets at reboot**: your home (/var/home/claude), /tmp and all containers and - **Your files survive reboots**: your home (/home/claude), containers and images stay.
images. Only your Claude login survives. Keep results somewhere else (push them to git, for /tmp is wiped at every boot. The VM may reboot at about 04:10 to update.
example). The VM may reboot at about 04:10 to update. - **To start over**, push what you want to keep, then remove all containers and images with
`podman system reset --force` and delete everything in your home but `~/.claude` and
`~/.claude.json`, which hold your Claude login.
-5
View File
@@ -1,5 +0,0 @@
# Environment
#
# Claude's config, with its login, lives on /var/lib/agent instead of in the
# home, because the home is wiped at every boot.
CLAUDE_CONFIG_DIR=/var/lib/agent/claude
-11
View File
@@ -1,11 +0,0 @@
# Mounts
#
# /var is the only partition on disk that is written (mkosi.repart/30-var.conf).
# x-systemd.growfs grows its filesystem to fill the partition at boot. noatime
# skips the write that the default (relatime) makes at the first read of a file
# each day. Images that podman unpacks are full of such files; nothing here uses
# access times.
PARTLABEL=var /var ext4 noatime,x-systemd.growfs 0 2
# /root is in memory, so root has a writable home that is wiped at every boot.
# Root's ssh key lives on /var (mkosi.extra/etc/ssh/sshd_config.d).
tmpfs /root tmpfs mode=0700 0 0
View File
Whitespace-only changes.
@@ -1,22 +0,0 @@
# ssh login
#
# Login is with keys only, for root and the user claude. Neither has a key
# until root adds one (README.md). The first value wins, and this file sorts
# before Fedora's 50-redhat.conf.
# HostKey lives on /var (agent-boot makes it), so it stays the same across
# reboots.
HostKey /var/lib/agent/ssh_host_ed25519_key
PasswordAuthentication no
KbdInteractiveAuthentication no
# AuthorizedKeysFile of the user claude is owned by root, so Claude can't add
# keys.
Match User claude
AuthorizedKeysFile /var/lib/agent/authorized_keys
# AuthorizedKeysFile of root is on /var, because its home is wiped at every
# boot (/etc/fstab). It also reads the default file, which the
# ssh.authorized_keys.root credential fills, such as for mkosi ssh.
Match User root
AuthorizedKeysFile /var/lib/agent/root_authorized_keys .ssh/authorized_keys
+1 -1
View File
@@ -1 +1 @@
claude:524288:65536 agent:524288:65536
+1 -1
View File
@@ -1 +1 @@
claude:524288:65536 agent:524288:65536
+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] [Network]
DHCP=yes 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-networkd.service
enable systemd-resolved.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 # getty@.service is the login on the screen, which Fedora disables (tty1, and
# tty2-6 through its autovt@ alias). # tty2-6 through its autovt@ alias).
enable getty@.service enable getty@.service
enable agent-setup@.service tty1 ttyS0
enable etc-shadow.mount
enable agent-boot.service
enable claude-remote.path enable claude-remote.path
enable systemd-sysupdate-update.timer enable systemd-sysupdate-update.timer
enable systemd-sysupdate-reboot.timer enable systemd-sysupdate-reboot.timer
# These services do nothing here, but Fedora enables them: no PAM or crypto # authselect-apply-changes would rewrite /etc/authselect, which links into the
# changes on a read-only /etc, and no system or config extensions. # read-only /usr (mkosi.finalize), and fails.
disable authselect-apply-changes.service 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 Description=Start Claude Remote Control once logged in
[Path] [Path]
PathExists=/var/lib/agent/claude/.credentials.json PathExists=/home/agent/.claude/.credentials.json
[Install] [Install]
WantedBy=multi-user.target WantedBy=multi-user.target
@@ -1,17 +1,16 @@
# Claude Remote Control # Claude Remote Control
# #
# Runs Claude Code in the background, in Claude's home, so it can be used from # Runs Claude Code in the background, as the user agent in its home, so it can
# claude.ai/code or the Claude app. claude-remote.path starts it once Claude is # be used from claude.ai/code or the Claude app. claude-remote.path starts it
# logged in. # once Claude is logged in.
[Unit] [Unit]
Description=Claude Code Remote Control Description=Claude Code Remote Control
Wants=network-online.target user@1000.service 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] [Service]
User=claude User=agent
WorkingDirectory=~ WorkingDirectory=~
EnvironmentFile=/etc/environment
Environment=XDG_RUNTIME_DIR=/run/user/1000 Environment=XDG_RUNTIME_DIR=/run/user/1000
ExecStart=/usr/bin/claude remote-control --name %H ExecStart=/usr/bin/claude remote-control --name %H
Restart=always 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 # Verify=yes: SHA256SUMS.gpg must be signed by a key in
# /usr/lib/systemd/import-pubring.pgp, and SHA256SUMS checks each download. # /usr/lib/systemd/import-pubring.pgp, and SHA256SUMS checks each download.
# The files come from .gitea/workflows/os.yml. # The files come from .gitea/workflows/os.yml.
@@ -11,12 +11,12 @@ Verify=yes
[Source] [Source]
Type=url-file Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/ 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] [Target]
Type=partition Type=partition
Path=auto Path=auto
MatchPattern=agent_@v MatchPattern=agent_@v
MatchPartitionType=root MatchPartitionType=usr
PartitionFlags=0 PartitionFlags=0
ReadOnly=1 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. # Verify=yes.
[Transfer] [Transfer]
ProtectVersion=%A ProtectVersion=%A
@@ -9,12 +9,12 @@ Verify=yes
[Source] [Source]
Type=url-file Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/ 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] [Target]
Type=partition Type=partition
Path=auto Path=auto
MatchPattern=agent_@v_verity MatchPattern=agent_@v_verity
MatchPartitionType=root-verity MatchPartitionType=usr-verity
PartitionFlags=0 PartitionFlags=0
ReadOnly=1 ReadOnly=1
@@ -1,12 +1,12 @@
# UKI update # UKI update
# #
# Installs the next UKI, which systemd-boot then boots by default. For # 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). # 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. # 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 # 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. # Mode=0444: systemd-boot can't rename a read-only file.
[Transfer] [Transfer]
ProtectVersion=%A 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 # The user Claude runs as. /etc/subuid and /etc/subgid give it the ids that
# rootless podman needs. # 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 # The home of the user agent (mkosi.extra/usr/lib/sysusers.d/agent.conf), with
# directories, /tmp and its own config. # Claude's login and podman storage.
d /home/agent 0700 agent agent -
# /var/lib/agent keeps the setup answers, the ssh keys and Claude's login. # linger starts the user manager of agent at boot, for rootless podman and
# agent-boot wipes the rest of Claude's config. # Claude's own services.
d /var/lib/agent 0755 root root - f /var/lib/systemd/linger/agent
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
-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"
Executable
+42
View File
@@ -0,0 +1,42 @@
#!/bin/sh
# Factory /etc
#
# The image ships only /usr (mkosi.repart), so this keeps the /etc that the
# packages and mkosi.extra/etc made in /usr/share/factory/etc. It writes
# /usr/lib/tmpfiles.d/factory-etc.conf, with which systemd-tmpfiles links each
# entry into the writable, empty /etc at boot. Updates to /usr then take
# effect in /etc too. /etc itself holds only what the machine writes: passwd,
# shadow, group, hostname, machine-id and the ssh host keys.
set -eu
factory=$BUILDROOT/usr/share/factory/etc
cp -a --no-target-directory --update=none "$BUILDROOT/etc" "$factory"
# skip holds what /etc keeps for itself, and what other tmpfiles.d files
# already set up, such as /etc/os-release.
skip=$(printf '%s\n' passwd group shadow gshadow hostname machine-id ssh
sed -n 's|^[^#][^ ]* */etc/\([^/ ]*\).*|\1|p' "$BUILDROOT"/usr/lib/tmpfiles.d/*.conf)
# link prints the tmpfiles line for /etc/$1. Some entries are copied instead:
# a symlink, because a relative one would point somewhere else from the
# factory, and subuid and subgid, because shadow-utils won't read them through
# a link.
link() {
case "$1" in
subuid|subgid) echo "C /etc/$1" ;;
*) if [ -L "$factory/$1" ]; then echo "C /etc/$1"; else echo "L /etc/$1"; fi ;;
esac
}
{
echo "# Generated by mkosi.finalize."
for f in $(ls -A "$factory"); do
case "$f" in *-|.*) continue ;; esac
echo "$skip" | grep -qxF "$f" || link "$f"
done
# /etc/ssh is a directory of its own, because sshd-keygen writes the host
# keys there.
echo "d /etc/ssh 0755"
for f in $(ls -A "$factory/ssh"); do link "ssh/$f"; done
} > "$BUILDROOT/usr/lib/tmpfiles.d/factory-etc.conf"
-19
View File
@@ -1,19 +0,0 @@
# Root filesystem, slot A
#
# /etc and /usr as read-only erofs, protected by dm-verity (roothash= in the
# UKI). Updates replace it whole. /var holds the state, on its own partition
# (30-var.conf).
[Partition]
Type=root
Label=%M_%A
Format=erofs
Compression=lz4hc
CopyFiles=/
ExcludeFilesTarget=/var/
Verity=data
VerityMatchKey=root
SizeMinBytes=1G
SizeMaxBytes=1G
# SplitName holds the partition UUID (%U): roothash= finds the root by it, and
# updates keep it (@u in mkosi.extra/usr/lib/sysupdate.d).
SplitName=%t.%U
+19
View File
@@ -0,0 +1,19 @@
# /usr, slot A
#
# The OS as read-only erofs, protected by dm-verity (usrhash= in the UKI).
# Updates replace it whole. The image holds nothing else but the ESP: the
# initrd makes the root filesystem, with /etc and /var, at first boot
# (mkosi.extra/usr/lib/repart.d/50-root.conf).
[Partition]
Type=usr
Label=%M_%A
Format=erofs
Compression=lz4hc
CopyFiles=/usr:/
Verity=data
VerityMatchKey=usr
SizeMinBytes=1G
SizeMaxBytes=1G
# SplitName holds the partition UUID (%U): usrhash= finds /usr by it, and
# updates keep it (@u in mkosi.extra/usr/lib/sysupdate.d).
SplitName=%t.%U
-11
View File
@@ -1,11 +0,0 @@
# Root verity, slot A
#
# The dm-verity hashes of the root filesystem in 10-root.conf.
[Partition]
Type=root-verity
Label=%M_%A_verity
Verity=hash
VerityMatchKey=root
SizeMinBytes=64M
SizeMaxBytes=64M
SplitName=%t.%U
+11
View File
@@ -0,0 +1,11 @@
# /usr verity, slot A
#
# The dm-verity hashes of /usr in 10-usr.conf.
[Partition]
Type=usr-verity
Label=%M_%A_verity
Verity=hash
VerityMatchKey=usr
SizeMinBytes=64M
SizeMaxBytes=64M
SplitName=%t.%U
@@ -1,8 +1,8 @@
# Root filesystem, slot B # /usr, slot B
# #
# Empty until systemd-sysupdate writes the next version to it. # Empty until systemd-sysupdate writes the next version to it.
[Partition] [Partition]
Type=root Type=usr
Label=_empty Label=_empty
SizeMinBytes=1G SizeMinBytes=1G
SizeMaxBytes=1G SizeMaxBytes=1G
-9
View File
@@ -1,9 +0,0 @@
# Root verity, slot B
#
# The dm-verity hashes for 20-root-b.conf, empty until the next update.
[Partition]
Type=root-verity
Label=_empty
SizeMinBytes=64M
SizeMaxBytes=64M
SplitName=-
+9
View File
@@ -0,0 +1,9 @@
# /usr verity, slot B
#
# The dm-verity hashes for 20-usr-b.conf, empty until the next update.
[Partition]
Type=usr-verity
Label=_empty
SizeMinBytes=64M
SizeMaxBytes=64M
SplitName=-
-13
View File
@@ -1,13 +0,0 @@
# State partition
#
# /var: everything reboots and updates keep, such as the setup answers, the
# root password and Claude's login (/var/lib/agent). /etc/fstab mounts it and
# grows it to fill the disk at boot. Claude's home is on it too, but is wiped
# at every boot (mkosi.extra/usr/lib/tmpfiles.d/agent.conf).
[Partition]
Type=var
Label=var
Format=ext4
CopyFiles=/var:/
Minimize=guess
SplitName=-