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

# celesto image

> Manage sandbox images with celesto image: download images ahead of time, clean up the cache, move images between machines, and build from a Dockerfile.

The `celesto image` command group is a Docker-style toolbelt for the images that sandboxes boot from. Use it to:

* **Pre-download** an image so the first `celesto sandbox create` finishes instantly (CI warm-up, air-gapped setup, flaky network).
* **Keep the cache tidy** — see what is on disk, inspect a single entry, remove a specific image, or drop stale caches left behind by older releases.
* **Move images between machines** — pack an image into a single archive on one host and unpack it on another.
* **Build your own** custom rootfs from a Dockerfile without writing Python.

By default Celesto downloads images lazily the first time a sandbox needs them and stores them under `~/.celesto/images/`. Everything in this group operates on that directory.

## Synopsis

```bash theme={null} theme={null}
celesto image pull [IMAGE] [--all] [OPTIONS]
celesto image list [OPTIONS]
celesto image ls [OPTIONS]              # alias of `image list`
celesto images [OPTIONS]                # top-level alias of `image list`
celesto image inspect NAME [OPTIONS]
celesto image rm NAME [OPTIONS]
celesto image build -t NAME [PATH] [OPTIONS]
celesto image save NAME -o FILE [OPTIONS]
celesto image load -i FILE [OPTIONS]
celesto image prune [OPTIONS]
```

Every subcommand accepts:

* `--image-dir PATH` — override the cache location for this invocation.
* `--json` — emit a machine-readable envelope instead of the formatted output.

## Where images live

Resolution order for the cache directory (first match wins):

1. `--image-dir PATH` on the command you are running.
2. The `CELESTO_IMAGE_DIR` environment variable.
3. The default: `~/.celesto/images/`.

> [!NOTE]
>
> Sandboxes read only `CELESTO_IMAGE_DIR` — the `--image-dir` flag is a per-command override for `celesto image ...` itself. If you pull to a non-default directory and want `celesto sandbox create` to boot from that same directory, export `CELESTO_IMAGE_DIR` before starting the sandbox:
>
> ```bash theme={null} theme={null}
> export CELESTO_IMAGE_DIR=/data/celesto-images
> celesto image pull ubuntu
> celesto sandbox create
> ```

## Subcommands

### pull

Download a published image (kernel + rootfs, verified and decompressed) ahead of time.

```bash theme={null} theme={null}
celesto image pull ubuntu
celesto image pull --all
```

**image** `string`

Published image to fetch: `ubuntu` or `linux-desktop`. Required unless `--all` is set.

**--all** `flag`

Download every image published for this machine's architecture and VMM. Failures for individual images are isolated so one bad download doesn't cancel the batch. Combine with `--os` to limit to a single operating system.

**--arch** `"amd64" | "arm64"`

Processor architecture. Defaults to this machine's.

**--vmm** `"firecracker" | "qemu" | "libkrun"`

Virtual machine engine the image targets. Defaults to what this host uses.

**--os** `"ubuntu" | "alpine"`

Operating system inside the image. For a single pull the default is `ubuntu`; with `--all`, this limits the batch to one OS.

**--image-dir** `path`

Cache location for this pull. Overrides `CELESTO_IMAGE_DIR` and the default.

**--json** `flag`

Emit a JSON envelope with the resolved target, output path, and cache-hit flag.

Preview and warm-up patterns:

```bash theme={null} theme={null}
# CI: pre-download the image the build will use
celesto image pull ubuntu

# Air-gapped prep: fetch every image for this host in one go
celesto image pull --all --os ubuntu
```

### list / ls / images

Show every entry in the cache with its kind, platform, version (stale versions are flagged), age, and size. `celesto images` and `celesto image ls` are aliases of `celesto image list` — same output, same JSON envelope.

```bash theme={null} theme={null}
celesto images
```

Example output:

```
NAME                                  KIND     PLATFORM                   VERSION   CREATED         SIZE
ubuntu-v0.1.11-amd64-firecracker      image    amd64/firecracker/ubuntu   0.1.11    2 hours ago     1.1 GiB
base-kernel-v0.1.11-amd64             kernel   amd64                      0.1.11    2 hours ago     34 MiB
```

Sizes are computed from allocated blocks, so sparse rootfs files report what deleting them will actually free.

### inspect

Print a Docker-style JSON array describing one image: parsed fields, per-file sizes (both apparent and on-disk), the rootfs sidecar, and — for current-version published entries — the manifest URLs, SHAs, and release tag.

```bash theme={null} theme={null}
celesto image inspect ubuntu
celesto image inspect custom/my-agent
```

**name** `string` *required*

Published image name such as `ubuntu` (matches every cached entry for that image), full cache directory name (as shown by `image list`), or a custom image's `custom/<name>` handle. Absolute paths that `image list` prints are also accepted.

### rm

Remove a downloaded image to free space. Deletion is confined to direct children of the resolved image directory — symlinks are unlinked in place and never followed.

```bash theme={null} theme={null}
celesto image rm ubuntu                       # every ubuntu entry
celesto image rm ubuntu-v0.1.11-amd64-firecracker
celesto image rm custom/my-agent
celesto image rm custom/my-agent/9c1e4a2f     # one build
```

**name** `string` *required*

Published image name, full cache directory name, or `custom/<name>[/<fingerprint>]` handle. Fingerprints accept Docker-style unique prefixes.

**--dry-run** `flag`

List what would be removed without deleting.

### build

Build a custom rootfs from a Dockerfile, exposing the same pipeline as [`DockerRootfsBuilder`](https://celesto.ai/docs/celesto/api/dockerrootfsbuilder) as a CLI. Requires Docker on the host. The built image lands in the cache as `custom/<name>/<fingerprint>` and shows up in `image list` alongside published images.

```bash theme={null} theme={null}
celesto image build -t my-agent .
celesto image build -t my-agent \
  -f ./docker/Dockerfile.agent \
  --build-arg MODEL=gpt-4.1 \
  --size-mb 1024 \
  ./context
```

**path** `path` (default: .)

Docker build context. Defaults to the current directory. A missing context is a clean error.

**-t, --tag** `string` *required*

Name for the built image. Written under `custom/<name>/...` in the cache.

**-f, --file** `path`

Path to the Dockerfile. Defaults to `Dockerfile` in the context.

**--size-mb** `integer` (default: 512)

Virtual disk size of the built rootfs, in MiB.

**--build-arg** `KEY=VALUE`

Value forwarded to the Dockerfile's `ARG` lines. Repeat for multiple args.

**--arch** `"amd64" | "arm64"`

Target processor architecture. Defaults to this machine's.

**--backend** `"auto" | "firecracker" | "qemu" | "libkrun"` (default: auto)

Boot backend the resulting image will target.

**--init** `string` (default: /init)

First program the guest starts.

> [!NOTE]
>
> Because the CLI cannot boot local Linux images directly yet, a successful `image build` prints a ready-to-run `Celesto.from_image(...)` snippet you can drop into Python.

### save / load

Move an image between hosts without going through the network. `save` packs a cached entry into a tar archive; `load` unpacks the archive back into a target cache. Useful for air-gapped installs, on-call laptops, or copying a `custom/<name>` build to a peer's machine.

```bash theme={null} theme={null}
# on the source host
celesto image save ubuntu -o ubuntu.tar

# copy ubuntu.tar to the destination host (scp, rsync, USB stick), then:
celesto image load -i ubuntu.tar
```

The archive carries a `manifest.json` describing every member. Load stages into a hidden `.partial` directory and renames atomically; malicious archives (traversal, absolute paths, undeclared members, unsupported schema versions) are rejected before anything reaches the cache. Use `--force` on `load` to replace an existing entry.

### prune

Remove image caches left behind by older Celesto releases. This is the canonical home for prune; `celesto prune` at the top level is kept as an alias with the same implementation and flags. See [`celesto prune`](https://celesto.ai/docs/celesto/cli/prune) for the full reference and dry-run examples.

```bash theme={null} theme={null}
celesto image prune --dry-run
celesto image prune
```

## Choosing `CELESTO_IMAGE_DIR` vs. `--image-dir`

* Set **`CELESTO_IMAGE_DIR`** when the whole host — including sandboxes started later — should read and write from a shared directory (a large data volume, a shared NFS mount for a fleet, or a per-user override on a multi-tenant box). This is the only variable sandboxes themselves consult.
* Pass **`--image-dir`** when you only want the current `celesto image ...` command to touch a specific directory (inspecting a peer's cache, saving from a scratch location, loading into a test directory) without changing what future sandboxes see.

If you `pull` into a directory that isn't reachable via `CELESTO_IMAGE_DIR`, the command warns you — the sandbox that boots afterward will fall back to the default location.

## Exit codes

| Code | Description |
| - | - |
| `0` | Success |
| `1` | Runtime error (download failed, disk full, corrupt archive, partial batch) |
| `2` | Invalid usage (missing subcommand, conflicting flags, unknown image) |

## Related

* [`celesto prune`](https://celesto.ai/docs/celesto/cli/prune) — top-level alias of `celesto image prune`.
* [`ImageBuilder`](https://celesto.ai/docs/celesto/api/imagebuilder) and [`DockerRootfsBuilder`](https://celesto.ai/docs/celesto/api/dockerrootfsbuilder) — the Python builders behind `celesto image build`.
* [`ImageManager`](https://celesto.ai/docs/celesto/api/imagemanager) — the loader sandboxes use to resolve entries in the cache.


## Related topics

- [Published images](https://celesto.ai/docs/celesto/concepts/published-images.md)
- [celesto prune](https://celesto.ai/docs/celesto/cli/prune.md)
- [celesto sandbox prune](https://celesto.ai/docs/celesto/cli/sandbox-prune.md)
- [Custom Sandbox Images with Docker](https://celesto.ai/docs/celesto/guides/custom-images.md)
- [Snapshot and restore Celesto sandboxes](https://celesto.ai/docs/celesto/features/snapshots.md)


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