refactor: rename to agentos, hand-picked /etc, user presets at first boot
os / os (push) Waiting to run

- Rename the image from agent to agentos (ImageId, hostname, CI, docs).
- mkosi.finalize only copies /etc to /usr/share/factory/etc. The hand-written
  tmpfiles.d/factory-etc.conf links the 24 entries the image needs.
- /etc/systemd is writable: PID 1 applies the system presets at first boot
  and preset-global.service the user presets, as in ParticleOS.
- claude-remote runs in the user manager of agent, enabled by a user preset.
- Root has no /var subvolume, and the verity partitions shrink to 16M.
- Style pass over comments, CLAUDE.md and AGENTS.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Job79andClaude Opus 5.5 committed 2026-11-22 15:48:42 +01:00
1 parent 186d133cbc
commit 1707500c05
25 files changed
+253 -249

No files matched your search

+12 -15
View File
@@ -1,18 +1,15 @@
# This machine
You run on a small Fedora VM made for you, as the user `claude`, without root.
A small Fedora VM, made for running Claude Code.
- **The OS is read-only**: you can't install anything on it. Run toolchains, languages and
services in containers, with rootless `podman`. For quick commands:
`podman run --rm -v "$PWD:/w" -w /w docker.io/library/python:3 python script.py`.
For longer work, keep one dev container per worktree or session, named after its directory,
that you install into:
`podman run -d --name "${PWD##*/}" -v "$PWD:$PWD" -w "$PWD" quay.io/fedora/fedora:latest sleep infinity`,
then `podman exec "${PWD##*/}" dnf install -y gcc` and `podman exec "${PWD##*/}" make`.
Remove it with `podman rm -f` when the work is done.
- On the host: git, ssh, curl, tar/gzip/xz/zstd, find, diff, ps, ip.
- **Your files survive reboots**: your home (/home/claude), containers and images stay.
/tmp is wiped at every boot. 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.
- Claude runs as the user `agent`, without root or sudo.
- The OS is read-only. Packages can't be installed on it.
- Run toolchains, languages and services in containers with rootless `podman`.
- For longer work, keep one container per worktree, named after its directory:
- Start: `podman run -d --name "${PWD##*/}" -v "$PWD:$PWD" -w "$PWD" quay.io/fedora/fedora:latest sleep infinity`
- Install: `podman exec "${PWD##*/}" dnf install -y gcc`
- Run: `podman exec "${PWD##*/}" make`
- Remove: `podman rm -f "${PWD##*/}"`
- On the host: git, ssh, curl, tar, gzip, xz, zstd, find, diff, ps, ip.
- The home directory (/home/agent), containers and images survive reboots.
- /tmp is wiped at every boot.
+4 -10
View File
@@ -1,16 +1,10 @@
# 50-root.conf makes the root filesystem 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.
# 50-root.conf makes the root filesystem at first boot, in the free space after
# /usr, and grows it with the disk. It holds all state: /etc and /var.
#
# 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.
# The key is in the TPM, sealed to the signed PCR 11 policy of our UKIs
# (SignExpectedPcr= in mkosi.conf).
[Partition]
Type=root
Format=btrfs
Subvolumes=/var
MakeDirectories=/var
Encrypt=tpm2
FactoryReset=yes
+2 -3
View File
@@ -1,4 +1,3 @@
# 50-agent.conf raises the inotify instances per user. Containers (file
# watchers, systemd in containers) run out of Fedora's 128. 8192 is common on
# Kubernetes nodes.
# 50-agent.conf raises the inotify instances per user from the kernel's 128,
# which many containers running systemd can use up.
fs.inotify.max_user_instances = 8192
@@ -1,24 +1,26 @@
# 50-agent.preset enables the services of the image. mkosi runs systemctl
# preset-all, which applies it. It sorts before Fedora's presets, so it wins
# where they disagree.
# 50-agent.preset enables the services of the image. PID 1 applies it at first
# boot, so a change reaches existing machines only after a factory reset. It
# sorts before Fedora's presets, so it wins where they disagree.
# systemd-networkd is disabled by Fedora, which uses NetworkManager.
enable systemd-networkd.service
enable systemd-resolved.service
# sshd.path starts sshd once there is an ssh key, so Fedora's preset of
# sshd.service is overruled.
# preset-global.service applies the user presets.
enable preset-global.service
# sshd.path starts sshd once there is an ssh key.
enable sshd.path
disable sshd.service
# getty@.service is the login on the screen, which Fedora disables (tty1, and
# tty2-6 through its autovt@ alias).
# getty@.service is the login on the screen, which Fedora disables.
enable getty@.service
enable claude-remote.path
enable systemd-sysupdate-update.timer
enable systemd-sysupdate-reboot.timer
# authselect-apply-changes would rewrite /etc/authselect, which links into the
# read-only /usr (mkosi.finalize), and fails.
# authselect-apply-changes fails, because /etc/authselect is on read-only /usr.
disable authselect-apply-changes.service
# systemd-homed, systemd-userdbd and systemd-nsresourced are unused here.
# Fedora enables them.
disable systemd-homed.service
disable systemd-homed-activate.service
disable systemd-userdbd.socket
@@ -1,10 +0,0 @@
# claude-remote.path 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
[Path]
PathExists=/home/agent/.claude/.credentials.json
[Install]
WantedBy=multi-user.target
@@ -1,15 +0,0 @@
# claude-remote.service runs Claude Code in the background, as the user agent
# in its home, so it can be used from claude.ai/code or the Claude app.
# claude-remote.path starts it once Claude is logged in.
[Unit]
Description=Claude Code Remote Control
Wants=network-online.target user@1000.service
After=network-online.target user@1000.service
[Service]
User=agent
WorkingDirectory=~
Environment=XDG_RUNTIME_DIR=/run/user/1000
ExecStart=/usr/bin/claude remote-control --name %H
Restart=always
RestartSec=10s
@@ -0,0 +1,20 @@
# preset-global.service applies the user presets at first boot, as PID 1 does
# for the system presets. It runs before basic.target, so before any user
# manager starts, which needs DefaultDependencies=no. It is the same as
# ParticleOS's. systemd 263 can apply presets at build time instead, with
# systemctl preset-all --vendor.
[Unit]
Description=Apply the user presets
ConditionFirstBoot=yes
DefaultDependencies=no
Before=basic.target
Conflicts=shutdown.target
Before=shutdown.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=systemctl preset-all --global
[Install]
WantedBy=basic.target
+1 -3
View File
@@ -1,7 +1,5 @@
# sshd.path starts sshd 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.
# new VM has no open port.
[Unit]
Description=Start sshd once an ssh key is set
@@ -0,0 +1,3 @@
# 50-agent.preset enables the user services of the image.
# preset-global.service applies it at first boot.
enable claude-remote.path
@@ -0,0 +1,13 @@
# claude-remote.path starts claude-remote.service once Claude is logged in.
# It runs in the user manager of agent, which linger starts at boot
# (mkosi.extra/usr/lib/tmpfiles.d/agent.conf). ConditionUser keeps it out of
# the user manager of root.
[Unit]
Description=Start Claude Remote Control once logged in
ConditionUser=agent
[Path]
PathExists=%h/.claude/.credentials.json
[Install]
WantedBy=default.target
@@ -0,0 +1,12 @@
# claude-remote.service runs Claude Code in the background, in the home of the
# user agent, so it can be used from claude.ai/code or the Claude app.
# claude-remote.path starts it once Claude is logged in. The user manager can't
# wait for the network, so Restart= retries until it is up.
[Unit]
Description=Claude Code Remote Control
[Service]
WorkingDirectory=~
ExecStart=/usr/bin/claude remote-control --name %H
Restart=always
RestartSec=10s
@@ -1,21 +1,20 @@
# 10-usr.transfer writes the next version of /usr to the unused /usr
# partition. The files come from .gitea/workflows/os.yml.
# 10-usr.transfer writes the next version of /usr to the inactive /usr
# partition.
#
# Verify=yes requires SHA256SUMS.gpg to be signed by a key in
# systemd-sysupdate requires SHA256SUMS.gpg to be signed by a key in
# /usr/lib/systemd/import-pubring.pgp, and SHA256SUMS checks each download.
[Transfer]
ProtectVersion=%A
Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.usr-%a.@u.raw.zst
Path=https://git.plabble.org/api/packages/Job79/generic/agentos/latest/
MatchPattern=agentos_@v.usr-%a.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agent_@v
MatchPattern=agentos_@v
MatchPartitionType=usr
PartitionFlags=0
ReadOnly=1
@@ -1,18 +1,17 @@
# 11-usr-verity.transfer writes the dm-verity hashes that go with
# 10-usr.transfer, which explains Verify=yes.
# 10-usr.transfer, which explains how downloads are checked.
[Transfer]
ProtectVersion=%A
Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.usr-%a-verity.@u.raw.zst
Path=https://git.plabble.org/api/packages/Job79/generic/agentos/latest/
MatchPattern=agentos_@v.usr-%a-verity.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agent_@v_verity
MatchPattern=agentos_@v_verity
MatchPartitionType=usr-verity
PartitionFlags=0
ReadOnly=1
@@ -1,25 +1,23 @@
# 20-uki.transfer installs the next UKI, which systemd-boot then boots by
# default. For Verify=yes, see 10-usr.transfer.
# default. For how downloads are checked, see 10-usr.transfer.
#
# The new UKI gets three tries (boot counting: the +@l-@d in its name).
# systemd-bless-boot marks it good once a boot reaches boot-complete.target.
# If no boot does, systemd-boot goes back to the previous UKI, and with it to
# the previous /usr partition, because each UKI holds its usr hash. No
# Mode=0444: systemd-boot can't rename a read-only file.
# the previous /usr partition, because each UKI holds its usr hash.
[Transfer]
ProtectVersion=%A
Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.efi
Path=https://git.plabble.org/api/packages/Job79/generic/agentos/latest/
MatchPattern=agentos_@v.efi
[Target]
Type=regular-file
Path=/EFI/Linux
PathRelativeTo=boot
MatchPattern=agent_@v+@l-@d.efi agent_@v+@l.efi agent_@v.efi
MatchPattern=agentos_@v+@l-@d.efi agentos_@v+@l.efi agentos_@v.efi
TriesLeft=3
TriesDone=0
InstancesMax=2
+4 -5
View File
@@ -1,7 +1,6 @@
# agent.conf makes the home of the user agent
# (mkosi.extra/usr/lib/sysusers.d/agent.conf), with Claude's login and podman
# storage.
d /home/agent 0700 agent agent -
# agent.conf makes the home of the user agent.
d /home/agent 0700 agent agent
# linger starts the user manager of agent at boot, for rootless podman and
# Claude's own services.
# claude-remote.path (mkosi.extra/usr/lib/systemd/user).
f /var/lib/systemd/linger/agent
@@ -0,0 +1,44 @@
# factory-etc.conf links what the image needs from /usr/share/factory/etc
# (mkosi.finalize) into the empty /etc at boot, so updates to /usr take effect
# in /etc too. The rest of the factory is unused package config. /etc itself
# holds what the machine writes: passwd, shadow, group, machine-id, ld.so.cache,
# /etc/systemd and the ssh host keys. systemd's own etc.conf sets up
# os-release, nsswitch.conf and pam.d.
#
# /etc/systemd is filled from the presets at first boot: by PID 1 for system
# units, and by mkosi.extra/usr/lib/systemd/system/preset-global.service for
# user units.
#
# subuid and subgid are copied, because shadow-utils won't read them through a
# link. Rootless podman needs them.
C /etc/subgid
C /etc/subuid
# /etc/ssh is a writable directory, because sshd-keygen writes the host keys
# there at first boot.
d /etc/ssh 0755
L /etc/ssh/moduli
L /etc/ssh/ssh_config
L /etc/ssh/ssh_config.d
L /etc/ssh/sshd_config
L /etc/ssh/sshd_config.d
# authselect holds the PAM files that /etc/pam.d links to.
L /etc/authselect
L /etc/security
L /etc/environment
L /etc/login.defs
L /etc/shells
# pki and ssl hold the CA certificates, and crypto-policies the TLS and ssh
# settings.
L /etc/pki
L /etc/ssl
L /etc/crypto-policies
L /etc/bashrc
L /etc/profile
L /etc/profile.d
L /etc/protocols
L /etc/services
L /etc/hostname
L /etc/claude-code