> ## 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.

# DockerRootfsBuilder

> DockerRootfsBuilder reference: build and cache raw ext4 root filesystems from Dockerfiles and return BootImage metadata for Celesto.from_image.

Use `DockerRootfsBuilder` when you want a Dockerfile to be the source of truth for a custom Celesto image. It builds a raw ext4 root filesystem, caches it by build inputs, and returns a [`BootImage`](https://celesto.ai/docs/celesto/api/bootimage).

> [!WARNING]
>
> `DockerRootfsBuilder` does not install SSH or the Celesto guest agent. Add your own guest control service, or use `ImageBuilder` when you need `vm.run(...)` immediately.

## Constructor

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

builder = DockerRootfsBuilder(
    name="worker-rootfs",
    dockerfile="""
        FROM alpine:3.20
        RUN apk add --no-cache python3
        COPY init /init
        RUN chmod +x /init
    """,
    context={"init": "#!/bin/sh\nwhile true; do sleep 3600; done\n"},
    rootfs_size_mb=512,
)
```

**name** `str` *required*

Cache directory name. Letters, numbers, `.`, `_`, and `-` are allowed.

**dockerfile** `str` *required*

Dockerfile text. Blank Dockerfiles are rejected.

**context** `dict[str, Path | str | bytes] | None` (default: None)

Files to copy into the temporary Docker build context. Keys must be safe relative paths.

**rootfs\_size\_mb** `int` (default: 512)

Size of the generated raw ext4 root filesystem. Must be greater than `0`.

**cache\_dir** `Path | None` (default: \~/.celesto/images/)

Cache root for built custom images.

**fingerprint\_inputs** `dict[str, Any] | None` (default: None)

Extra JSON-serializable values mixed into the cache key.

**build\_args** `dict[str, str] | None` (default: None)

Docker build arguments passed as `--build-arg`.

**docker\_platform** `str | None` (default: None)

Docker target platform override. When omitted, Celesto selects `linux/amd64` or `linux/arm64` from the requested architecture.

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

Whether the image starts SSH and accepts the credentials you pass to Celesto.

## ensure

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

image = builder.ensure(
    backend="qemu",
    arch="host",
    boot=DirectKernelBoot(root="/dev/vda", init="/init"),
)

with Celesto.from_image(image, memory_mb=1024) as vm:
    print(vm.vm_id)
```

**backend** `str` *required*

Backend to prepare the image for. Public docs focus on `"firecracker"` and `"qemu"`.

**arch** `Literal["host", "amd64", "arm64", "x86_64", "aarch64"] | str` (default: host)

Guest architecture. Use `"host"` to match the current machine.

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

Boot profile to render later for the selected backend.

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

Explicit kernel boot arguments. Mutually exclusive with `boot`.

**return** `BootImage`

A `BootImage` with `rootfs_format="raw-ext4"`, the built rootfs path, the matching Celesto base kernel, backend, arch, and `ssh_capable` flag.

## Cache behavior

The cache key includes the Dockerfile, build context, build args, target architecture, rootfs size, Docker platform, and `fingerprint_inputs`. It does not include the backend or kernel identity, so Firecracker and QEMU can reuse the same rootfs when the architecture matches.

## Context safety

`DockerRootfsBuilder` validates context paths before running Docker:

* Context keys must be relative paths.
* `..` traversal is rejected.
* A context entry named `Dockerfile` is reserved.
* Missing files passed as `Path` values raise an error before the build starts.

## Related

* [`celesto image build`](https://celesto.ai/docs/celesto/cli/image#build) — the same Dockerfile-to-rootfs pipeline exposed as a CLI command.
* [ImageBuilder](https://celesto.ai/docs/celesto/api/imagebuilder.md) — build Alpine or Debian rootfs images programmatically.


## Related topics

- [Custom Sandbox Images with Docker](https://celesto.ai/docs/celesto/guides/custom-images.md)
- [ImageBuilder](https://celesto.ai/docs/celesto/api/imagebuilder.md)
- [celesto image](https://celesto.ai/docs/celesto/cli/image.md)
- [Celesto Python class reference](https://celesto.ai/docs/celesto/api/celesto.md)
- [Troubleshooting guide](https://celesto.ai/docs/celesto/advanced/troubleshooting.md)


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