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 images 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 each published image
  • 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 images are published

Celesto 0.1.11 uses image release images-2026.10.25.0. Publishing an image does not automatically enable it in the CLI: each Celesto release pins the image release it reads.
Each manifest row is keyed by image name, 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 image name, 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/celesto-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 CELESTO_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 ~/.celesto/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 celesto-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 November 3, 2026