> ## Documentation Index
> Fetch the complete documentation index at: https://sandkiln.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Boot from a custom image

> Register a rootfs and boot sandboxes from it.

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

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

```python register_image.py theme={null}
from sandkiln import Image

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

```bash CLI theme={null}
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:

```bash theme={null}
scripts/preflight-check.sh --root-checks --rootfs-image /home/t1000/images/node-lts-custom.ext4
```

## Boot from it

```ts boot.ts theme={null}
const sandbox = await Sandbox.create({ imageId: "node-lts-custom" });
```

```python boot.py theme={null}
sandbox = Sandbox.create(image_id="node-lts-custom")
```

```bash CLI theme={null}
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](/concepts/images) for the full mechanics, including deletion and what's genuinely not done yet (OCI/Docker conversion).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.