Skip to main content
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.

​
Which presets are published

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.
The public CLI command for claude-code is celesto claude start.
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

1

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

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

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

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.

​
Kernel and rootfs formats

Celesto builds one kernel source tree into the formats each backend expects: 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.
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.

​
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.
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:

​
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:

​
Next steps

Runtime backends

See which backend uses each image format

Control channel

Learn how the guest agent speeds up commands

celesto prune

Reclaim disk from old caches

celesto ui

Start the dashboard
Last modified on September 7, 2026