From frostyard-os
WHEN: Filesystem layout questions, package relocation, service enablement in immutable OS images. WHEN NOT: Standard Linux filesystem questions for mutable systems.
How this skill is triggered — by the user, by Claude, or both
Slash command
/frostyard-os:immutable-fsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guide to the immutable filesystem layout used by frostyard bootc images.
Guide to the immutable filesystem layout used by frostyard bootc images.
| Path | Access | Purpose | Notes |
|---|---|---|---|
/usr | Read-only | Binaries, libraries, system configs | All package contents must live here |
/etc | Overlay | System configuration | Overlay on /usr/etc. Base configs in image, user changes persist across boots. On OS update, new base configs merge — user-modified files are preserved (user layer wins) |
/var | Read-write | State, logs, container storage | Persistent across boots and updates |
/opt | Bind-mount | Third-party software | Bind-mount to /var/opt. Writable at runtime but shadowed by sysext overlays |
/home | Read-write | User data | Persistent |
/opt is a bind-mount to /var/opt, which means it's writable at runtime. However, sysext overlays can shadow /opt contents, causing conflicts. Packages that install to /opt must be relocated at build time.
# In a postinstall script (.chroot)
set -euo pipefail
# Move from /opt to /usr/lib
mv /opt/<package> /usr/lib/<package>
# Create symlinks for binaries
ln -sf /usr/lib/<package>/bin/<binary> /usr/bin/<binary>
This applies to both desktop images and sysexts. Common packages needing relocation: 1Password, some proprietary tools.
All binaries in the image must reside under /usr/bin or /usr/sbin. If installing from a tarball or custom build, place the binary directly in /usr/bin/.
systemctl --user enable does not work inside a mkosi chroot — there's no user session or D-Bus. System services work fine via systemctl enable, but user services require manual symlink creation:
# In a postinstall script
mkdir -p /etc/systemd/user/<target>.wants
ln -sf /usr/lib/systemd/user/<service> /etc/systemd/user/<target>.wants/<service>
The target (e.g., gnome-session.target) comes from the service's WantedBy= in its [Install] section.
deb-systemd-helper creates .dsh-also tracking files in /var/lib/systemd/deb-systemd-user-helper-enabled/ during the build but may not create the actual enablement symlinks in /etc/systemd/user/. If a user service isn't auto-starting after reboot:
/etc/systemd/user/<target>.wants/.dsh-also fileIf a package ships both types: system services (/usr/lib/systemd/system/) are enabled normally via systemctl enable in the chroot. User services require the manual symlink approach above. Handle them independently — system service enablement does not affect user services.
set -euo pipefail at the top of every script.chroot extension (e.g., snow.postinst.chroot).sh extensionverified_download() from shared/download/verified-download.shlatest or branch namesSysexts have additional constraints beyond the base image:
/usr/etc or /var at runtime/etc configs, use the factory pattern:
/usr/share/factory/etc/ during buildsystemd-tmpfiles C (copy) directive:
# /usr/lib/tmpfiles.d/myapp.conf
C /etc/myapp - - - - /usr/share/factory/etc/myapp
sysext-authoring skill for full detailsDuring a bootc update:
| Path | Behavior |
|---|---|
/usr | Replaced entirely with the new image |
/etc | User modifications preserved — new base defaults merge underneath |
/var | Untouched — fully persistent |
/home | Untouched — fully persistent |
Sysexts are updated independently via systemd-sysupdate.
npx claudepluginhub frostyard/frostyard-ai --plugin frostyard-osProvides Docker best practices for base image selection, Dockerfile layer optimization, multi-stage builds, and production container deployments.
Docker and Podman container management: Dockerfile optimization, multi-stage builds, Compose v2 orchestration, networking, volumes, security hardening, supply chain integrity, health checks, resource limits, Quadlet systemd integration, and debugging. Invoke whenever task involves any interaction with containers — writing Dockerfiles, configuring Compose, managing Podman Quadlets, reviewing container security, debugging container issues, or setting up image signing and scanning.
Creates reproducible, cross-platform (macOS/Linux) development environments with Flox. Use for project toolchains, system-level dependencies, and onboarding developers.