From a1fc65ed212522658f0e0b0cd2fae718e7d0b8e8 Mon Sep 17 00:00:00 2001 From: Job79 Date: Mon, 16 Nov 2026 20:14:06 +0100 Subject: [PATCH] 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 --- .gitea/workflows/os.yml | 8 +- .gitignore | 3 + STYLE.md | 19 +---- mkosi.conf | 79 +++++++++++-------- mkosi.extra/etc/environment | 5 +- mkosi.extra/etc/fstab | 5 +- .../etc/ssh/sshd_config.d/10-agent.conf | 8 +- mkosi.extra/usr/lib/repart.d/50-var.conf | 6 +- mkosi.extra/usr/lib/sysctl.d/50-agent.conf | 6 +- .../usr/lib/systemd/network/80-dhcp.network | 5 +- .../lib/systemd/system-preset/50-agent.preset | 13 ++- .../usr/lib/systemd/system/agent-boot.service | 6 +- .../lib/systemd/system/agent-setup@.service | 9 ++- .../usr/lib/systemd/system/claude-remote.path | 5 +- .../lib/systemd/system/claude-remote.service | 7 +- .../usr/lib/systemd/system/etc-shadow.mount | 4 +- .../systemd/system/sshd.service.d/agent.conf | 5 +- .../usr/lib/sysupdate.d/10-root.transfer | 9 ++- .../lib/sysupdate.d/11-root-verity.transfer | 5 +- .../usr/lib/sysupdate.d/20-uki.transfer | 15 ++-- mkosi.extra/usr/lib/sysusers.d/claude.conf | 5 +- mkosi.extra/usr/lib/tmpfiles.d/agent.conf | 13 ++- mkosi.extra/usr/libexec/agent-boot | 9 ++- mkosi.extra/usr/libexec/agent-setup | 11 ++- mkosi.repart/00-esp.conf | 4 +- mkosi.repart/10-root.conf | 10 ++- mkosi.repart/11-root-verity.conf | 4 +- mkosi.repart/20-root-b.conf | 4 +- mkosi.repart/21-root-verity-b.conf | 4 +- mkosi.repart/30-var.conf | 9 ++- .../etc/yum.repos.d/claude-code.repo | 5 +- mkosi.version | 4 +- 32 files changed, 191 insertions(+), 113 deletions(-) diff --git a/.gitea/workflows/os.yml b/.gitea/workflows/os.yml index c471b99..59e0532 100644 --- a/.gitea/workflows/os.yml +++ b/.gitea/workflows/os.yml @@ -1,8 +1,8 @@ -# 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, /api/packages//generic/ diff --git a/.gitignore b/.gitignore index c2947e3..f3cc75c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ +# Ignored files +# +# Build output, and the Secure Boot private key (mkosi.conf, [Validation]). mkosi.output/ mkosi.key diff --git a/STYLE.md b/STYLE.md index 01f4864..2ec4e5d 100644 --- a/STYLE.md +++ b/STYLE.md @@ -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. diff --git a/mkosi.conf b/mkosi.conf index daf6fe1..b53686e 100644 --- a/mkosi.conf +++ b/mkosi.conf @@ -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 @@ -17,19 +20,18 @@ SplitArtifacts=uki,partitions [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 -# - util-linux, shadow-utils console login, setup, newuidmap for rootless podman -# - systemd-pam login sessions (pam_systemd): 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 -# - the rest basic command-line tools Claude uses on the host +# - kernel-core no drivers or firmware beyond what VMs need +# - 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: 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 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 systemd @@ -61,13 +63,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 +85,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 +94,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/* @@ -106,10 +113,12 @@ KernelModules= virtio-gpu veth 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) +# - System.map only for debugging the kernel +# - udev hwdb hardware names and quirks, nothing a VM needs +# - 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 +129,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 diff --git a/mkosi.extra/etc/environment b/mkosi.extra/etc/environment index 7befa6e..2aba1d8 100644 --- a/mkosi.extra/etc/environment +++ b/mkosi.extra/etc/environment @@ -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 diff --git a/mkosi.extra/etc/fstab b/mkosi.extra/etc/fstab index 8c95777..e7d9511 100644 --- a/mkosi.extra/etc/fstab +++ b/mkosi.extra/etc/fstab @@ -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 diff --git a/mkosi.extra/etc/ssh/sshd_config.d/10-agent.conf b/mkosi.extra/etc/ssh/sshd_config.d/10-agent.conf index 884354d..55f3472 100644 --- a/mkosi.extra/etc/ssh/sshd_config.d/10-agent.conf +++ b/mkosi.extra/etc/ssh/sshd_config.d/10-agent.conf @@ -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 diff --git a/mkosi.extra/usr/lib/repart.d/50-var.conf b/mkosi.extra/usr/lib/repart.d/50-var.conf index 9d0525a..a74d973 100644 --- a/mkosi.extra/usr/lib/repart.d/50-var.conf +++ b/mkosi.extra/usr/lib/repart.d/50-var.conf @@ -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 diff --git a/mkosi.extra/usr/lib/sysctl.d/50-agent.conf b/mkosi.extra/usr/lib/sysctl.d/50-agent.conf index 09ba833..3653ac2 100644 --- a/mkosi.extra/usr/lib/sysctl.d/50-agent.conf +++ b/mkosi.extra/usr/lib/sysctl.d/50-agent.conf @@ -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 diff --git a/mkosi.extra/usr/lib/systemd/network/80-dhcp.network b/mkosi.extra/usr/lib/systemd/network/80-dhcp.network index 6000185..18c9667 100644 --- a/mkosi.extra/usr/lib/systemd/network/80-dhcp.network +++ b/mkosi.extra/usr/lib/systemd/network/80-dhcp.network @@ -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=!* diff --git a/mkosi.extra/usr/lib/systemd/system-preset/50-agent.preset b/mkosi.extra/usr/lib/systemd/system-preset/50-agent.preset index 917f117..431fbe8 100644 --- a/mkosi.extra/usr/lib/systemd/system-preset/50-agent.preset +++ b/mkosi.extra/usr/lib/systemd/system-preset/50-agent.preset @@ -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 diff --git a/mkosi.extra/usr/lib/systemd/system/agent-boot.service b/mkosi.extra/usr/lib/systemd/system/agent-boot.service index 527096d..5a11df1 100644 --- a/mkosi.extra/usr/lib/systemd/system/agent-boot.service +++ b/mkosi.extra/usr/lib/systemd/system/agent-boot.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 diff --git a/mkosi.extra/usr/lib/systemd/system/agent-setup@.service b/mkosi.extra/usr/lib/systemd/system/agent-setup@.service index da7f4a9..0b71ccf 100644 --- a/mkosi.extra/usr/lib/systemd/system/agent-setup@.service +++ b/mkosi.extra/usr/lib/systemd/system/agent-setup@.service @@ -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 @@ -14,7 +17,7 @@ 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] diff --git a/mkosi.extra/usr/lib/systemd/system/claude-remote.path b/mkosi.extra/usr/lib/systemd/system/claude-remote.path index ba50a87..ec51bbd 100644 --- a/mkosi.extra/usr/lib/systemd/system/claude-remote.path +++ b/mkosi.extra/usr/lib/systemd/system/claude-remote.path @@ -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 diff --git a/mkosi.extra/usr/lib/systemd/system/claude-remote.service b/mkosi.extra/usr/lib/systemd/system/claude-remote.service index 5b9c52b..d1ef719 100644 --- a/mkosi.extra/usr/lib/systemd/system/claude-remote.service +++ b/mkosi.extra/usr/lib/systemd/system/claude-remote.service @@ -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 diff --git a/mkosi.extra/usr/lib/systemd/system/etc-shadow.mount b/mkosi.extra/usr/lib/systemd/system/etc-shadow.mount index cf988c8..07372af 100644 --- a/mkosi.extra/usr/lib/systemd/system/etc-shadow.mount +++ b/mkosi.extra/usr/lib/systemd/system/etc-shadow.mount @@ -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 diff --git a/mkosi.extra/usr/lib/systemd/system/sshd.service.d/agent.conf b/mkosi.extra/usr/lib/systemd/system/sshd.service.d/agent.conf index 8524a40..bc1bfd3 100644 --- a/mkosi.extra/usr/lib/systemd/system/sshd.service.d/agent.conf +++ b/mkosi.extra/usr/lib/systemd/system/sshd.service.d/agent.conf @@ -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 diff --git a/mkosi.extra/usr/lib/sysupdate.d/10-root.transfer b/mkosi.extra/usr/lib/sysupdate.d/10-root.transfer index af95a16..35b4d04 100644 --- a/mkosi.extra/usr/lib/sysupdate.d/10-root.transfer +++ b/mkosi.extra/usr/lib/sysupdate.d/10-root.transfer @@ -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 diff --git a/mkosi.extra/usr/lib/sysupdate.d/11-root-verity.transfer b/mkosi.extra/usr/lib/sysupdate.d/11-root-verity.transfer index 907d7aa..5d8796a 100644 --- a/mkosi.extra/usr/lib/sysupdate.d/11-root-verity.transfer +++ b/mkosi.extra/usr/lib/sysupdate.d/11-root-verity.transfer @@ -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 diff --git a/mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer b/mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer index 467f899..0327331 100644 --- a/mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer +++ b/mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer @@ -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 diff --git a/mkosi.extra/usr/lib/sysusers.d/claude.conf b/mkosi.extra/usr/lib/sysusers.d/claude.conf index cd3538f..b575564 100644 --- a/mkosi.extra/usr/lib/sysusers.d/claude.conf +++ b/mkosi.extra/usr/lib/sysusers.d/claude.conf @@ -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 diff --git a/mkosi.extra/usr/lib/tmpfiles.d/agent.conf b/mkosi.extra/usr/lib/tmpfiles.d/agent.conf index 14df66b..81132bb 100644 --- a/mkosi.extra/usr/lib/tmpfiles.d/agent.conf +++ b/mkosi.extra/usr/lib/tmpfiles.d/agent.conf @@ -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. diff --git a/mkosi.extra/usr/libexec/agent-boot b/mkosi.extra/usr/libexec/agent-boot index bfe1013..ffd0579 100755 --- a/mkosi.extra/usr/libexec/agent-boot +++ b/mkosi.extra/usr/libexec/agent-boot @@ -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)" diff --git a/mkosi.extra/usr/libexec/agent-setup b/mkosi.extra/usr/libexec/agent-setup index 85f6bc0..ca108bb 100755 --- a/mkosi.extra/usr/libexec/agent-setup +++ b/mkosi.extra/usr/libexec/agent-setup @@ -1,8 +1,11 @@ #!/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. set -euo pipefail echo "== Agent setup ==" diff --git a/mkosi.repart/00-esp.conf b/mkosi.repart/00-esp.conf index f228b03..3c0bc10 100644 --- a/mkosi.repart/00-esp.conf +++ b/mkosi.repart/00-esp.conf @@ -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 diff --git a/mkosi.repart/10-root.conf b/mkosi.repart/10-root.conf index e117697..b320580 100644 --- a/mkosi.repart/10-root.conf +++ b/mkosi.repart/10-root.conf @@ -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 diff --git a/mkosi.repart/11-root-verity.conf b/mkosi.repart/11-root-verity.conf index 1e9761a..099a178 100644 --- a/mkosi.repart/11-root-verity.conf +++ b/mkosi.repart/11-root-verity.conf @@ -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 diff --git a/mkosi.repart/20-root-b.conf b/mkosi.repart/20-root-b.conf index c8b4bdd..e502718 100644 --- a/mkosi.repart/20-root-b.conf +++ b/mkosi.repart/20-root-b.conf @@ -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 diff --git a/mkosi.repart/21-root-verity-b.conf b/mkosi.repart/21-root-verity-b.conf index 1a323ba..244d554 100644 --- a/mkosi.repart/21-root-verity-b.conf +++ b/mkosi.repart/21-root-verity-b.conf @@ -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 diff --git a/mkosi.repart/30-var.conf b/mkosi.repart/30-var.conf index 78fc515..1a838af 100644 --- a/mkosi.repart/30-var.conf +++ b/mkosi.repart/30-var.conf @@ -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 diff --git a/mkosi.sandbox/etc/yum.repos.d/claude-code.repo b/mkosi.sandbox/etc/yum.repos.d/claude-code.repo index d24ee8d..78c81dd 100644 --- a/mkosi.sandbox/etc/yum.repos.d/claude-code.repo +++ b/mkosi.sandbox/etc/yum.repos.d/claude-code.repo @@ -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 diff --git a/mkosi.version b/mkosi.version index f073956..8fc03e7 100755 --- a/mkosi.version +++ b/mkosi.version @@ -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