Skip to main content
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.

​
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
Last modified on April 6, 2026