Files
agentos/mkosi.conf
T
Job79andClaude Opus 5.5 c80e843cb5 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>
2026-11-19 21:09:31 +01:00

177 lines
6.5 KiB
Plaintext

# 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. /usr is read-only and replaced whole by
# updates. The root filesystem holds the state: /var, and an /etc that is
# 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:
# managed-settings.json lets it run without permission prompts, and CLAUDE.md
# tells it about this machine.
[Distribution]
Distribution=fedora
Release=45
[Output]
Format=disk
ImageId=agent
OutputDirectory=mkosi.output
SplitArtifacts=uki,partitions
# ManifestFormat 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
# Packages is systemd with its network services, plus:
# - kernel-core has no drivers or firmware beyond what VMs need.
# - systemd-container has systemd-pull, which systemd-sysupdate downloads with.
# - gnupg2 checks the signature of updates.
# - systemd-boot-unsigned is the boot loader, which mkosi signs.
# - util-linux and shadow-utils give the console login, the setup and
# newuidmap for rootless podman.
# - systemd-pam gives login sessions: Claude's user manager and its D-Bus,
# which rootless podman needs.
# - openssh-server lets you log in with ssh keys.
# - zram-generator-defaults sets up compressed swap in RAM.
# - podman and podman-docker run Claude's toolchains in containers.
# - claude-code comes from mkosi.sandbox/etc/yum.repos.d.
# - git-core and openssh-clients let Claude Code use git and push over ssh.
# - The rest are basic command-line tools Claude uses on the host.
Packages=
kernel-core
systemd
dbus-broker
systemd-udev
systemd-networkd
systemd-resolved
systemd-container
gnupg2
systemd-boot-unsigned
util-linux
shadow-utils
systemd-pam
openssh-server
zram-generator-defaults
podman
podman-docker
claude-code
git-core
openssh-clients
curl
tar
gzip
xz
zstd
diffutils
findutils
procps-ng
iproute
WithDocs=no
Locale=C.UTF-8
# UnifiedKernelImageFormat names UKIs the way systemd-sysupdate names the ones
# it installs.
UnifiedKernelImageFormat=%i_%v
# KernelCommandLine sets:
# - console= shows the console on the serial port and the screen. The last
# one, the screen, is /dev/console, where systemd-firstboot asks for the root
# password at first boot.
# - 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
# changes per second. At the default of 5, it holds back mounts at boot and
# delays / and /usr by up to a second each. The kernel passes it to systemd
# as environment.
KernelCommandLine=
console=ttyS0,115200n8
console=tty0
quiet
rw
systemd.hostname=agent-????
systemd.image_policy=root=encrypted+absent:usr=verity:esp=unprotected
SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST=50
# KernelInitrdModules are the modules the initrd needs to find the disks of a
# VM, mount /usr and make, unlock and mount the root filesystem.
KernelInitrdModules=
virtio_blk
virtio_scsi
sd_mod
nvme
tpm_tis
tpm_crb
dm-verity
dm-crypt
erofs
btrfs
# KernelModules keeps 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/*
/drivers/virtio/*
/drivers/block/*
/drivers/md/*
nvme
virtio_scsi
sd_mod
virtio_net
qemu_fw_cfg
bochs
virtio-gpu
veth
tun
# RemoveFiles drops what the image doesn't use:
# - System.map is only for debugging the kernel.
# - The udev hwdb holds hardware names and quirks, nothing a VM needs.
# - homed, userdbd and nsresourced are unused services.
RemoveFiles=
/usr/lib/modules/*/System.map
/usr/lib/udev/hwdb.bin
/usr/lib/udev/hwdb.d
/usr/lib/systemd/system/systemd-homed*
/usr/lib/systemd/system/systemd-userdbd.*
/usr/lib/systemd/system/systemd-nsresourced.*
[Validation]
# SecureBoot signs systemd-boot and the UKI, and puts 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
# 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 sets up the test VM of mkosi vm (AGENTS.md). Ephemeral boots a copy,
# so test runs don't change the built image. Credentials sets the root
# password, and systemd.firstboot=no skips the questions at first boot, such
# 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
CPUs=4
RAM=8G
RuntimeSize=40G
# QemuArgs joins the serial port to the console mkosi vm shows (hvc0). The UKI
# doesn't use hvc0: with Secure Boot, systemd-stub ignores the console= mkosi
# passes.
QemuArgs=-serial chardev:console
Credentials=passwd.plaintext-password.root=root
KernelCommandLineExtra=systemd.firstboot=no