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 createfinishes 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.
~/.celesto/images/. Everything in this group operates on that directory.
Synopsis
--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):--image-dir PATHon the command you are running.- The
CELESTO_IMAGE_DIRenvironment variable. - The default:
~/.celesto/images/.
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:Subcommands
pull
Download a published image (kernel + rootfs, verified and decompressed) ahead of time.string
Published image to fetch:
ubuntu or linux-desktop. Required unless --all is set.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."amd64" | "arm64"
Processor architecture. Defaults to this machine’s.
"firecracker" | "qemu" | "libkrun"
Virtual machine engine the image targets. Defaults to what this host uses.
"ubuntu" | "alpine"
Operating system inside the image. For a single pull the default is
ubuntu; with --all, this limits the batch to one OS.path
Cache location for this pull. Overrides
CELESTO_IMAGE_DIR and the default.flag
Emit a JSON envelope with the resolved target, output path, and cache-hit flag.
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.
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.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.string
required
Published image name, full cache directory name, or
custom/<name>[/<fingerprint>] handle. Fingerprints accept Docker-style unique prefixes.flag
List what would be removed without deleting.
build
Build a custom rootfs from a Dockerfile, exposing the same pipeline asDockerRootfsBuilder 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.
path
default:"."
Docker build context. Defaults to the current directory. A missing context is a clean error.
string
required
Name for the built image. Written under
custom/<name>/... in the cache.path
Path to the Dockerfile. Defaults to
Dockerfile in the context.integer
default:"512"
Virtual disk size of the built rootfs, in MiB.
KEY=VALUE
Value forwarded to the Dockerfile’s
ARG lines. Repeat for multiple args."amd64" | "arm64"
Target processor architecture. Defaults to this machine’s.
"auto" | "firecracker" | "qemu" | "libkrun"
default:"auto"
Boot backend the resulting image will target.
string
default:"/init"
First program the guest starts.
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.
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 for the full reference and dry-run examples.
Choosing CELESTO_IMAGE_DIR vs. --image-dir
- Set
CELESTO_IMAGE_DIRwhen 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-dirwhen you only want the currentcelesto 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.
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
Related
celesto prune— top-level alias ofcelesto image prune.ImageBuilderandDockerRootfsBuilder— the Python builders behindcelesto image build.ImageManager— the loader sandboxes use to resolve entries in the cache.