No description
- Go 89.5%
- Shell 10.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
e53b14224c
The /.overlay directory must be a tmpfs mountpoint BEFORE res-os-overlay creates the btrfs mount under it. Otherwise the upperdir path traverses through / (the lowerdir), causing overlayfs self-reference and breaking file execution (can't execute /bin/login). |
||
| .forgejo/workflows | ||
| .opencode | ||
| cmd | ||
| internal | ||
| overlay/etc | ||
| .editorconfig | ||
| .gitattributes | ||
| .gitignore | ||
| Dockerfile.ResOS | ||
| go.mod | ||
| README.md | ||
| residual-overview.md | ||
residual/os
Build tooling for the residual OS. Currently hosts res-os-builder, a
container-native tool that turns OCI/container rootfs images into bootable
artifacts — fully unprivileged, runnable on standard CI runners.
Layout
Dockerfile.ResOS— the default OS image (build context is the repo root).overlay/— rootfs overwrite filesCOPYed onto the image.cmd/res-os-builder/— the Go CLI. See its README for pipeline docs, usage, and size goals.cmd/res-os-overlay/+internal/overlay/— the persistence overlay locator baked into the image (no host Go toolchain needed to build it).internal/— Go internals (build pipeline, exec helpers).
Quick start
# Build the tool
go build -o res-os-builder ./cmd/res-os-builder
# Build the OS image (repo root is the context)
docker build -f Dockerfile.ResOS -t residual:alpine .
# Full pipeline: Dockerfile → rootfs → initramfs → bootable image
./res-os-builder build --from-dockerfile Dockerfile.ResOS --output residual.img
# Boot test (QEMU)
qemu-system-x86_64 -kernel ~/res-rootfs/boot/vmlinuz-lts \
-initrd ~/res-initramfs.gz -m 1024 -nographic -no-reboot \
-append "console=ttyS0,115200" 2>&1 | grep RESIDUAL-POC
See residual/.agent#27 for the design.