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

# Published images

> How Celesto boots from pre-built sandbox images so celesto claude start launches in seconds.

Celesto can start from ready-made sandbox images instead of building an operating system image on your machine. This makes the first launch faster and keeps common presets consistent across hosts.

## What Celesto downloads

Published images are release assets on the Celesto GitHub repository. They include:

* A Celesto-built Linux kernel in the format the selected backend needs
* A compressed root filesystem for a preset or base operating system
* SHA-256 checksums that Celesto verifies before boot
* A pinned Rust guest-agent binary for custom image builds from installed wheels

The image release tag uses a date-based format such as `images-2026.09.07.0`. This tag is separate from the Python package version, so Celesto can publish rebuilt images without pretending the Python API changed.

<Tooltip tip="CalVer means calendar versioning. The version includes the release date, which makes image rebuilds easier to track.">
  CalVer
</Tooltip>

## Which presets are published

| Preset        | What it gives you             |
| ------------- | ----------------------------- |
| `codex`       | OpenAI Codex CLI in a sandbox |
| `claude-code` | Claude Code CLI in a sandbox  |
| `openclaw`    | OpenClaw gateway and runtime  |
| `opencode`    | OpenCode coding agent         |
| `hermes`      | Hermes coding agent           |
| `pi`          | Pi coding agent               |
| `ubuntu`      | A clean Ubuntu base image     |

<Note>
  Celesto v0.0.31 uses image release `images-2026.09.07.0`. Publishing an image does not automatically enable it in the CLI: OpenClaw still installs Node.js and OpenClaw inside each new sandbox, and OpenCode images are not yet selected by this release. Allow several minutes for OpenClaw setup.
</Note>

The public CLI command for `claude-code` is `celesto claude start`.

```bash theme={null}
celesto codex start
celesto claude start
celesto sandbox create --os ubuntu
```

Each manifest row is keyed by preset, CPU architecture, backend, and guest operating system. If Celesto does not find a matching row, it uses the slower build or install path for that launch.

## How a published launch works

<Steps>
  <Step title="Celesto resolves the target image">
    Celesto combines the preset, host architecture, backend, and requested guest operating system. For example, a Linux Firecracker launch and a macOS QEMU launch can use different kernel artifacts.
  </Step>

  <Step title="Celesto downloads verified assets">
    Kernel and rootfs files come from the configured `images-YYYY.MM.DD.N` release tag. Celesto verifies each file against the bundled SHA-256 checksum.
  </Step>

  <Step title="Celesto decompresses the rootfs once">
    Compressed `.zst` files stay in the cache. Celesto creates a sibling `rootfs.ext4` file and stores a sidecar checksum so it knows when to refresh the decompressed copy.
  </Step>

  <Step title="Celesto injects your access key at launch">
    Published images do not bake in your SSH key. Celesto passes your public key at launch so the same image can be shared safely across users.
  </Step>
</Steps>

## Kernel and rootfs formats

Celesto builds one kernel source tree into the formats each backend expects:

| Backend     | Kernel format                |
| ----------- | ---------------------------- |
| Firecracker | `vmlinux.<arch>.elf`         |
| QEMU        | `vmlinux.<arch>.image`       |
| libkrun     | ELF on Linux, Image on macOS |

The rootfs is a Linux filesystem image. Published rootfs files are compressed as `.ext4.zst` and decompressed locally before boot.

## Guest agent pins

Recent images include `/usr/local/bin/smolvm-guest-agent`. The agent starts before networking and powers the fast vsock control channel for commands, file transfer, shell streams, and guest sync.

When you build images from an installed Python wheel instead of a source checkout, Celesto downloads the pinned guest-agent binary from the same image release tag and verifies its SHA-256 checksum.

```text theme={null}
~/.smolvm/images/
  _guest-agent/
    images-2026.09.07.0/
      arm64/
        smolvm-guest-agent-linux-arm64
```

<Note>
  If you set `SMOLVM_GUEST_AGENT_BINARY`, Celesto uses that local binary for image builds. The binary must be a static Linux binary for the guest architecture.
</Note>

## Cache layout

Published images live under `~/.smolvm/images/`. The release URLs use the CalVer image tag, while the local cache directory includes the Celesto package version.

```text theme={null}
~/.smolvm/images/
  codex-v0.0.31-arm64-qemu/
    kernel
    rootfs.ext4.zst
    rootfs.ext4
    rootfs.ext4.from-sha256

  base-kernel-v0.0.31-arm64/
    vmlinux.elf
    vmlinux.image
```

The `.from-sha256` sidecar records which compressed rootfs produced the decompressed `rootfs.ext4`. If the manifest checksum changes, Celesto refreshes the decompressed file.

Run `celesto prune` to remove old cached images:

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

## Dashboard UI assets

The dashboard has its own release asset named like `smolvm-dashboard-ui-<tag>.tar.gz`. The `celesto ui` command downloads the newest stable dashboard asset into the local Celesto data directory when the installed package does not already include a built UI.

Use beta dashboard assets only when you want prerelease UI changes:

```bash theme={null}
celesto ui --allow-beta
```

## Next steps

<CardGroup cols={2}>
  <Card title="Runtime backends" icon="microchip" href="/smolvm/concepts/backends">
    See which backend uses each image format
  </Card>

  <Card title="Control channel" icon="plug" href="/smolvm/concepts/control-channel">
    Learn how the guest agent speeds up commands
  </Card>

  <Card title="celesto prune" icon="broom" href="/smolvm/cli/prune">
    Reclaim disk from old caches
  </Card>

  <Card title="celesto ui" icon="desktop" href="/smolvm/cli/ui">
    Start the dashboard
  </Card>
</CardGroup>


## Related topics

- [celesto image](/smolvm/cli/image.md)
- [Control channel](/smolvm/concepts/control-channel.md)
- [Security model](/smolvm/concepts/security.md)
- [Performance benchmarks](/smolvm/advanced/performance.md)
- [Coding Agents in Sandbox](/smolvm/features/coding-agents.md)