Boot from a custom image - sandkiln

The daemon’s default rootfs is whatever SANDKILN_BASE_ROOTFS is configured to. Registering your own image lets you boot from something else — your own tooling baked in, a pinned runtime version — without touching that daemon-wide default.

Register it

curl -X POST http://127.0.0.1:7777/images \
  -d '{"id": "node-lts-custom", "path": "/home/t1000/images/node-lts-custom.ext4"}'

from sandkiln import Image

Image.register("node-lts-custom", "/home/t1000/images/node-lts-custom.ext4")

kiln image create node-lts-custom /home/t1000/images/node-lts-custom.ext4

path is a path on the daemon’s own host filesystem — this isn’t a file upload. Build the image first (images/build-universal-image.sh is the reference build script for the project’s own universal image, adaptable for a custom one) and get it onto the daemon’s host before registering.

Verify the guest agent is actually there

The response includes "guest_agent_verified": false — always, by design, because the unprivileged daemon can’t loop-mount your image to check. Do this yourself before relying on it:

scripts/preflight-check.sh --root-checks --rootfs-image /home/t1000/images/node-lts-custom.ext4

Boot from it

const sandbox = await Sandbox.create({ imageId: "node-lts-custom" });

sandbox = Sandbox.create(image_id="node-lts-custom")

kiln sandbox create --image node-lts-custom

A nonexistent imageId fails fast with a 404, checked before the slow boot ever starts. See Custom & managed images for the full mechanics, including deletion and what’s genuinely not done yet (OCI/Docker conversion).