Skip to main content

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.

By default, SmolVM boots a minimal Alpine Linux image with SSH. If you need specific packages, libraries, or a different base OS, you can build a custom image using the ImageBuilder class. Custom images are built with Docker and cached locally so you only build once.

​
Quick start

from smolvm import SmolVM, VMConfig
from smolvm.build import ImageBuilder, SSH_BOOT_ARGS

builder = ImageBuilder()
kernel, rootfs = builder.build_alpine_ssh()

config = VMConfig(
    vm_id="my-custom-vm",
    vcpu_count=1,
    memory=512,
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args=SSH_BOOT_ARGS,
)

with SmolVM(config) as vm:
    result = vm.run("cat /etc/os-release")
    print(result.output)
ImageBuilder requires Docker to be installed and running. On macOS, use Docker Desktop. On Linux, install docker.io.

​
Build methods

SmolVM provides three image build methods. Each creates a Linux filesystem with SSH pre-configured and returns a (kernel_path, rootfs_path) tuple.

​
Alpine with SSH password

The simplest option — builds a minimal Alpine Linux image with root password authentication: 
kernel, rootfs = builder.build_alpine_ssh(
    name="my-alpine",           # Cache name (default: "alpine-ssh")
    ssh_password="mypassword",  # Root password (default: "smolvm")
    rootfs_size_mb=512,         # Disk size in MB (default: 512)
)
More secure — uses public key authentication instead of a password: 
from smolvm.utils import ensure_ssh_key

# Generate or load SSH keys
private_key, public_key = ensure_ssh_key()

kernel, rootfs = builder.build_alpine_ssh_key(
    ssh_public_key=public_key,
    name="alpine-key",
    rootfs_size_mb=512,
)

config = VMConfig(
    vm_id="key-vm",
    vcpu_count=1,
    memory=512,
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args=SSH_BOOT_ARGS,
)

with SmolVM(config, ssh_key_path=str(private_key)) as vm:
    result = vm.run("whoami")
    print(result.output)  # "root"

​
Debian with SSH key

For workloads that need apt, glibc, or broader package compatibility. Debian images are larger but more compatible:
Since v0.0.14, debian is no longer accepted by smolvm create --os or by auto-config. The build_debian_ssh_key method below remains available when you call ImageBuilder directly. For new projects, prefer the Ubuntu auto-config path or build on the Alpine/Ubuntu base.
from smolvm.utils import ensure_ssh_key

private_key, public_key = ensure_ssh_key()

kernel, rootfs = builder.build_debian_ssh_key(
    ssh_public_key=public_key,
    name="debian-key",
    rootfs_size_mb=2048,  # Debian needs more space
    base_image="debian:bookworm-slim",
)

config = VMConfig(
    vm_id="debian-vm",
    vcpu_count=2,
    memory=1024,
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args=SSH_BOOT_ARGS,
)

with SmolVM(config, ssh_key_path=str(private_key)) as vm:
    result = vm.run("cat /etc/debian_version")
    print(result.output)

​
Boot arguments

Use the SSH_BOOT_ARGS constant for any SSH-capable image: 
from smolvm.build import SSH_BOOT_ARGS

print(SSH_BOOT_ARGS)
# "console=ttyS0 reboot=k panic=1 pci=off root=/dev/vda rw init=/init"
The init=/init parameter is required for SmolVM’s SSH functionality. Without it, the custom init script will not run and SSH will not start.

​
Image caching

ImageBuilder caches built images to avoid rebuilding. The first build downloads base images and runs Docker. Subsequent calls with the same name return cached paths instantly: 
builder = ImageBuilder()

# First build — downloads and builds everything
kernel1, rootfs1 = builder.build_alpine_ssh(name="my-image")

# Second call — returns cached paths immediately
kernel2, rootfs2 = builder.build_alpine_ssh(name="my-image")
For key-based images, the cache is automatically invalidated if the SSH key is newer than the cached image.

​
Custom cache directory

from pathlib import Path

builder = ImageBuilder(cache_dir=Path("/mnt/fast-ssd/vm-images"))

kernel, rootfs = builder.build_alpine_ssh()
print(kernel)  # /mnt/fast-ssd/vm-images/alpine-ssh/vmlinux.bin
print(rootfs)  # /mnt/fast-ssd/vm-images/alpine-ssh/rootfs.ext4

​
The kernel SmolVM uses

Every image you build with ImageBuilder boots SmolVM’s own Linux 6.12.85 kernel. SmolVM builds it in CI from upstream Linux source and tunes it for sandbox workloads — it is the same kernel used by the published images so behavior stays consistent across hosts. You don’t need to pick a kernel or pass a URL. SmolVM downloads the universal kernel once and caches it under ~/.smolvm/images/<version>/.

​
How the init script works

All SSH-capable images include a custom /init script that runs as PID 1 inside the sandbox. This script:
  • Mounts essential filesystems (/proc, /sys, /dev, /tmp)
  • Configures networking from kernel boot arguments
  • Sets up DNS resolution (8.8.8.8)
  • Generates SSH host keys if missing
  • Starts the SSH daemon
  • Stays alive as PID 1 to keep the sandbox running
You do not need to modify this script for most use cases. It is included automatically when you use any ImageBuilder method.

​
Real-world example: OpenClaw

For day-to-day use, run smolvm openclaw start — it boots from a pre-built image in seconds and forwards your OPENROUTER_API_KEY and OPENCLAW_GATEWAY_TOKEN automatically. The example below shows the manual builder path, which is useful when you’re customizing the image.
This example from examples/openclaw.py builds a 4 GB Debian image for the OpenClaw application: 
import os
from smolvm import SmolVM, VMConfig
from smolvm.build import ImageBuilder, SSH_BOOT_ARGS
from smolvm.utils import ensure_ssh_key

private_key, public_key = ensure_ssh_key()

kernel, rootfs = ImageBuilder().build_debian_ssh_key(
    ssh_public_key=public_key,
    name="debian-ssh-key-openclaw-4g",
    rootfs_size_mb=4096,
)

config = VMConfig(
    vcpu_count=1,
    memory=2048,
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args=SSH_BOOT_ARGS,
    env_vars={
        "OPENROUTER_API_KEY": os.getenv("OPENROUTER_API_KEY", ""),
    },
)

with SmolVM(config, ssh_key_path=str(private_key)) as vm:
    vm.run("apt-get update && apt-get install -y nodejs npm")
    vm.run("npm install -g openclaw")

​
Troubleshooting

When an image build fails, SmolVM diagnoses the root cause and returns a specific error message. You do not need to debug Docker issues manually.
SmolVM raises an ImageError with install instructions:
  • macOS: Install Docker Desktop
  • Linux: sudo apt-get install docker.io (Debian/Ubuntu)
You can check Docker availability before building:
builder = ImageBuilder()
if not builder.check_docker():
    print(builder.docker_requirement_error())
Start the Docker service:
open -a Docker
Add your user to the docker group:
sudo usermod -aG docker $USER
newgrp docker  # or log out and back in
Image builds require sufficient disk space. Check available space and clean the Docker cache if needed:
df -h ~/.smolvm/images/
docker system prune -a

​
Next steps

Environment variables

Inject configuration into custom images

AI agent integration

Build specialized images for AI agent sandboxes

VM lifecycle

Manage sandboxes built with custom images
Last modified on May 7, 2026