Author SHA1 Message Date
Job79andClaude Opus 5.5 0a68a046ef fix: check out with git again
actions/checkout needs Node.js in every job and fetches the action from
GitHub. Four lines of git need neither.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:40:59 +00:00
Job79andClaude Opus 5.5 e0cd5db5c5 fix: use Node.js 26 for actions/checkout
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:27:43 +00:00
Job79andClaude Opus 5.5 3793cb0f31 fix: check out with actions/checkout
gitea-runner 6 removed builtin:checkout. With Node.js in the job,
actions/checkout works.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:05:15 +00:00
Job79andClaude Opus 5.5 34be2ef89f docs: say that gitea-runner 6 removed builtin:checkout
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:01:03 +00:00
Job79andClaude Opus 5.5 94fd5d1ce9 fix: check out with git, sign local builds with a test key
gitea-runner 6 has no builtin:checkout, and plain Fedora has no Node.js
for actions/checkout, so the workflow fetches the commit with git.
Setting permissions: keeps read access for that and asks for package
writes.

mkosi genkey won't replace mkosi.crt, so the docs now sign local builds
with a test key in mkosi.local.conf, which also covers the PCR and
verity keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 16:07:45 +00:00
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
56 changed files with 537 additions and 561 deletions

No files matched your search

+31 -16
View File
@@ -1,8 +1,6 @@
# OS image
#
# 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.
# 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.
#
# Required values:
# - SECUREBOOT_KEY repository secret: the private key of mkosi.crt, written
@@ -15,20 +13,30 @@ 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 }}"
# permissions lets gitea.token check out the repository and publish the
# package.
permissions:
contents: read
packages: write
steps:
- name: Install tools
run: dnf install -yq mkosi sbsigntools
run: dnf install -yq mkosi git-core
# Check out fetches the commit with git, which needs no Node.js and no
# action from GitHub. gitea-runner 6 removed builtin:checkout.
- name: Check out
uses: builtin:checkout
env:
AUTH: "Authorization: token ${{ gitea.token }}"
run: |
git init -q
git -c http.extraHeader="$AUTH" fetch -q --depth 1 \
"${{ gitea.server_url }}/${{ gitea.repository }}" "${{ gitea.sha }}"
git checkout -q FETCH_HEAD
- name: Build
env:
KEY: ${{ secrets.SECUREBOOT_KEY }}
@@ -38,9 +46,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:
@@ -49,10 +58,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 agent_*.manifest 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
+3 -1
View File
@@ -1,2 +1,4 @@
mkosi.output/
mkosi.key
mkosi.output/
mkosi.cache/
mkosi.local.conf
+99
View File
@@ -0,0 +1,99 @@
# 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 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 signs with the test key of `mkosi.local.conf`
([README.md](README.md#development)), with paths as the container sees them.
- `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
```
-11
View File
@@ -1,11 +0,0 @@
# mkosi container
#
# Builds and boots a test VM where the host has no systemd, such as a dev
# container (README.md). mkosi vm needs systemd to run qemu in a scope, so
# systemd runs as init here and mkosi runs through podman exec.
FROM registry.fedoraproject.org/fedora:45
RUN dnf install -y --setopt=install_weak_deps=False mkosi dbus-broker \
qemu-kvm-core edk2-ovmf /usr/bin/systemd-repart openssh-clients && \
dnf install -y --setopt=install_weak_deps=False $(mkosi dependencies) && \
dnf clean all
CMD ["/sbin/init"]
+52 -30
View File
@@ -1,47 +1,69 @@
# agent-mkosi
# agentos
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.
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:** Claude's home, `/tmp` and all containers are wiped at every boot. Only the setup answers and Claude's login survive (`/var/lib/agent`).
- **Read-only OS:** the root filesystem is read-only, so Claude can't change the OS. All state lives on `/var`.
- **Tools in containers:** Claude runs as the user `claude`, without root, and runs its toolchains in containers with podman. The host has only git, ssh and basic command-line tools.
- **Self-updating:** the `os` rebuilds weekly and updates with systemd-sysupdate.
- **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), resize it to the disk size you want and boot it with UEFI in Secure Boot setup mode. The console asks 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, then /login with your Claude account
```
The VM then shows up in claude.ai/code and the Claude app under its hostname.
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
```sh
mkosi genkey # local test only, CI uses the SECUREBOOT_KEY secret
mkosi build
```
`mkosi.output/` then holds the disk image (`agent_<version>.raw`) and the UKI and root partitions that make up an update.
To build and boot a test VM with Secure Boot (needs `qemu-kvm-core edk2-ovmf`):
`mkosi build` signs with `mkosi.key`, the private key of `mkosi.crt`, which
only CI has (the `SECUREBOOT_KEY` secret). `mkosi genkey` won't replace
`mkosi.crt`, so local builds sign with a test key. Make one:
```sh
mkosi -f vm
openssl req -new -x509 -newkey rsa:2048 -nodes -subj /CN=test \
-keyout ~/test.key -out ~/test.crt
```
The `[Runtime]` section of `mkosi.conf` answers the setup, so it boots straight to a login (root, password `test`). Then `ssh -p 2222 claude@localhost` with your own key (`mkosi.credentials/agent.ssh-key`).
and point `mkosi.local.conf` at it, which mkosi reads and git ignores:
`mkosi vm` needs systemd on the host. Without it, such as in a dev container, run mkosi in a container with systemd ([Containerfile](Containerfile)):
```ini
[Validation]
SecureBootKey=~/test.key
SecureBootCertificate=~/test.crt
SignExpectedPcrKey=~/test.key
SignExpectedPcrCertificate=~/test.crt
VerityKey=~/test.key
VerityCertificate=~/test.crt
```
Then run `mkosi build`.
`mkosi.output/` then holds the disk image (`agentos_<version>.raw`) and the UKI
and /usr partitions that make up an update.
To build and boot a test VM:
```sh
podman build -t mkosi-vm .
podman run -d --name mkosi --systemd=always --privileged --device /dev/kvm -v .:/repo -v ~/.ssh:/root/.ssh:ro -w /repo mkosi-vm
podman exec -it mkosi mkosi -f vm
podman exec -it mkosi ssh -p 2222 claude@localhost # in another terminal
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.
```
-30
View File
@@ -1,30 +0,0 @@
# Style guide
- 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
#
# 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.
- 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 80 columns.
+72 -99
View File
@@ -1,59 +1,74 @@
# Agent image
# 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.
#
# 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.
# 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
SplitArtifacts=uki,partitions
# Lists the packages and versions in the image, to tell which builds a CVE
# affects. .gitea/workflows/os.yml publishes it with the image.
ManifestFormat=json
[Content]
Bootable=yes
Bootloader=systemd-boot
# - 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
# 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
@@ -63,43 +78,19 @@ Packages=
findutils
procps-ng
iproute
WithDocs=no
Locale=C.UTF-8
# Name UKIs the way systemd-sysupdate names the ones it installs.
UnifiedKernelImageFormat=%i_%v
# - 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
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
# The initrd only needs to find and mount 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
# 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/*
@@ -108,47 +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, 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
/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]
# 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.
# 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]
# For testing with mkosi vm. It does the setup itself (the agent.* credentials,
# mkosi.extra/usr/libexec/agent-setup). Its console is hvc0, which the UKI
# doesn't use: with Secure Boot, systemd-stub ignores the console= mkosi
# passes. So the serial port joins that console, and replaces mkosi's network
# to forward ssh to port 2222. Ephemeral boots a copy, so test runs don't
# change the built image.
# 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
RAM=8G
CPUs=4
RAM=4G
RuntimeSize=40G
RuntimeNetwork=none
QemuArgs=-serial chardev:console -nic user,model=virtio-net-pci,hostfwd=tcp::2222-:22
Credentials=agent.password=test agent.hostname=agent-test mkosi.credentials/
Credentials=passwd.plaintext-password.root=root
KernelCommandLineExtra=systemd.firstboot=no
-6
View File
@@ -1,6 +0,0 @@
#!/bin/sh
# SSH key for mkosi vm
#
# mkosi vm runs this and passes what it prints as the credential agent.ssh-key
# (mkosi.conf), so you can ssh into the test VM with your own keys.
cat ~/.ssh/*.pub 2>/dev/null || true
+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
}
-5
View File
@@ -1,5 +0,0 @@
# 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
-5
View File
@@ -1,5 +0,0 @@
# 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
View File
Whitespace-only changes.
@@ -1,11 +0,0 @@
# 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
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
-6
View File
@@ -1,6 +0,0 @@
# 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
+2 -4
View File
@@ -1,5 +1,3 @@
# Kernel settings
#
# 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,14 +1,8 @@
# Network
#
# DHCP on the real network cards. Kind=!* skips virtual links such as those of
# containers.
# 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,23 +1,27 @@
# Enabled services
#
# mkosi runs systemctl preset-all, which applies this file. 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
enable sshd.service
# Fedora disables the login on the screen (tty1, and tty2-6 through its
# autovt@ alias).
# 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, and 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,17 +0,0 @@
# 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
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,25 +0,0 @@
# 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
After=systemd-tmpfiles-setup.service
Before=getty@%i.service serial-getty@%i.service
[Service]
Type=oneshot
ImportCredential=agent.*
ExecStart=/usr/libexec/agent-setup
StandardInput=tty
StandardOutput=tty
TTYPath=/dev/%I
TTYReset=yes
TTYVHangup=yes
# Being stopped by the other console is not a failure.
SuccessExitStatus=SIGTERM
[Install]
WantedBy=multi-user.target
@@ -1,12 +0,0 @@
# 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
[Path]
PathExists=/var/lib/agent/claude/.credentials.json
[Install]
WantedBy=multi-user.target
@@ -1,17 +0,0 @@
# 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
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,16 +0,0 @@
# 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,7 +0,0 @@
# 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
@@ -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,22 +0,0 @@
# 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
[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,20 +0,0 @@
# Root verity update
#
# Writes the dm-verity hashes that go with 10-root.transfer, which explains
# 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,27 +1,23 @@
# UKI update
#
# Installs the next UKI, which systemd-boot then boots by default. For
# Verify=yes, see 10-root.transfer.
# 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 root partition, because each UKI holds its root 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
@@ -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,5 +0,0 @@
# 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
+12 -14
View File
@@ -1,15 +1,13 @@
# Agent directories
#
# What survives a reboot and what doesn't. Claude can only write to the wiped
# directories, /tmp and its own config.
# 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
# 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): 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.
f /var/lib/systemd/linger/claude
# .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
-12
View File
@@ -1,12 +0,0 @@
#!/bin/bash
# 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)"
[[ -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 {} +
-45
View File
@@ -1,45 +0,0 @@
#!/bin/bash
# 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.
#
# With the credential agent.password, it asks nothing and takes the answers
# from the credentials agent.password, agent.hostname and agent.ssh-key. mkosi
# vm passes them (mkosi.conf).
set -euo pipefail
cred() { cat "${CREDENTIALS_DIRECTORY:-/nonexistent}/agent.$1" 2>/dev/null; }
if pw=$(cred password); then
# Both consoles run this script. Only one may do the setup.
exec 9>/run/agent-setup.lock
flock -n 9 || exit 0
name=$(cred hostname) || true
key=$(cred ssh-key) || true
else
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
read -rp "Hostname [agent]: " name
read -rp "SSH public key for the user claude: " key
fi
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
[[ -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 -3
View File
@@ -1,6 +1,5 @@
# EFI system partition
#
# Holds 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
-19
View File
@@ -1,19 +0,0 @@
# 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
Format=erofs
Compression=zstd
CopyFiles=/
ExcludeFilesTarget=/var/
Verity=data
VerityMatchKey=root
SizeMinBytes=1G
SizeMaxBytes=1G
# 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
+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
-11
View File
@@ -1,11 +0,0 @@
# Root verity, slot A
#
# The dm-verity hashes of the root filesystem in 10-root.conf.
[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
-9
View File
@@ -1,9 +0,0 @@
# Root filesystem, slot B
#
# Empty until systemd-sysupdate writes the next version to it.
[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=-
-9
View File
@@ -1,9 +0,0 @@
# Root verity, slot B
#
# The dm-verity hashes for 20-root-b.conf, empty until the next update.
[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=-
-13
View File
@@ -1,13 +0,0 @@
# 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
Format=ext4
CopyFiles=/var:/
Minimize=guess
SplitName=-
@@ -1,8 +1,5 @@
# Claude Code repository
#
# 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.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 -7
View File
@@ -1,7 +1,8 @@
#!/bin/sh
# Image version
#
# 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
#!/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"