Compare commits

..
Author SHA1 Message Date
Job79andClaude Opus 5.5 ce1faca070 feat: unattended setup from credentials, rewrite README
agent-setup takes its answers from the credentials agent.password,
agent.hostname and agent.ssh-key when they are given, so a test VM boots
without typing. The README is shorter, explains the mkosi layout and
shows how to boot a test VM with these credentials. Also uploads the
manifest in the os workflow and ignores the test VM files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 21:02:29 +01:00
Job79 3ae080f978 chore: simplify comments in os.yml 2026-11-16 20:17:24 +01:00
Job79andClaude Opus 5.5 a1fc65ed21 style: apply STYLE.md to all files
Give every file a header (title, empty line, explanation), wrap comments
at 80 columns and keep them to the why. Only comments change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 20:14:06 +01:00
Job79 efb282bf7d Merge pull request 'docs: explain pipeline values, link style guide' (#1) from pipeline-comments into main
Reviewed-on: #1
2026-11-16 19:09:28 +00:00
33 changed files with 224 additions and 146 deletions

No files matched your search

+6 -21
View File
@@ -1,30 +1,15 @@
# agent OS image
# OS image
#
# Builds the OS image and publishes it as version "latest". VMs fetch the build
# images as updates (mkosi.extra/usr/lib/sysupdate.d). Runs on every push,
# weekly for package updates, and by hand for critical CVE's.
# Builds the OS image and publishes it as version "latest". VMs fetch the
# built images as updates (mkosi.extra/usr/lib/sysupdate.d). Runs on every
# push, weekly for package updates, and by hand for critical CVEs.
#
# Values used below:
# - PKG upload location, <server>/api/packages/<owner>/generic/
# agent/latest. Path= in mkosi.extra/usr/lib/sysupdate.d/
# *.transfer points at the same place.
# - AUTH the job's automatic token (gitea.token), which can write
# the owner's packages.
# Required values:
# - SECUREBOOT_KEY repository secret: the private key of mkosi.crt, written
# to mkosi.key.
# - SIGNING_KEY repository secret: the armored private gpg key whose
# public half is mkosi.extra/usr/lib/systemd/
# import-pubring.pgp, which systemd-sysupdate checks.
# - zstd -19 -T0 the root and verity partitions have a fixed size (1 GiB,
# 64 MiB) and are mostly zero padding: zstd shrinks them
# from ~1.1 GB to ~245 MB. -19 is ~11% smaller than the
# default -3, for ~35 s more build time. -T0 uses all
# cores; --rm deletes the .raw files. systemd-sysupdate
# decompresses .raw.zst as it downloads.
# - qemu-img -c agent.qcow2, the whole disk compressed, for creating new
# VMs (not for updates).
# - SHA256SUMS checksums of the update files, signed as SHA256SUMS.gpg
# (Verify=yes in sysupdate.d).
name: os
on:
push:
@@ -68,6 +53,6 @@ jobs:
working-directory: mkosi.output
run: |
curl -fsS -H "$AUTH" -X DELETE "$PKG" || true
for f in agent_*.efi agent_*.root-*.raw.zst agent.qcow2 SHA256SUMS.gpg SHA256SUMS; do
for f in agent_*.efi agent_*.root-*.raw.zst agent.qcow2 agent_*.manifest SHA256SUMS.gpg SHA256SUMS; do
curl -fsS -o /dev/null -H "$AUTH" --upload-file "$f" "$PKG/$f"
done
+2
View File
@@ -1,2 +1,4 @@
mkosi.output/
mkosi.key
test.qcow2
vars.fd
+17 -17
View File
@@ -1,42 +1,42 @@
# agent-mkosi
A VM that runs [Claude Code](https://claude.com/claude-code) in the background, packaged as a minimal Fedora image built with [mkosi](https://github.com/systemd/mkosi). You control Claude from claude.ai/code, the Claude app (Remote Control), or log in with ssh.
A VM that runs [Claude Code](https://claude.com/claude-code) in the background. It is a minimal Fedora image built with [mkosi](https://github.com/systemd/mkosi). You control Claude from claude.ai/code or the Claude app (Remote Control), or log in with ssh.
- **Resets at reboot:** the OS is read-only, so Claude can't change it, and Claude's home, `/tmp` and all containers are wiped at every boot. Only the setup answers and Claude's login survive (`/var/lib/agent`).
- **Claude as non-root, tools in containers:** Claude runs as the user `claude`, without root, and runs its toolchains in containers with rootless podman (also as `docker`). `/etc/claude-code/CLAUDE.md` tells it about the machine; `/etc/claude-code/managed-settings.json` lets it run without asking permission. The host has only git, ssh and basic command-line tools.
- **Self-updating:** like [git-runner-mkosi](../git-runner-mkosi): images are rebuilt weekly (also picking up the latest Claude Code) and on every push. Hosts download updates with systemd-sysupdate, check their signature (`SIGNING_KEY` secret), write them into a second root partition (A/B) and reboot into them daily at about 04:10. That reboot also resets Claude's work. A new version gets three tries to boot; if none gets through, systemd-boot goes back to the previous one.
- **Read-only system:** systemd-boot starts a UKI that mounts the root filesystem, /etc and /usr included, from a read-only erofs partition checked by dm-verity. All state (Claude's home, its login, the root password, logs) lives on `/var`, its own partition.
- **Secure Boot:** systemd-boot and the UKIs are signed with our own key (`mkosi.crt`; the private key is the `SECUREBOOT_KEY` secret). systemd-boot enrolls it at first boot if the VM's firmware has no keys yet; the firmware then boots nothing else.
- **Resets at reboot:** Claude's home, `/tmp` and all containers are wiped at every boot. Only the setup answers and Claude's login survive (`/var/lib/agent`).
- **Read-only OS:** the root filesystem is read-only, so Claude can't change the OS. All state lives on `/var`.
- **Tools in containers:** Claude runs as the user `claude`, without root, and runs its toolchains in containers with podman. The host has only git, ssh and basic command-line tools.
- **Self-updating:** the `os` rebuilds weekly and updates with systemd-sysupdate.
## Install
Download [the disk image](https://git.plabble.org/api/packages/Job79/generic/agent/latest/agent.qcow2) (built by the `os` workflow), resize it to the disk size you want (/var grows to fill it) and boot it with UEFI in Secure Boot setup mode (no keys enrolled; in Proxmox, an EFI disk with "Pre-Enroll keys" unchecked), so it enrolls our key. The screen and the serial console ask for a root password, a hostname and an ssh public key for the user `claude`.
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 in Secure Boot setup mode. The console asks for a root password, a hostname and an ssh public key for the user `claude`.
Then log Claude in once:
```sh
ssh claude@<vm>
claude # trust the folder (your home), then /login with your Claude account
claude # trust the folder, then /login with your Claude account
```
As soon as Claude is logged in, `claude-remote.service` starts `claude remote-control` in Claude's home, and the VM shows up in claude.ai/code and the Claude app under its hostname. Over ssh you can also run `claude` yourself. Logs: `journalctl -u claude-remote`.
The VM then shows up in claude.ai/code and the Claude app under its hostname.
## Development
`mkosi.conf` defines the OS (`mkosi.extra/` is copied to `/`, `mkosi.repart/` is the disk layout, `mkosi.sandbox/` adds the Claude Code package repository). When changing files, follow [STYLE.md](STYLE.md).
```sh
mkosi genkey # local test only, CI uses the SECUREBOOT_KEY secret
mkosi build
```
The build signs with `mkosi.key`: the `SECUREBOOT_KEY` secret, or for a local test a key of your own (`mkosi genkey` writes `mkosi.key` and `mkosi.crt`; don't commit them).
`mkosi.output/` then holds the disk image (`agent_<version>.raw`), and the UKI and root partitions that the `os` workflow publishes as an update. To boot the disk image with Secure Boot (needs `qemu-kvm-core edk2-ovmf`; `OVMF_VARS.fd` has no keys, so it enrolls ours; ssh on port 2222):
`mkosi.output/` then holds the disk image (`agent_<version>.raw`) and the UKI and root partitions that make up an update. To boot it with Secure Boot (needs `qemu-kvm-core edk2-ovmf`):
```sh
qemu-img convert -O qcow2 mkosi.output/agent_<version>.raw test.qcow2 && qemu-img resize test.qcow2 40G
qemu-img create -f qcow2 -F raw -b $PWD/mkosi.output/agent_<version>.raw test.qcow2 40G
cp /usr/share/edk2/ovmf/OVMF_VARS.fd vars.fd
qemu-kvm -m 8G -smp 4 -cpu host -nic user,model=virtio-net-pci,hostfwd=tcp::2222-:22 -drive file=test.qcow2,if=virtio -device virtio-balloon-pci,free-page-reporting=on \
qemu-kvm -m 8G -cpu host -nographic -nic user,model=virtio-net-pci,hostfwd=tcp::2222-:22 -drive file=test.qcow2,if=virtio \
-machine q35,smm=on -global driver=cfi.pflash01,property=secure,value=on \
-drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE.secboot.fd -drive if=pflash,format=raw,file=vars.fd
-drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE.secboot.fd -drive if=pflash,format=raw,file=vars.fd \
-smbios type=11,value=io.systemd.credential:agent.password=test \
-smbios type=11,value=io.systemd.credential.binary:agent.ssh-key=$(base64 -w0 ~/.ssh/id_ed25519.pub)
```
The credentials answer the setup, so it boots straight to a login (root, password `test`) on the serial console. Ctrl-a x quits. Then `ssh -p 2222 claude@localhost`.
+3 -16
View File
@@ -1,9 +1,5 @@
# Style guide
For everyone who changes this repository, people and AI agents alike.
## General
- Keep it simple. Prefer fewer files, fewer lines and the defaults. Delete what isn't needed.
- Each fact lives in one place. Elsewhere, refer to it by path instead of repeating it.
- Write plain English in short sentences.
@@ -16,7 +12,8 @@ Every file that allows comments starts with a header. It goes after the shebang,
#!/bin/sh
# Image version
#
# The build time (UTC), so every build is newer than the last.
# Prints the build time in UTC (YYYYMMDDhhmm). Every build gets a higher version than the one
# before, which is how systemd-sysupdate tells that an update is newer.
```
- Line 1 is a title: a few words, in sentence case, with no full stop.
@@ -30,14 +27,4 @@ them or in the README.
- Explain why, not what. Leave out comments that only repeat the code.
- Put a comment right above the line or block it is about.
- Wrap comments at 100 columns.
## Shell
- Use `#!/bin/sh` with `set -eu`. Switch to `#!/bin/bash` with `set -euo pipefail` only when the
script needs bash.
- Quote variables: `"$var"`.
## Config files
- Put one value per line in lists, with a comment explaining the less obvious entries.
- Wrap comments at 80 columns.
+39 -28
View File
@@ -1,7 +1,10 @@
# agent: a Fedora VM image that runs Claude Code in the background, built with mkosi.
# mkosi.extra/ is copied to /, mkosi.repart/ defines the disk, mkosi.sandbox/ adds the Claude Code repo.
# The root filesystem, /etc included, is read-only and replaced whole by updates; all state lives
# on /var. Claude can't change the OS: it runs its tools in containers.
# Agent image
#
# 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
# Claude Code package repository. The root filesystem, /etc included, is
# read-only and replaced whole by updates. All state lives on /var. Claude
# can't change the OS, so it runs its tools in containers.
[Distribution]
Distribution=fedora
@@ -11,24 +14,25 @@ Release=45
Format=disk
ImageId=agent
OutputDirectory=mkosi.output
# The UKI and root partitions are published as updates (systemd-sysupdate).
SplitArtifacts=uki,partitions
# Lists the packages and versions in the image, to tell which builds a CVE
# affects. .gitea/workflows/os.yml publishes it with the image.
ManifestFormat=json
[Content]
Bootable=yes
Bootloader=systemd-boot
# - kernel-core no drivers or firmware beyond what VMs need
# - systemd-container, gnupg2 systemd-pull, which systemd-sysupdate downloads with, and gpg,
# which it checks their signature with
# - systemd-boot-unsigned the bootloader
# - systemd-container systemd-pull, which systemd-sysupdate downloads by
# - gnupg2 checks the signature of updates
# - util-linux, shadow-utils console login, setup, newuidmap for rootless podman
# - systemd-pam login sessions (pam_systemd): Claude's user manager and its
# - systemd-pam login sessions: Claude's user manager and its
# D-Bus, which rootless podman needs
# - openssh-server ssh login for the user (keys only)
# - zram-generator-defaults compressed swap in RAM
# - podman, podman-docker containers, for all of Claude's toolchains (also as docker)
# - claude-code Claude Code (mkosi.sandbox/etc/yum.repos.d)
# - git-core, openssh-clients Claude Code uses git; it pushes over ssh
# - podman, podman-docker containers for Claude's toolchains (also as docker)
# - claude-code from mkosi.sandbox/etc/yum.repos.d
# - git-core, openssh-clients Claude Code uses git and pushes over ssh
# - the rest basic command-line tools Claude uses on the host
Packages=
kernel-core
@@ -61,13 +65,17 @@ Packages=
iproute
WithDocs=no
Locale=C.UTF-8
# The UKI's file name in the ESP, as systemd-sysupdate names the ones it installs.
# Name UKIs the way systemd-sysupdate names the ones it installs.
UnifiedKernelImageFormat=%i_%v
# The console on screen and serial port, the machine ID from the VM's firmware
# (mkosi.extra/etc/machine-id is empty, so no boot counts as the first), no systemd-firstboot
# questions (agent-setup asks its own), freeing memory unused for an hour (damon_reclaim, in µs; the
# watermarks make it run whatever memory is free), so the host can take it back (virtio-balloon
# free page reporting).
# - console= show the console on screen and on the serial port
# - systemd.machine_id= take the machine ID from the VM's firmware;
# mkosi.extra/etc/machine-id is empty, so no boot
# counts as the first
# - systemd.firstboot=no agent-setup asks its own questions
# - damon_reclaim.* free memory unused for an hour (min_age is in µs),
# so the host can take it back through virtio-balloon
# free page reporting. The watermarks make it run
# however much memory is free.
KernelCommandLine=
console=tty0
console=ttyS0,115200n8
@@ -79,7 +87,7 @@ KernelCommandLine=
damon_reclaim.wmarks_high=1000
damon_reclaim.wmarks_mid=999
damon_reclaim.wmarks_low=0
# Kernel modules in the initrd: only what finds and mounts the disks of a VM.
# The initrd only needs to find and mount the disks of a VM.
KernelInitrdModules=
virtio_blk
virtio_scsi
@@ -88,9 +96,10 @@ KernelInitrdModules=
dm-verity
erofs
ext4
# Kernel modules in the image: all but the hardware drivers, then the drivers of a VM (disks,
# network, screen) and of rootless podman's networks (pasta). The last matching line wins.
# Keyboard, USB and a basic screen are built into the kernel.
# All modules but the hardware drivers, then the drivers a 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 built into the
# kernel.
KernelModules=
/*
-/drivers/*
@@ -108,8 +117,10 @@ KernelModules=
tun
# - System.map only for debugging the kernel
# - udev hwdb hardware names and quirks, nothing a VM needs
# - homed, userdbd, nsresourced unused services
# - sshd-keygen sshd uses one host key, kept on /var (sshd_config.d)
# - homed, userdbd, unused services
# nsresourced
# - sshd-keygen sshd uses one host key, kept on /var
# (mkosi.extra/etc/ssh/sshd_config.d)
RemoveFiles=
/usr/lib/modules/*/System.map
/usr/lib/udev/hwdb.bin
@@ -120,10 +131,10 @@ RemoveFiles=
/usr/lib/systemd/system/sshd-keygen*
[Validation]
# Signs systemd-boot and the UKI for Secure Boot, and puts our keys on the ESP, where systemd-boot
# enrolls them at first boot if the firmware is in setup mode (no keys enrolled; in Proxmox, an EFI
# disk without pre-enrolled keys). mkosi.crt is the certificate; mkosi.key, its private key, is the
# SECUREBOOT_KEY secret of this repository, which the os workflow writes to mkosi.key.
# Sign systemd-boot and the UKI for Secure Boot, and put our keys on the ESP.
# systemd-boot enrolls them at first boot if the firmware is in setup mode (no
# keys enrolled; in Proxmox, an EFI disk without pre-enrolled keys).
# mkosi.key is the SECUREBOOT_KEY secret, which .gitea/workflows/os.yml writes.
SecureBoot=yes
SecureBootKey=mkosi.key
SecureBootCertificate=mkosi.crt
+4 -1
View File
@@ -1,2 +1,5 @@
# Claude's config, with its login, lives on /var/lib/agent (kept across reboots), not in the home.
# 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
+4 -1
View File
@@ -1,2 +1,5 @@
# /var, the only partition on disk that is written (mkosi.repart/30-var.conf). Grows to fill its partition at boot.
# 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.
PARTLABEL=var /var ext4 x-systemd.growfs 0 2
@@ -1,6 +1,8 @@
# ssh: only the user claude, only with the key asked at setup. The host key is kept on /var
# (agent-boot makes it), so it stays the same across reboots. First value wins: this file sorts
# before Fedora's 50-redhat.conf.
# ssh login
#
# Only the user claude may log in, only with the key asked at setup. The host
# key lives on /var (agent-boot makes it), so it stays the same across reboots.
# The first value wins, and this file sorts before Fedora's 50-redhat.conf.
HostKey /var/lib/agent/ssh_host_ed25519_key
AuthorizedKeysFile /var/lib/agent/authorized_keys
AllowUsers claude
+4 -2
View File
@@ -1,4 +1,6 @@
# Grow the /var partition to fill the disk at boot (systemd-repart); x-systemd.growfs in /etc/fstab
# then grows its filesystem.
# 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
+4 -2
View File
@@ -1,3 +1,5 @@
# Containers (file watchers, systemd in containers) run out of Fedora's 128 inotify instances
# per user; 8192 is common on Kubernetes nodes.
# Kernel settings
#
# Containers (file watchers, systemd in containers) run out of Fedora's 128
# inotify instances per user. 8192 is common on Kubernetes nodes.
fs.inotify.max_user_instances = 8192
@@ -1,4 +1,7 @@
# DHCP on the real network cards. Kind=!* skips virtual links.
# Network
#
# DHCP on the real network cards. Kind=!* skips virtual links such as those of
# containers.
[Match]
Type=ether
Kind=!*
@@ -1,8 +1,13 @@
# Services enabled in the image (mkosi runs systemctl preset-all). Fedora disables getty@.service, the
# login on the screen (tty1, and tty2-6 through its autovt@ alias); this file sorts first, so it wins.
# Enabled services
#
# mkosi runs systemctl preset-all, which applies this file. It sorts before
# Fedora's presets, so it wins where they disagree.
enable systemd-networkd.service
enable systemd-resolved.service
enable sshd.service
# Fedora disables the login on the screen (tty1, and tty2-6 through its
# autovt@ alias).
enable getty@.service
enable agent-setup@.service tty1 ttyS0
enable etc-shadow.mount
@@ -10,8 +15,8 @@ enable agent-boot.service
enable claude-remote.path
enable systemd-sysupdate-update.timer
enable systemd-sysupdate-reboot.timer
# Fedora enables these, but they do nothing here: no PAM or crypto changes on a read-only /etc,
# no system or config extensions.
# Fedora enables these, but they do nothing here: no PAM or crypto changes on a
# read-only /etc, and no system or config extensions.
disable authselect-apply-changes.service
disable fips-crypto-policy-overlay.service
disable systemd-sysext.service
@@ -1,5 +1,7 @@
# Applies the setup answers at every boot (see /usr/libexec/agent-boot). Before the setup is done
# there are none; agent-setup starts this when it is.
# 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
@@ -1,5 +1,8 @@
# First boot: asks for the root password, hostname and ssh key, on the screen (tty1) and the serial
# console (ttyS0) at once; whichever is answered first stops the other.
# 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
@@ -8,13 +11,14 @@ 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
# Answering on one console stops the setup on the other (SIGTERM), which is no failure.
# Being stopped by the other console is not a failure.
SuccessExitStatus=SIGTERM
[Install]
@@ -1,4 +1,7 @@
# Starts Claude (Remote Control) once it is logged in: at boot, or when the user first logs in.
# Start Claude when logged in
#
# Starts claude-remote.service once Claude has a login: at boot, or as soon as
# the user first logs in.
[Unit]
Description=Start Claude Remote Control once logged in
@@ -1,5 +1,8 @@
# Claude Code, in the background, controlled from claude.ai/code or the Claude app (Remote Control).
# Works in Claude's home. Started by claude-remote.path once Claude is logged in.
# 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.
[Unit]
Description=Claude Code Remote Control
Wants=network-online.target user@1000.service
@@ -1,4 +1,6 @@
# The root password. /etc is read-only, so agent-setup writes the shadow file to /var and this
# 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
@@ -1,4 +1,7 @@
# The host key is made by agent-boot, once the setup is done; agent-setup then starts sshd.
# 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,9 @@
# Updates the root filesystem: writes the next version to the unused root partition.
# Verify=yes: SHA256SUMS.gpg must be signed by a key in /usr/lib/systemd/import-pubring.pgp, and
# SHA256SUMS checks each download.
# Root update
#
# Writes the next version of the root filesystem to the unused root 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.
[Transfer]
ProtectVersion=%A
Verify=yes
@@ -1,4 +1,7 @@
# Updates the root filesystem's dm-verity hashes, next to 10-root.transfer (see it for Verify=yes).
# Root verity update
#
# Writes the dm-verity hashes that go with 10-root.transfer, which explains
# Verify=yes.
[Transfer]
ProtectVersion=%A
Verify=yes
@@ -1,8 +1,13 @@
# Installs the next UKI, which systemd-boot boots by default. Verify=yes: see 10-root.transfer.
# It gets three tries (boot counting, the +@l-@d in its name; no Mode=0444, systemd-boot can't
# rename a read-only file): systemd-bless-boot marks it good once a boot gets through
# (boot-complete.target); if none does, systemd-boot goes back to the previous UKI, and with it
# the previous root partition (each UKI holds its root hash).
# UKI update
#
# Installs the next UKI, which systemd-boot then boots by default. For
# Verify=yes, see 10-root.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
# Mode=0444: systemd-boot can't rename a read-only file.
[Transfer]
ProtectVersion=%A
Verify=yes
+4 -1
View File
@@ -1,2 +1,5 @@
# The user Claude runs as; /etc/subuid and /etc/subgid give it the ids of rootless podman.
# Claude 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
+9 -4
View File
@@ -1,9 +1,14 @@
# State kept across reboots: the setup answers, the ssh host key and Claude's login
# (agent-boot wipes the rest of Claude's config).
# Agent directories
#
# What survives a reboot and what doesn't. Claude can only write to the wiped
# directories, /tmp and its own config.
# Kept: the setup answers, the ssh host key 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 -
# Wiped at every boot (D empties a directory at boot): Claude's home, with its podman storage, and
# temporary files. These, /tmp and Claude's config are all that Claude can write.
# Wiped at every boot (D): Claude's home, with its podman storage, and
# temporary files.
D /var/home/claude 0700 claude claude -
D /var/tmp 1777 root root -
# Start Claude's user manager at boot, for rootless podman and its own services.
+6 -3
View File
@@ -1,7 +1,10 @@
#!/bin/bash
# Every boot (agent-boot.service), and after the setup: sets the hostname asked at setup (/etc is
# read-only, so it is set on every boot), makes the ssh host key the first time, and wipes
# Claude's config except its login, so Claude starts fresh but logged in.
# 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)"
+26 -10
View File
@@ -1,24 +1,40 @@
#!/bin/bash
# First boot: asks for the root password, the hostname and the ssh key of the user claude, on the
# screen (tty1) and the serial console (ttyS0) at once (agent-setup@.service).
# /etc is read-only, so the answers go to /var/lib/agent: the password to a shadow file there
# (etc-shadow.mount puts it over /etc/shadow), the rest is applied by agent-boot at every boot.
# First-boot setup
#
# Asks for the root password, the hostname and the ssh key of the user claude
# (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.
#
# With the credential agent.password, it asks nothing and takes the answers
# from the credentials agent.password, agent.hostname and agent.ssh-key, such
# as for a test VM (README.md).
set -euo pipefail
echo "== Agent setup =="
cred() { cat "${CREDENTIALS_DIRECTORY:-/nonexistent}/agent.$1" 2>/dev/null; }
while :; do
if pw=$(cred password); then
# Both consoles run this script. Only one may do the setup.
exec 9>/run/agent-setup.lock
flock -n 9 || exit 0
name=$(cred hostname) || true
key=$(cred ssh-key) || 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
done
read -rp "Hostname [agent]: " name
read -rp "SSH public key for the user claude: " key
fi
install -d -m 0700 /var/lib/agent/etc
cp /etc/passwd /etc/shadow /var/lib/agent/etc/
echo "root:$pw" | chpasswd --prefix /var/lib/agent
systemctl start etc-shadow.mount
read -rp "Hostname [agent]: " name
read -rp "SSH public key for the user claude: " key
[[ -n $key ]] && install -m 0644 /dev/stdin /var/lib/agent/authorized_keys <<<"$key"
# Written last: its presence marks the setup as done.
echo "${name:-agent}" > /var/lib/agent/hostname
+3 -1
View File
@@ -1,4 +1,6 @@
# EFI system partition: systemd-boot and the UKIs (two versions at most).
# EFI system partition
#
# Holds systemd-boot and the UKIs, two versions at most.
[Partition]
Type=esp
Format=vfat
+7 -3
View File
@@ -1,5 +1,8 @@
# The root filesystem, slot A: /etc and /usr, read-only erofs protected by dm-verity (roothash= in
# the UKI). Updates replace it whole. /var, the state, is its own partition (30-var.conf).
# 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
@@ -11,5 +14,6 @@ Verity=data
VerityMatchKey=root
SizeMinBytes=1G
SizeMaxBytes=1G
# The file name holds the partition UUID, which roothash= finds the root by; updates keep it (@u in sysupdate.d).
# roothash= finds the root by its partition UUID, so the file name holds it
# and updates keep it (@u in mkosi.extra/usr/lib/sysupdate.d).
SplitName=%t.%U
+3 -1
View File
@@ -1,4 +1,6 @@
# dm-verity hashes of the root filesystem, slot A.
# Root verity, slot A
#
# The dm-verity hashes of the root filesystem in 10-root.conf.
[Partition]
Type=root-verity
Label=%M_%A_verity
+3 -1
View File
@@ -1,4 +1,6 @@
# The root filesystem, slot B: empty until systemd-sysupdate writes the next version.
# Root filesystem, slot B
#
# Empty until systemd-sysupdate writes the next version to it.
[Partition]
Type=root
Label=_empty
+3 -1
View File
@@ -1,4 +1,6 @@
# dm-verity hashes of the root filesystem, slot B.
# Root verity, slot B
#
# The dm-verity hashes for 20-root-b.conf, empty until the next update.
[Partition]
Type=root-verity
Label=_empty
+6 -3
View File
@@ -1,6 +1,9 @@
# /var: Claude's home and the state that reboots and updates keep (/var/lib/agent: the setup answers
# and Claude's login, the root password). Mounted by /etc/fstab, which also grows it to fill the
# disk at boot. Claude's home, with its containers, is wiped at every boot (tmpfiles.d/agent.conf).
# 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
@@ -1,6 +1,7 @@
# Claude Code
# Claude Code repository
#
# Anthropic's package repository, stable channel. The key's fingerprint is
# Anthropic's package repository, stable channel. mkosi uses it to install the
# claude-code package (mkosi.conf). The key's fingerprint is
# 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE.
[claude-code]
name=Claude Code
+3 -1
View File
@@ -1,5 +1,7 @@
#!/bin/sh
# Image version
#
# The build time (UTC), so every build is newer than the last.
# Prints the build time in UTC (YYYYMMDDhhmm). Every build gets a higher
# version than the one before, which is how systemd-sysupdate tells that an
# update is newer.
date -u +%Y%m%d%H%M