26 Commits
Author SHA1 Message Date
Job79andClaude Opus 5.5 738a902b2d docs: drop the trust step, which agent.conf already does
os / os (push) Waiting to run
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 16:48:30 +01:00
Job79andClaude Opus 5.5 3a4a9f715a fix: run Remote Control in ~/work, which Claude can trust
os / os (push) Waiting to run
Claude never saves trust for a home directory, so claude-remote.service
now runs in ~/work, which tmpfiles makes and pre-trusts in .claude.json.
Its status screen on stdout no longer floods the journal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 16:47:45 +01:00
Job79andClaude Opus 5.5 1707500c05 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>
2026-11-22 15:48:42 +01:00
Job79andClaude Opus 5.5 186d133cbc fix: keep the mkosi workspace off overlayfs in the test container
os / os (push) Canceled after 0s
mkosi's copy_tree() leaves out all xattrs when it copies a tree with SELinux
labels to overlayfs. In the podman test container the workspace was in
/var/tmp on the container's overlayfs, and the cached tree has the host's
SELinux labels, so newuidmap and newgidmap lost their file capabilities and
rootless podman failed in the VM. A volume at /var/tmp avoids that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V27snrrx9tfCQvBpqtSPn3
2026-11-21 20:53:45 +01:00
Job79andClaude Opus 5.5 5255656258 refactor: style pass, tools tree and fixes from a test build
os / os (push) Canceled after 0s
- Follow AGENTS.md style: headers start with the file's name, short
  notes are full sentences, comments within 80 columns.
- Build with mkosi's tools tree, pinned to the image's release
  (ToolsTreeRelease=%r): rawhide's repositories made the image rawhide.
- Incremental builds with mkosi.cache/ for faster local rebuilds.
- Hostname= instead of systemd.hostname= on the kernel command line.
- mkosi.finalize: bash, no cd, and L+ for /etc/systemd. PID 1 applies
  the presets at first boot and made /etc/systemd/system, which blocked
  the link, so /etc/systemd/user (the user's D-Bus) was missing.
- Disable homed, userdbd and nsresourced with presets instead of
  deleting their units. Drop modules the kernel has built in.
- mkosi.version adds the git commit to the version.
- One dev container per worktree or session in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 20:37:26 +01:00
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
Job79andClaude Opus 5.5 db8fb0d5a4 feat: root adds the ssh keys, mkosi ssh for the test VM
The setup no longer asks for an ssh key. Root logs in on the console and
adds keys for claude and root to /var/lib/agent. Root may log in with
ssh, and its home is a tmpfs that is wiped at every boot. The test VM
uses mkosi ssh instead of a forwarded port, so the agent.ssh-key
credential is gone.

Also mount /var with noatime, move STYLE.md into AGENTS.md and rewrite
comments to start with the name of what they describe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 19:10:54 +01:00
Job79andClaude Opus 5.5 8aeb448936 docs: how to measure a normal boot of the test VM
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:09:15 +01:00
Job79andClaude Opus 5.5 49ae3230ed perf: drop DAMON reclaim
It sampled memory every 5ms, always on, which woke the VM ~400 times a
second at idle instead of ~50. Memory the VM has used now stays with it
until it needs it again or reboots.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 20:52:00 +01:00
Job79andClaude Opus 5.5 9dc6dff880 ci: compress the root partition with zstd -9
-19 took 34s for 5% less than -9, which takes 6s. The erofs inside is
compressed already.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 20:39:53 +01:00
Job79andClaude Opus 5.5 08fccd6aaf ci: convert the qcow2 on several cores
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 20:38:45 +01:00
Job79andClaude Opus 5.5 6fdd32834f perf: raise systemd's mount rate limit at boot
systemd handles mount changes at most 5 times per second and holds back
mount jobs once it hits that. At boot this delayed mounting / in the
initrd and /var by up to a second each. Boot goes from ~4.7s to ~2.4s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 20:30:10 +01:00
Job79andClaude Opus 5.5 a98a110dc0 perf: keep systemd-boot-random-seed
It seeds the kernel's RNG at the next boot. Keeping it is worth the
wait for the ESP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:56:10 +01:00
Job79andClaude Opus 5.5 71277dd4cd perf: ext4 for /var, drop systemd-boot-random-seed
xfs is a module in Fedora's kernel and takes ~0.5s to load, which held
up mounting /var. ext4 is built in. systemd-boot-random-seed waited ~1s
for the ESP to mount. Also remove /afs and /buildroot from the image and
give the test VM 4 CPUs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:55:19 +01:00
Job79andClaude Opus 5.5 144ce30757 test: give the test VM 8 CPUs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:46:07 +01:00
Job79andClaude Opus 5.5 51272b708c build: keep downloaded packages in mkosi.pkgcache
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:36:23 +01:00
Job79andClaude Opus 5.5 2439f58279 docs: move testing details from README to AGENTS.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:33:00 +01:00
Job79andClaude Opus 5.5 3b791adc3d docs: list the mkosi container's needs instead of a Containerfile
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:18:50 +01:00
Job79andClaude Opus 5.5 e9b93b11a6 Merge branch 'mkosi-vm' into main
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:15:57 +01:00
Job79andClaude Opus 5.5 86f64a6304 perf: xfs for /var, lz4hc for the root erofs
xfs replaces ext4 on /var (no fsck pass, so fstab passno 0), and the
root erofs uses lz4hc, which decompresses faster than zstd.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:15:34 +01:00
Job79andClaude Opus 5.5 3146f54994 feat: run mkosi vm in a container with systemd
mkosi vm hangs where the host has no systemd, such as in a dev
container. The Containerfile runs systemd as init with mkosi and qemu,
so mkosi -f vm works through podman exec. Tested: builds and boots to
the login in about 105 seconds, of which booting takes about 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 21:15:12 +01:00
Job79andClaude Opus 5.5 eb8e4b440a feat: boot a test VM with mkosi -f vm
The [Runtime] section of mkosi.conf sets up mkosi vm for testing: it
passes the setup credentials (mkosi.credentials/agent.ssh-key prints your
own ssh keys), forwards ssh to port 2222 and adds the serial console,
since systemd-stub ignores the console= mkosi passes under Secure Boot.

Untested: in a container without systemd, mkosi vm hangs before qemu
starts, because it can't create a systemd scope.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 21:02:43 +01:00
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: Job79/agent-mkosi#1
2026-11-16 19:09:28 +00:00
54 changed files with 516 additions and 461 deletions

No files matched your search

+18 -31
View File
@@ -1,47 +1,27 @@
# agent OS image
# os.yml builds the OS image and publishes it as version "latest". VMs fetch
# the built images as updates (mkosi.extra/usr/lib/sysupdate.d). It runs on
# every push, weekly for package updates, and by hand for critical CVEs.
#
# 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.
#
# 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:
branches: [main]
schedule:
- cron: "0 2 * * 0" # weekly (Sunday), picks up package updates
workflow_dispatch: # run by hand, e.g. for a CVE
- cron: "0 2 * * 0"
workflow_dispatch:
jobs:
os:
runs-on: linux
env:
PKG: ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/generic/agent/latest
AUTH: "Authorization: token ${{ gitea.token }}"
steps:
- name: Install tools
run: dnf install -yq mkosi sbsigntools
run: dnf install -yq mkosi git-core
- name: Check out
uses: builtin:checkout
- name: Build
@@ -53,9 +33,10 @@ jobs:
- name: Compress
working-directory: mkosi.output
run: |
zstd -q --rm -T0 -19 agent_*.root-*.raw
qemu-img convert -c -O qcow2 "$(basename agent_*.efi .efi).raw" agent.qcow2
sha256sum agent_*.efi agent_*.root-*.raw.zst > SHA256SUMS
zstd -q --rm -9 agentos_*.usr-*.raw
- name: Checksum
working-directory: mkosi.output
run: sha256sum agentos_*.efi agentos_*.usr-*.raw.zst > SHA256SUMS
- name: Sign
working-directory: mkosi.output
env:
@@ -64,10 +45,16 @@ jobs:
export GNUPGHOME=$(mktemp -d)
gpg -q --batch --import <<< "$KEY"
gpg -q --batch -o SHA256SUMS.gpg --detach-sign SHA256SUMS
- name: Build qcow2
working-directory: mkosi.output
run: qemu-img convert -c -O qcow2 "$(basename agentos_*.efi .efi).raw" agentos.qcow2
- name: Publish
working-directory: mkosi.output
env:
PKG: ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/generic/agentos/latest
AUTH: "Authorization: token ${{ gitea.token }}"
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 agentos_*.efi agentos_*.usr-*.raw.zst agentos.qcow2 agentos_*.manifest SHA256SUMS.gpg SHA256SUMS; do
curl -fsS -o /dev/null -H "$AUTH" --upload-file "$f" "$PKG/$f"
done
+2 -1
View File
@@ -1,2 +1,3 @@
mkosi.output/
mkosi.key
mkosi.output/
mkosi.cache/
+98
View File
@@ -0,0 +1,98 @@
# Agent notes
How to build and test this image as a coding agent. Follow [Style](#style) for
every change.
## Style
- Keep it simple. Prefer fewer files and fewer lines. Delete what isn't
needed. Write plain English in short sentences.
- Follow the defaults and conventions of each tool and language. Only set an
option when the default doesn't work.
- Each fact lives in one place. Elsewhere, refer to it instead of repeating it.
- Divide code and config into parts (files, directories, sections) that each
stand on their own: reading one part alone tells you what it does and why.
- Name each part for what it does. A part without a good name holds things
that don't belong together.
- A little copying beats a little dependency. Repeat a small piece rather than
share it or pull it in from elsewhere.
### File header
A file starts with a header, after the shebang if there is one. Leave it out
when the name already says it all, as with `.gitignore`. A part made of
many files, like a package, needs it in only one file. For example:
```sh
#!/bin/bash
# mkosi.version prints the build time in UTC (YYYYMMDDhhmm) and the git
# commit. Every build gets a higher version than the one before, which is how
# systemd-sysupdate tells that an update is newer. The commit tells which
# source an image was built from.
```
- The first sentence starts with the name of the part the file is, and says
what it does. That is the name the language or tool uses for it, such as a
file name or a package name.
- The rest says why, naming the files it works with by path.
Files that can't hold comments (JSON, `subuid`, `machine-id`) are explained in
the file that uses them.
### Comments
- Explain why, not what. Leave out comments that only repeat the code. Try to
write clean code instead of comments.
- Write full sentences that start with the name of what they describe:
`# ManifestFormat lists the packages and versions in the image.` or
`# link prints the tmpfiles line for /etc/$1.`
- Put a comment right above the line or block it is about. A short note on
one line may go at the end of that line, as a full sentence too.
- Separate paragraphs and lists with a line holding only the comment
character.
- Wrap comments at 80 columns.
## Testing
`mkosi vm` boots the image in qemu. It needs systemd on the host, so run mkosi
in a privileged podman container that boots systemd:
```sh
podman build -t mkosi-vm - <<'END'
FROM registry.fedoraproject.org/fedora:45
RUN dnf install -y mkosi git-core qemu-system-x86-core edk2-ovmf swtpm-tools \
virtiofsd openssh-clients socat
CMD ["/sbin/init"]
END
podman run -d --name mkosi --privileged --systemd=always -v <repo>:/repo \
-v mkosi-cache:/root/.cache/mkosi -v mkosi-work:/var/tmp -w /repo mkosi-vm
podman exec mkosi mkosi genkey # Run this once, if there is no mkosi.key.
podman exec mkosi mkdir -p mkosi.cache
podman exec -d -t mkosi sh -c 'mkosi -i -f \
--kernel-command-line-extra=console=ttyS0 vm -- -serial chardev:console \
> mkosi.output/vm.log 2>&1'
podman exec mkosi mkosi ssh -- systemctl --failed
```
- `mkosi -i` keeps the image with its packages installed in `mkosi.cache/`.
Rebuilds start from it and skip installing packages.
- The volume `mkosi-work` keeps mkosi's workspace in /var/tmp off overlayfs.
When mkosi copies files with SELinux labels to overlayfs, it drops all
xattrs. That removes the file capabilities of newuidmap and newgidmap, and
rootless podman fails in the VM.
- `mkosi vm` needs a terminal, hence `-d -t`. Its console goes to the log.
- The console of `mkosi vm` is hvc0, which the kernel can only use once the
initrd loads its driver. `console=ttyS0` also sends the kernel log to the
serial port, and `-serial chardev:console` sends that port to the same log.
The log then shows early errors too, such as a panic or an initrd that
can't find /usr. Arguments after `--` go to qemu.
- `mkosi ssh` runs a command as root once the VM has booted. For the user
`agent`, run `su - agent -c '<command>'`.
`mkosi.version` gives each run a new version, so `mkosi vm` without `-f` fails
with "has not been built yet". To boot an existing build again, pin its version
from `mkosi.output/agentos_<version>.raw`:
```sh
mkosi --image-version 202611171816.c80e843 vm
```
+34 -25
View File
@@ -1,42 +1,51 @@
# agent-mkosi
# agentos
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.
- **Read-only OS:** `/usr` is read-only, so Claude can't change the OS. Secure
Boot verifies the UKI (kernel, initrd and command line), which holds the
dm-verity hash that verifies `/usr`.
- **Encrypted with a TPM:** everything that isn't read-only, such as `/etc`,
`/var` and `/home`, is encrypted. The TPM unlocks it only for correctly signed
UKIs.
- **Easy to reset:** a factory reset wipes everything that isn't read-only, and
the VM sets itself up again as at first boot.
- **Tools in containers:** Claude runs as the user `agent`, without root, and
runs its toolchains in containers with podman.
- **Self-updating:** the image rebuilds weekly. A bad update rolls back by
itself.
## 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/agentos/latest/agentos.qcow2),
resize it to the disk size you want and boot it with UEFI and a TPM. At first
boot, the screen offers a recovery key for the encrypted disk and asks for a
root password. Then log in as root and put your ssh key in
`/home/agent/.ssh/authorized_keys` (for root: `~/.ssh/authorized_keys`), which
starts sshd. Run `claude` once as `agent` to sign in. The VM then shows up in
claude.ai/code and the Claude app under its hostname: `agentos-` and four hex
digits.
Then log Claude in once:
```sh
ssh claude@<vm>
claude # trust the folder (your home), 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`.
To start over, run `systemctl start factory-reset.target` as root. It reboots
and wipes the root partition (`/etc`, `/var` and `/home`), and the VM sets
itself up as at first boot.
## 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 # This is for local tests. 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 (`agentos_<version>.raw`) and the UKI
and /usr partitions that make up an update.
`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):
To build and boot a test VM:
```sh
qemu-img convert -O qcow2 mkosi.output/agent_<version>.raw test.qcow2 && qemu-img resize 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 \
-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
mkosi -f vm # This opens the console. Log in as root, password root.
mkosi ssh # This logs in as root with ssh, in another terminal.
```
-43
View File
@@ -1,43 +0,0 @@
# 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.
## File header
Every file that allows comments starts with a header. It goes after the shebang, if there is one:
```sh
#!/bin/sh
# Image version
#
# The build time (UTC), so every build is newer than the last.
```
- Line 1 is a title: a few words, in sentence case, with no full stop.
- Then a line with only the comment character.
- Then what the file does and why, naming the files it works with by path.
Files that can't hold comments (JSON, `subuid`, `machine-id`) are explained in the file that uses
them or in the README.
## Comments
- 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.
+78 -80
View File
@@ -1,55 +1,74 @@
# 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.
# mkosi.conf builds agentos, a Fedora VM image that runs Claude Code. The
# image holds a read-only /usr. The root filesystem, which holds the state,
# is made at first boot.
#
# The other parts of the build:
# - mkosi.extra/ is copied to /.
# - mkosi.repart/ defines the disk image: the ESP and the /usr partitions.
# - mkosi.extra/usr/lib/repart.d/ makes the root partition at first boot.
# - mkosi.finalize keeps /etc in /usr/share/factory/etc.
# - mkosi.sandbox/ adds the Claude Code package repository.
# - mkosi.version gives each build its version.
[Distribution]
Distribution=fedora
Release=45
[Output]
Format=disk
ImageId=agent
# Output writes agentos_<version>.* to mkosi.output/. The UKI and /usr
# partitions are split into the files of an update.
ImageId=agentos
OutputDirectory=mkosi.output
# The UKI and root partitions are published as updates (systemd-sysupdate).
SplitArtifacts=uki,partitions
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
# - 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
# Content sets what goes into the image:
# - Hostname is agentos- and four hex digits of the machine ID.
# - WithDocs leaves out man pages. The image has no man to read them.
# - Packages lists the packages installed into the image.
# - UnifiedKernelImageFormat names the UKI agentos_<version>.efi, which matches
# the MatchPattern= of mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer.
# - KernelCommandLine:
# - rw has the initrd mount the root filesystem writable. It finds it by its
# partition type (mkosi.extra/usr/lib/repart.d/50-root.conf).
# - The image policy only accepts an encrypted root filesystem (or none, at
# first boot) and a verity-checked /usr. Otherwise someone with the disk
# could swap in a plain root filesystem. Our UKI would boot it, and their
# code could unseal the key of the real one.
# - The root btrfs keeps one copy of its metadata instead of two (DUP,
# mkfs.btrfs's default). On a VM disk a second copy adds little.
# - The mount rate limit is raised from 5, which holds back mounts at boot
# and delays / and /usr by up to a second each.
# - KernelInitrdModules are what the initrd needs to find the disks of a VM,
# mount /usr and unlock the root filesystem. The kernel has virtio_blk,
# sd_mod, the TPM drivers and btrfs built in.
# - KernelModules keeps all modules but the hardware drivers, then adds back
# the drivers a VM needs (disks, network, screen) and those of podman's
# networks (veth, tun). The last matching line wins. Keyboard, USB and a
# basic screen are built into the kernel.
# - RemoveFiles drops System.map, which is only for debugging the kernel, and
# the udev hwdb, which holds hardware names and quirks a VM doesn't need.
# Without hwdb.d, systemd-hwdb-update can't build it again at boot.
Hostname=agentos-????
WithDocs=no
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
kernel-core # Unlike kernel, this has no extra drivers.
systemd # The init and service manager is PID 1.
dbus-broker # D-Bus serves the user manager and podman.
systemd-udev # Udev, sysupdate, repart, cryptsetup are here.
systemd-networkd # DHCP runs on every network card.
systemd-resolved # DNS names are resolved here.
systemd-container # Sysupdate needs its systemd-pull and gnupg2.
systemd-boot-unsigned # mkosi signs this boot loader.
util-linux # The console login needs its login.
shadow-utils # Rootless podman needs its newuidmap.
systemd-pam # Logins get a session and user manager.
openssh-server # You can log in with ssh once there is a key.
zram-generator-defaults # Swap is compressed in RAM.
podman # Claude runs its tools in containers.
claude-code # Its repo is mkosi.sandbox/etc/yum.repos.d.
git-core # Git pushes over ssh.
curl
tar
gzip
@@ -59,38 +78,19 @@ Packages=
findutils
procps-ng
iproute
WithDocs=no
Locale=C.UTF-8
# The UKI's file name in the ESP, as 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).
KernelCommandLine=
console=tty0
console=ttyS0,115200n8
quiet
systemd.machine_id=firmware
systemd.firstboot=no
damon_reclaim.enabled=Y
damon_reclaim.min_age=3600000000
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.
rw
systemd.image_policy=root=encrypted+absent:usr=verity:esp=unprotected
systemd.setenv=SYSTEMD_REPART_MKFS_OPTIONS_BTRFS=--metadata=single
SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST=50
KernelInitrdModules=
virtio_blk
virtio_scsi
sd_mod
nvme
dm-verity
dm-crypt
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.
KernelModules=
/*
-/drivers/*
@@ -99,31 +99,29 @@ KernelModules=
/drivers/md/*
nvme
virtio_scsi
sd_mod
virtio_net
qemu_fw_cfg
bochs
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)
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.*
/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.
# Validation signs the boot chain with mkosi.key, so the TPM unlocks the root
# filesystem only for our UKIs.
SecureBoot=yes
SecureBootKey=mkosi.key
SecureBootCertificate=mkosi.crt
SignExpectedPcr=yes
[Runtime]
# Runtime sets up the test VM of mkosi vm. Each run boots a fresh copy, with
# root password root and no first boot questions.
Ephemeral=yes
CPUs=4
RAM=4G
RuntimeSize=40G
Credentials=passwd.plaintext-password.root=root
KernelCommandLineExtra=systemd.firstboot=no
+12 -11
View File
@@ -1,14 +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` (also as `docker`). For quick commands:
`podman run --rm -v "$PWD:/w" -w /w docker.io/library/python:3 python script.py`.
For longer work, keep a dev container you can install into:
`podman run -d --name dev -v ~:/w -w /w quay.io/fedora/fedora:45 sleep infinity`, then
`podman exec dev dnf install -y gcc` and `podman exec dev make`.
- On the host: git, ssh, curl, tar/gzip/xz/zstd, find, diff, ps, ip.
- **Everything resets at reboot**: your home (/var/home/claude), /tmp and all containers and
images. Only your Claude login survives. Keep results somewhere else (push them to git, for
example). The VM may reboot at about 04:10 to update.
- 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,4 +1,5 @@
{
"permissions": { "defaultMode": "bypassPermissions" },
"skipDangerousModePermissionPrompt": true
"skipDangerousModePermissionPrompt": true,
"remoteControlAtStartup": true
}
-2
View File
@@ -1,2 +0,0 @@
# Claude's config, with its login, lives on /var/lib/agent (kept across reboots), not in the home.
CLAUDE_CONFIG_DIR=/var/lib/agent/claude
-2
View File
@@ -1,2 +0,0 @@
# /var, the only partition on disk that is written (mkosi.repart/30-var.conf). Grows to fill its partition at boot.
PARTLABEL=var /var ext4 x-systemd.growfs 0 2
View File
Whitespace-only changes.
@@ -1,9 +0,0 @@
# 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.
HostKey /var/lib/agent/ssh_host_ed25519_key
AuthorizedKeysFile /var/lib/agent/authorized_keys
AllowUsers claude
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
+1 -1
View File
@@ -1 +1 @@
claude:524288:65536
agent:524288:65536
+1 -1
View File
@@ -1 +1 @@
claude:524288:65536
agent:524288:65536
+10
View File
@@ -0,0 +1,10 @@
# 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.
#
# 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
Encrypt=tpm2
FactoryReset=yes
-4
View File
@@ -1,4 +0,0 @@
# Grow the /var partition to fill the disk at boot (systemd-repart); x-systemd.growfs in /etc/fstab
# then grows its filesystem.
[Partition]
Type=var
+2 -2
View File
@@ -1,3 +1,3 @@
# Containers (file watchers, systemd in containers) run out of Fedora's 128 inotify instances
# per user; 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,11 +1,8 @@
# DHCP on the real network cards. Kind=!* skips virtual links.
# 80-dhcp.network turns on DHCP on the real network cards. Kind=!* skips
# virtual links such as those of containers.
[Match]
Type=ether
Kind=!*
[Network]
DHCP=yes
[DHCPv4]
# The hostname is the one asked at setup (agent-boot), not the DHCP server's.
UseHostname=no
@@ -1,18 +1,27 @@
# 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.
# 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
enable sshd.service
# 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.
enable getty@.service
enable agent-setup@.service tty1 ttyS0
enable etc-shadow.mount
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.
# authselect-apply-changes fails, because /etc/authselect is on read-only /usr.
disable authselect-apply-changes.service
disable fips-crypto-policy-overlay.service
disable systemd-sysext.service
disable systemd-confext.service
# systemd-homed, systemd-userdbd and systemd-nsresourced are unused here.
disable systemd-homed.service
disable systemd-homed-activate.service
disable systemd-userdbd.socket
disable systemd-nsresourced.socket
@@ -1,15 +0,0 @@
# 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.
[Unit]
Description=Apply agent setup
ConditionPathExists=/var/lib/agent/hostname
After=systemd-tmpfiles-setup.service
Before=sshd.service claude-remote.service
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/libexec/agent-boot
[Install]
WantedBy=multi-user.target
@@ -1,21 +0,0 @@
# 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.
[Unit]
Description=Agent first-boot setup on %I
ConditionPathExists=!/var/lib/agent/hostname
After=systemd-tmpfiles-setup.service
Before=getty@%i.service serial-getty@%i.service
[Service]
Type=oneshot
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.
SuccessExitStatus=SIGTERM
[Install]
WantedBy=multi-user.target
@@ -1,9 +0,0 @@
# Starts Claude (Remote Control) once it is logged in: at boot, or when the user first logs in.
[Unit]
Description=Start Claude Remote Control once logged in
[Path]
PathExists=/var/lib/agent/claude/.credentials.json
[Install]
WantedBy=multi-user.target
@@ -1,14 +0,0 @@
# 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.
[Unit]
Description=Claude Code Remote Control
Wants=network-online.target user@1000.service
After=network-online.target user@1000.service agent-boot.service
[Service]
User=claude
WorkingDirectory=~
Environment=CLAUDE_CONFIG_DIR=/var/lib/agent/claude XDG_RUNTIME_DIR=/run/user/1000
ExecStart=/usr/bin/claude remote-control --name %H
Restart=always
RestartSec=10s
@@ -1,14 +0,0 @@
# The 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
ConditionPathExists=/var/lib/agent/etc/shadow
RequiresMountsFor=/var
[Mount]
What=/var/lib/agent/etc/shadow
Where=/etc/shadow
Options=bind
[Install]
WantedBy=local-fs.target
@@ -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
@@ -0,0 +1,11 @@
# sshd.path starts sshd only once root or the user agent has an ssh key, so a
# new VM has no open port.
[Unit]
Description=Start sshd once an ssh key is set
[Path]
PathExists=/home/agent/.ssh/authorized_keys
PathExists=/root/.ssh/authorized_keys
[Install]
WantedBy=multi-user.target
@@ -1,4 +0,0 @@
# The host key is made by agent-boot, once the setup is done; agent-setup then starts sshd.
[Unit]
After=agent-boot.service
ConditionPathExists=/var/lib/agent/ssh_host_ed25519_key
@@ -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,18 @@
# claude-remote.service runs Claude Code in the background, in ~/work of the
# user agent, so it can be used from claude.ai/code or the Claude app. Claude
# never saves trust for a home directory, so it can't run in ~ itself.
# 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.
#
# Remote Control redraws its status screen on stdout every second, which would
# flood the journal. Its errors go to stderr, which the journal keeps.
[Unit]
Description=Claude Code Remote Control
[Service]
WorkingDirectory=%h/work
ExecStart=/usr/bin/claude remote-control --name %H
StandardOutput=null
StandardError=journal
Restart=always
RestartSec=10s
@@ -1,19 +0,0 @@
# 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.
[Transfer]
ProtectVersion=%A
Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.root-%a.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agent_@v
MatchPartitionType=root
PartitionFlags=0
ReadOnly=1
@@ -0,0 +1,20 @@
# 10-usr.transfer writes the next version of /usr to the inactive /usr
# partition.
#
# 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
[Source]
Type=url-file
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=agentos_@v
MatchPartitionType=usr
PartitionFlags=0
ReadOnly=1
@@ -1,17 +0,0 @@
# Updates the root filesystem's dm-verity hashes, next to 10-root.transfer (see it for Verify=yes).
[Transfer]
ProtectVersion=%A
Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.root-%a-verity.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agent_@v_verity
MatchPartitionType=root-verity
PartitionFlags=0
ReadOnly=1
@@ -0,0 +1,17 @@
# 11-usr-verity.transfer writes the dm-verity hashes that go with
# 10-usr.transfer, which explains how downloads are checked.
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
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=agentos_@v_verity
MatchPartitionType=usr-verity
PartitionFlags=0
ReadOnly=1
@@ -1,22 +1,23 @@
# 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).
# 20-uki.transfer installs the next UKI, which systemd-boot then boots by
# 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.
[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
@@ -0,0 +1,3 @@
# agent.conf adds the user agent, which Claude runs as. /etc/subuid and
# /etc/subgid give it the ids that rootless podman needs.
u agent 1000 "Agent" /home/agent /bin/bash
@@ -1,2 +0,0 @@
# The user Claude runs as; /etc/subuid and /etc/subgid give it the ids of rootless podman.
u claude 1000 "Claude" /var/home/claude /bin/bash
+13 -10
View File
@@ -1,10 +1,13 @@
# State kept across reboots: 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.
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.
f /var/lib/systemd/linger/claude
# agent.conf makes the home of the user agent, and in it work, where
# claude-remote.service runs (mkosi.extra/usr/lib/systemd/user).
d /home/agent 0700 agent agent
d /home/agent/work 0700 agent agent
# .claude.json trusts ~/work, so claude-remote.service can run there without
# the trust dialog first. It is only made if missing, because Claude keeps its
# login there too.
f /home/agent/.claude.json 0600 agent agent - {"projects":{"/home/agent/work":{"hasTrustDialogAccepted":true}}}
# linger starts the user manager of agent at boot, for rootless podman and
# claude-remote.path.
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
-9
View File
@@ -1,9 +0,0 @@
#!/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.
set -euo pipefail
cd /var/lib/agent
hostnamectl hostname --transient "$(cat hostname)"
[[ -f ssh_host_ed25519_key ]] || ssh-keygen -q -t ed25519 -N '' -f ssh_host_ed25519_key
find claude -mindepth 1 -maxdepth 1 ! -name .credentials.json ! -name .claude.json -exec rm -rf {} +
-29
View File
@@ -1,29 +0,0 @@
#!/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.
set -euo pipefail
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
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
systemctl start agent-boot.service sshd.service
echo "Done. Log in with ssh claude@<this VM>, run claude and log in with your account."
echo "Remote Control then starts by itself."
# Stop the setup on the other console, which then shows its login.
systemctl --no-block stop "agent-setup@*.service"
Executable
+8
View File
@@ -0,0 +1,8 @@
#!/bin/bash
# mkosi.finalize keeps the /etc that the packages and mkosi.extra/etc made in
# /usr/share/factory/etc, because the image ships only /usr. At boot,
# mkosi.extra/usr/lib/tmpfiles.d/factory-etc.conf links from it what /etc needs.
set -euo pipefail
cp -a --no-target-directory --update=none "$BUILDROOT/etc" \
"$BUILDROOT/usr/share/factory/etc"
+2 -1
View File
@@ -1,4 +1,5 @@
# EFI system partition: systemd-boot and the UKIs (two versions at most).
# 00-esp.conf defines the EFI system partition. It holds systemd-boot and the
# UKIs, two versions at most.
[Partition]
Type=esp
Format=vfat
-15
View File
@@ -1,15 +0,0 @@
# 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).
[Partition]
Type=root
Label=%M_%A
Format=erofs
Compression=zstd
CopyFiles=/
ExcludeFilesTarget=/var/
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).
SplitName=%t.%U
+17
View File
@@ -0,0 +1,17 @@
# 10-usr.conf defines /usr in slot A: the OS as read-only erofs, protected by
# dm-verity (usrhash= in the UKI). Updates replace it whole. The image holds
# nothing else but the ESP: the initrd makes the root filesystem, with /etc
# and /var, at first boot (mkosi.extra/usr/lib/repart.d/50-root.conf).
[Partition]
Type=usr
Label=%M_%A
Format=erofs
Compression=lz4hc
CopyFiles=/usr:/
Verity=data
VerityMatchKey=usr
SizeMinBytes=1G
SizeMaxBytes=1G
# SplitName holds the partition UUID (%U): usrhash= finds /usr by it, and
# updates keep it (@u in mkosi.extra/usr/lib/sysupdate.d).
SplitName=%t.%U
-9
View File
@@ -1,9 +0,0 @@
# dm-verity hashes of the root filesystem, slot A.
[Partition]
Type=root-verity
Label=%M_%A_verity
Verity=hash
VerityMatchKey=root
SizeMinBytes=64M
SizeMaxBytes=64M
SplitName=%t.%U
+9
View File
@@ -0,0 +1,9 @@
# 11-usr-verity.conf holds the dm-verity hashes of /usr in 10-usr.conf.
[Partition]
Type=usr-verity
Label=%M_%A_verity
Verity=hash
VerityMatchKey=usr
SizeMinBytes=16M
SizeMaxBytes=16M
SplitName=%t.%U
-7
View File
@@ -1,7 +0,0 @@
# The root filesystem, slot B: empty until systemd-sysupdate writes the next version.
[Partition]
Type=root
Label=_empty
SizeMinBytes=1G
SizeMaxBytes=1G
SplitName=-
+8
View File
@@ -0,0 +1,8 @@
# 20-usr-b.conf defines /usr in slot B. It stays empty until systemd-sysupdate
# writes the next version to it.
[Partition]
Type=usr
Label=_empty
SizeMinBytes=1G
SizeMaxBytes=1G
SplitName=-
-7
View File
@@ -1,7 +0,0 @@
# dm-verity hashes of the root filesystem, slot B.
[Partition]
Type=root-verity
Label=_empty
SizeMinBytes=64M
SizeMaxBytes=64M
SplitName=-
+8
View File
@@ -0,0 +1,8 @@
# 21-usr-verity-b.conf holds the dm-verity hashes for 20-usr-b.conf, empty
# until the next update.
[Partition]
Type=usr-verity
Label=_empty
SizeMinBytes=16M
SizeMaxBytes=16M
SplitName=-
-10
View File
@@ -1,10 +0,0 @@
# /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).
[Partition]
Type=var
Label=var
Format=ext4
CopyFiles=/var:/
Minimize=guess
SplitName=-
@@ -1,7 +1,5 @@
# Claude Code
#
# Anthropic's package repository, stable channel. The key's fingerprint is
# 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE.
# claude-code.repo adds Anthropic's package repository, stable channel. mkosi
# uses it to install the claude-code package (mkosi.conf).
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
+8 -5
View File
@@ -1,5 +1,8 @@
#!/bin/sh
# Image version
#
# The build time (UTC), so every build is newer than the last.
date -u +%Y%m%d%H%M
#!/bin/bash
# mkosi.version prints the build time in UTC (YYYYMMDDhhmm) and the git
# commit. Every build gets a higher version than the one before, which is how
# systemd-sysupdate tells that an update is newer. The commit tells which
# source an image was built from.
set -euo pipefail
commit=$(git rev-parse --short HEAD)
echo "$(date -u +%Y%m%d%H%M).$commit"