ImageManager

ImageManager handles fetching and caching VM images from remote sources. It provides atomic downloads with SHA-256 verification to ensure image integrity.

Constructor

`ImageManager(cache_dir=None, registry=None)`

Initialize the image manager.

Path | None

default:"~/.smolvm/images/"

Override the default cache directory. If not specified, images are cached in ~/.smolvm/images/.

dict[str, ImageSource] | None

default:"BUILTIN_IMAGES"

Override the built-in image registry. Useful for testing or adding custom images. If not specified, uses the built-in registry.

from smolvm import ImageManager
from pathlib import Path

# Use default settings
manager = ImageManager()

# Custom cache directory
manager = ImageManager(cache_dir=Path("/var/cache/smolvm"))

Methods

`list_available()`

List names of all registered images.

list[str]

Sorted list of image names available in the registry.

manager = ImageManager()
available = manager.list_available()
print(f"Available images: {', '.join(available)}")
# Output: Available images: hello, quickstart-x86_64

`is_cached(name)`

Check if an image is fully cached locally.

str

required

Image name to check.

bool

True if both kernel and rootfs files exist in the cache, False otherwise.

Raises:

ValueError - If image name is empty

manager = ImageManager()

if manager.is_cached("hello"):
    print("Image already cached")
else:
    print("Need to download image")

`ensure_image(name)`

Ensure an image is available locally, downloading if necessary. If the image is already cached and passes SHA-256 verification, it is returned immediately. Otherwise, it is downloaded from the registry. Downloads are atomic: files are written to a temporary location, SHA-256 verified, then renamed into place. This ensures a partial download never corrupts the cache.

str

required

Image name from the registry.

LocalImage

LocalImage instance with paths to kernel and rootfs.

Raises:

ValueError - If image name is empty
ImageError - If the image is not in the registry, download fails, or checksum verification fails

from smolvm import ImageManager, SmolVM, VMConfig

manager = ImageManager()

# Download or retrieve cached image
image = manager.ensure_image("hello")
print(f"Kernel: {image.kernel_path}")
print(f"Rootfs: {image.rootfs_path}")

# Use the image with SmolVM
config = VMConfig(
    kernel_path=image.kernel_path,
    rootfs_path=image.rootfs_path,
)

with SmolVM(config) as vm:
    vm.start()
    # VM is now running with the "hello" image

Built-in Image Registry

SmolVM includes a registry of pre-built images from Firecracker’s official sources:

`hello`

Minimal “hello world” image for testing.

Kernel: hello-vmlinux.bin
Rootfs: hello-rootfs.ext4
Size: ~10MB total
Use case: Quick tests, examples

`quickstart-x86_64`

Ubuntu Bionic (18.04) image for x86_64 architecture.

Kernel: vmlinux.bin
Rootfs: bionic.rootfs.ext4
Size: ~100MB total
Use case: General purpose Linux environment

Custom Image Registry

You can define custom images by providing your own registry:

from smolvm import ImageManager, ImageSource

custom_registry = {
    "my-custom-image": ImageSource(
        name="my-custom-image",
        kernel_url="https://example.com/vmlinux.bin",
        kernel_sha256="abc123...",
        rootfs_url="https://example.com/rootfs.ext4",
        rootfs_sha256="def456...",
    ),
}

manager = ImageManager(registry=custom_registry)
image = manager.ensure_image("my-custom-image")

Cache Behavior

The image manager implements smart caching:

Cache hit: If both kernel and rootfs exist and pass SHA-256 verification, they are used immediately
Cache miss: If files don’t exist, they are downloaded
Checksum mismatch: If cached files fail verification, they are re-downloaded
Atomic writes: Downloads write to temporary files and rename on success, preventing corruption

manager = ImageManager()

# First call: downloads image
image1 = manager.ensure_image("hello")
print("Downloaded image")

# Second call: uses cache (instant)
image2 = manager.ensure_image("hello")
print("Used cached image")

assert image1.kernel_path == image2.kernel_path
assert image1.rootfs_path == image2.rootfs_path

Error Handling

from smolvm import ImageManager
from smolvm.exceptions import ImageError

manager = ImageManager()

try:
    image = manager.ensure_image("nonexistent")
except ImageError as e:
    print(f"Error: {e}")
    # Error: Unknown image: 'nonexistent'. Available images: hello, quickstart-x86_64

ImageSource - Define downloadable image metadata
LocalImage - Locally-cached image representation
ImageBuilder - Build custom images with SSH

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Constructor

`ImageManager(cache_dir=None, registry=None)`

Methods

`list_available()`

`is_cached(name)`

`ensure_image(name)`

Built-in Image Registry

`hello`

`quickstart-x86_64`

Custom Image Registry

Cache Behavior

Error Handling

​Constructor

​ImageManager(cache_dir=None, registry=None)

​Methods

​list_available()

​is_cached(name)

​ensure_image(name)

​Built-in Image Registry

​hello

​quickstart-x86_64

​Custom Image Registry

​Cache Behavior

​Error Handling

​Related

Constructor

`ImageManager(cache_dir=None, registry=None)`

Methods

`list_available()`

`is_cached(name)`

`ensure_image(name)`

Built-in Image Registry

`hello`

`quickstart-x86_64`

Custom Image Registry

Cache Behavior

Error Handling

Related