refactor: rename to agentos, hand-picked /etc, user presets at first boot
os / os (push) Waiting to run
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:
25 files changed
+253
-249
No files matched your search
@@ -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.
|
||||
@@ -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
|
||||
@@ -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,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
|
||||
@@ -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
|
||||
Reference in new issue
Block a user