How it works

1. Boot layer. snowglobe adds a kernel, an initramfs that mounts the root filesystem over 9p, and BusyBox's init and getty with a terminal running your command, as files on top of your image's layers. Nothing runs in the image.
2. Filesystem. The flattened layers become a 9p filesystem: a JSON tree and one compressed blob per unique file, fetched on demand. Files of 2 MiB and more are split into content-defined chunks, so a read fetches only what it covers.
3. Snapshot. The guest boots headless until the app is ready, and the whole machine is saved. Visitors, snowglobe run, bundles and snowglobe mcp all restore it.
4. Machines. Natively, the snapshot's memory becomes an image the host maps copy-on-write into every instance, and a template restores once and forks a machine per command, per snowglobe up or per service replica, each sharing what it doesn't write.
5. Warm pack. The files read while booting and exercising are bundled into one download the page fetches in the background.

When a build goes wrong

• "the boot stalled". Nothing was printed, fetched or computed for 5 minutes before the app was ready. The build prints every CPU's state and boots once more; twice usually means the app waits for something that never comes, such as --ready text it never prints. SNOWGLOBE_BOOT_STALL_SECS changes the limit, and 0 turns it off.
• "not arm64". Build FROM alpine or arm64v8/alpine; on an x86 host, install QEMU's binfmt handlers first.
• A request answers 502. In a page, the server doesn't allow CORS. Under snowglobe run the same request goes out from your machine instead.
• A service doesn't start. There is no OpenRC: start it from the image's command.