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

# BootImage and boot helpers

> BootImage, DirectKernelBoot, and FirmwareBoot reference for describing custom Celesto disk images and the kernel or firmware boot path the VM should use.

Use `BootImage` to tell Celesto which disk image to boot and how to boot it. It is a description only: Celesto creates the VM, networking, and per-VM disk later when you pass the image to [`Celesto.from_image()`](https://celesto.ai/docs/celesto/api/celesto#from_image).

## BootImage

```python theme={null}
from pathlib import Path

from celesto import BootImage, DirectKernelBoot

image = BootImage(
    name="alpine-tools",
    rootfs_path=Path("/var/images/alpine-tools.ext4"),
    rootfs_format="raw-ext4",
    boot=DirectKernelBoot(root="/dev/vda", init="/init"),
    backend="qemu",
    arch="amd64",
)
```

**name** `str` *required*

Human-readable image name. Blank names are rejected.

**rootfs\_path** `Path` *required*

Path to the root filesystem disk image. The file must exist.

**rootfs\_format** `Literal["raw-ext4", "qcow2"]` *required*

Disk image format. Use `"raw-ext4"` for raw ext4 filesystems and `"qcow2"` for QEMU qcow2 disks.

**kernel\_path** `Path | None` (default: None)

Kernel image path for direct-kernel boot. Direct-kernel images may omit this; `Celesto.from_image(...)` resolves Celesto's cached base kernel for the selected backend.

**initrd\_path** `Path | None` (default: None)

Optional initrd image path for direct-kernel boot.

**boot** `DirectKernelBoot | FirmwareBoot | None` (default: None)

Boot helper. Use `DirectKernelBoot` for Linux images loaded with `-kernel`, or `FirmwareBoot` for QEMU images that boot through firmware.

**boot\_args** `str | None` (default: None)

Explicit kernel command line for direct-kernel images. Mutually exclusive with `boot`.

**backend** `Literal["firecracker", "qemu", "libkrun"] | None` (default: None)

Backend this image is built for. Public docs focus on Firecracker and QEMU; `libkrun` is accepted by the source but is less documented.

**arch** `Literal["amd64", "arm64"] | None` (default: None)

Guest CPU architecture. Leave unset when `Celesto.from_image(...)` should use the host architecture.

**ssh\_capable** `bool` (default: False)

Whether the image starts SSH and accepts the credentials you pass to Celesto. Set this to `True` only when command helpers such as `vm.run(...)` can connect.

## Validation rules

`BootImage` validates the boot contract before you launch:

* Artifact paths must exist and point to files.
* Direct-kernel images need either `boot` or `boot_args`.
* `boot` and `boot_args` are mutually exclusive.
* Firmware images must use `backend="qemu"` when a backend is set.
* Firmware images must not set `kernel_path`, `initrd_path`, or `boot_args`.

## Properties and methods

**boot\_mode** `Literal["direct_kernel", "firmware"]`

VM boot mode inferred from the boot helper.

```python theme={null}
print(image.boot_mode)
print(image.render_boot_args(backend="qemu", arch="amd64"))
```

**render\_boot\_args(backend, arch)** `method`

Returns the kernel command line for direct-kernel images. Firmware images return an empty string because their boot arguments live inside the disk image.

## DirectKernelBoot

Use `DirectKernelBoot` when Celesto should load a Linux kernel directly.

```python theme={null}
from celesto import DirectKernelBoot

boot = DirectKernelBoot(
    root="/dev/vda",
    init="/init",
    quiet=False,
    extra_args=("acpi=off",),
)

print(boot.render(backend="qemu", arch="host"))
```

**root** `str` (default: /dev/vda)

Root device passed to the kernel.

**init** `str | None` (default: /init)

Init program path. Set `None` when the image should use its default init.

**rw** `bool` (default: True)

Mount the root filesystem read-write. When `False`, renders `ro`.

**console** `Literal["serial", "none"]` (default: serial)

Serial console setting. QEMU on arm64 uses `ttyAMA0`; other documented paths use `ttyS0`.

**panic** `int` (default: 1)

Kernel panic reboot delay.

**reboot** `str` (default: k)

Kernel reboot mode.

**safe\_trims** `bool` (default: True)

Add Celesto's safe boot defaults such as `tsc=reliable` and `no_timer_check`.

**quiet** `bool | None` (default: None)

Controls the `quiet` boot flag. Leave unset for the default behavior, or set `CELESTO_VERBOSE_BOOT=1` to drop `quiet` while debugging.

**extra\_args** `tuple[str, ...]` (default: ())

Extra kernel arguments. Each entry must be one token with no spaces.

## FirmwareBoot

Use `FirmwareBoot` for QEMU images that already contain their own bootloader, such as cloud images or Windows qcow2 disks.

```python theme={null}
from pathlib import Path

from celesto import BootImage, FirmwareBoot

image = BootImage(
    name="ubuntu-cloud",
    rootfs_path=Path("/var/images/ubuntu.qcow2"),
    rootfs_format="qcow2",
    boot=FirmwareBoot(),
    backend="qemu",
)
```

> [!NOTE]
>
> Firmware images boot through QEMU firmware. They do not use `kernel_path`, `initrd_path`, or `boot_args`.


## Related topics

- [Custom Sandbox Images with Docker](https://celesto.ai/docs/celesto/guides/custom-images.md)
- [celesto windows](https://celesto.ai/docs/celesto/cli/windows.md)
- [ImageBuilder](https://celesto.ai/docs/celesto/api/imagebuilder.md)
- [Celesto Python class reference](https://celesto.ai/docs/celesto/api/celesto.md)
- [DockerRootfsBuilder](https://celesto.ai/docs/celesto/api/dockerrootfsbuilder.md)


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