> ## 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 SmolVM boots from pre-built sandbox images so smolvm claude start launches in seconds.

SmolVM 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 SmolVM downloads

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

* A SmolVM-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 SmolVM 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.06.24.0`. This tag is separate from the Python package version, so SmolVM 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  |
| `hermes`      | Hermes coding agent           |
| `pi`          | Pi coding agent               |
| `ubuntu`      | A clean Ubuntu base image     |

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

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

Each manifest row is keyed by preset, CPU architecture, backend, and guest operating system. If SmolVM 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="SmolVM resolves the target image">
    SmolVM 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="SmolVM downloads verified assets">
    Kernel and rootfs files come from the configured `images-YYYY.MM.DD.N` release tag. SmolVM verifies each file against the bundled SHA-256 checksum.
  </Step>

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

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

## Kernel and rootfs formats

SmolVM 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, SmolVM 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.06.24.0/
      arm64/
        smolvm-guest-agent-linux-arm64
```

<Note>
  If you set `SMOLVM_GUEST_AGENT_BINARY`, SmolVM 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 SmolVM package version.

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

  base-kernel-v0.0.24.post2-arm64/
    vmlinux.elf
    vmlinux.image
```

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

Run `smolvm prune` to remove old cached images:

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

## Opt out for image development

Set `SMOLVM_USE_PUBLISHED=0` when you want to test a local image build or preset install script:

```bash theme={null}
SMOLVM_USE_PUBLISHED=0 smolvm codex start
```

For everyday use, leave this unset so SmolVM can use the verified fast path.

## Dashboard UI assets

The dashboard has its own release asset named like `smolvm-dashboard-ui-<tag>.tar.gz`. The `smolvm ui` command downloads the newest stable dashboard asset into the local SmolVM 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}
smolvm 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="smolvm prune" icon="broom" href="/smolvm/cli/prune">
    Reclaim disk from old caches
  </Card>

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