Basic usage

This page covers the everyday operations you need to work with SmolVM: creating a sandbox, running commands inside it, reading the output, and handling errors. If you have not installed SmolVM yet, start with the quickstart.

Quick start

The simplest way to use SmolVM is the auto-configuration mode:

from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("uname -r")
    print(result.stdout)

When you create a SmolVM() with no arguments, it automatically:

Generates SSH keys (stored in ~/.smolvm/keys/)
Builds an Alpine Linux image with SSH pre-configured
Creates a VM with sensible defaults (512MB RAM, 1 vCPU)
Starts the VM when entering the context manager

Creating a sandbox

You can create a sandbox with sensible defaults or customize the configuration.

Auto-config (Recommended)
Manual Configuration

from smolvm import SmolVM

# Minimal configuration
with SmolVM() as vm:
    print(f"VM running at {vm.get_ip()}")

# Custom memory and disk size
with SmolVM(memory=1024, disk_size=1024) as vm:
    print(f"VM ID: {vm.vm_id}")

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

# Build custom image
builder = ImageBuilder()
kernel, rootfs = builder.build_alpine_ssh()

# Create VM with explicit config
config = VMConfig(
    vm_id="my-vm",
    vcpu_count=2,
    memory=1024,
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args=SSH_BOOT_ARGS,
)

with SmolVM(config) as vm:
    result = vm.run("echo 'Hello from SmolVM'")
    print(result.output)

Running commands

The run() method executes commands via SSH and returns a CommandResult object:

from smolvm import SmolVM

with SmolVM() as vm:
    # Basic command execution
    result = vm.run("ls -la /")
    print(result.stdout)  # Command output
    print(result.exit_code)  # Exit status (0 = success)
    print(result.ok)  # True if exit_code == 0

    # Commands with custom timeout
    result = vm.run("sleep 10", timeout=60)

    # Handle command failures
    result = vm.run("exit 1")
    if not result.ok:
        print(f"Command failed: {result.stderr}")

Shell modes

SmolVM supports two command execution modes:

# Login shell mode (default) - runs through guest login shell
result = vm.run("echo $HOME", shell="login")

# Raw mode - executes command directly with no shell wrapping
result = vm.run("/bin/ls", shell="raw")

VM properties

Access VM information through properties:

with SmolVM() as vm:
    print(vm.vm_id)        # VM identifier
    print(vm.status)       # Current state (VMState.RUNNING)
    print(vm.get_ip())     # Guest IP address
    print(vm.info)         # Full VMInfo object (cached)
    print(vm.data_dir)     # State directory path

    # Refresh cached info from state store
    vm.refresh()
    print(vm.info.status)

Checking SSH capability

Not all VM images support command execution. You can check before running commands:

with SmolVM() as vm:
    if vm.can_run_commands():
        result = vm.run("whoami")
        print(result.output)
    else:
        print("This VM does not support SSH command execution")

Command execution requires the VM to be booted with init=/init in the boot arguments. All auto-configured VMs and images built with ImageBuilder include this by default.

Getting SSH connection details

Retrieve SSH commands for manual connection:

with SmolVM() as vm:
    ssh_cmds = vm.ssh_commands()
    print(ssh_cmds["direct"])     # SSH to guest IP
    print(ssh_cmds["localhost"])  # SSH via localhost (if forwarded)

Error handling

SmolVM raises specific exceptions for different failure scenarios:

from smolvm import SmolVM
from smolvm.exceptions import (
    SmolVMError,
    CommandExecutionUnavailableError,
    OperationTimeoutError,
)

try:
    with SmolVM() as vm:
        result = vm.run("some-command", timeout=5)
except CommandExecutionUnavailableError as e:
    print(f"SSH not available: {e.reason}")
    print(f"Remediation: {e.remediation}")
except OperationTimeoutError as e:
    print(f"Operation timed out: {e.message}")
except SmolVMError as e:
    print(f"SmolVM error: {e}")

Next steps

VM lifecycle

Learn about starting, stopping, and managing VM lifecycles

Port forwarding

Expose guest services to your host machine

Environment variables

Inject configuration into your VMs

Custom images

Build custom rootfs images for your use case

Get Started

Features

Guides

Architecture

Operations

Quick start

Creating a sandbox

Running commands

Shell modes

VM properties

Checking SSH capability

Getting SSH connection details

Error handling

Next steps

VM lifecycle

Port forwarding

Environment variables

Custom images

​Quick start

​Creating a sandbox

​Running commands

​Shell modes

​VM properties

​Checking SSH capability

​Getting SSH connection details

​Error handling

​Next steps

VM lifecycle

Port forwarding

Environment variables

Custom images

Quick start

Creating a sandbox

Running commands

Shell modes

VM properties

Checking SSH capability

Getting SSH connection details

Error handling

Next steps