Installation

Detailed installation instructions for SmolVM on Linux and macOS

SmolVM supports two backends depending on your operating system:

• Linux: Firecracker (KVM-based microVMs)
• macOS: QEMU (hardware virtualization)

The backend is automatically detected based on your platform, but can be overridden via the SMOLVM_BACKEND environment variable.

Requirements

System Requirements

Linux

• OS: Ubuntu, Debian, Fedora, or any Linux distribution with KVM support
• Python: 3.10 or later
• KVM: /dev/kvm must be accessible
• Architecture: x86_64 (amd64)
• Dependencies: ip, nft, ssh, wget, tar

macOS

• OS: macOS (Apple Silicon and Intel)
• Python: 3.10 or later
• Homebrew: Required for QEMU installation
• Architecture: ARM64 (Apple Silicon) or x86_64 (Intel)

Python Dependencies

SmolVM requires the following Python packages (installed automatically via pip):

• paramiko>=3.0 - SSH client for guest command execution
• pydantic>=2.0 - Data validation and settings management
• requests>=2.28 - HTTP client for API interactions
• requests-unixsocket>=0.3 - Unix socket support for Firecracker API

Installation Steps

Linux (Firecracker)

1. Install Python package

   pip install smolvm
   
2. Run system setup script

   The system setup script installs Firecracker and configures your system:

   sudo ./scripts/system-setup.sh --configure-runtime
   

   What does this script do?

   The setup script performs the following operations:

   1. Checks KVM support: Verifies /dev/kvm exists
   2. Installs system dependencies: curl, wget, jq, nftables, iproute2, e2fsprogs, openssh-client, tar
   3. Downloads and installs Firecracker: Fetches the latest Firecracker binary and installs to /usr/local/bin
   4. Adds user to KVM group: Grants access to /dev/kvm
   5. Configures runtime sudoers: Sets up passwordless sudo for specific SmolVM commands (ip, nft)

   The --configure-runtime flag configures passwordless sudo for networking commands. This is optional but recommended for seamless operation.

3. Activate KVM group membership

   After setup, activate the KVM group:

   newgrp kvm
   

   Or log out and log back in for the group changes to take effect permanently.

4. Verify installation

   Check that everything is installed correctly:

   # Check Firecracker
   firecracker --version
   
   # Check SmolVM
   python -c "from smolvm import SmolVM; print('SmolVM installed successfully')"
   
   # Run system diagnostics
   smolvm doctor
   

macOS (QEMU)

1. Install Homebrew (if not already installed)

   If you don’t have Homebrew, install it from brew.sh:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
2. Install Python package

   pip install smolvm
   
3. Run macOS setup script

   The macOS setup script installs QEMU via Homebrew:

   ./scripts/system-setup-macos.sh
   

   What does this script do?

   The macOS setup script:

   1. Verifies Homebrew: Checks that brew is available
   2. Installs QEMU: Installs qemu-system-aarch64 and qemu-system-x86_64 via Homebrew
   3. Verifies SSH: Ensures the SSH client is available (pre-installed on macOS)
   4. Optional Docker: With --with-docker, installs Docker Desktop

   On macOS, the QEMU backend is automatically selected. You can verify this:

   smolvm doctor --backend qemu
   
4. Verify installation

   Check that everything is installed correctly:

   # Check QEMU
   qemu-system-aarch64 --version  # Apple Silicon
   qemu-system-x86_64 --version   # Intel
   
   # Check SmolVM
   python -c "from smolvm import SmolVM; print('SmolVM installed successfully')"
   
   # Run system diagnostics
   smolvm doctor
   

Advanced Installation Options

Custom Backend Selection

You can override the automatic backend detection:

# Force QEMU backend (useful for testing on Linux)
export SMOLVM_BACKEND=qemu

# Force Firecracker backend
export SMOLVM_BACKEND=firecracker

# Auto-detect (default)
export SMOLVM_BACKEND=auto

In Python:

from smolvm import SmolVM

# Explicitly use QEMU backend
vm = SmolVM(backend="qemu")

Installing with Docker Support

For building custom images, you may want Docker installed:

Linux

sudo ./scripts/system-setup.sh --configure-runtime --with-docker

Development Installation

For development with testing and linting tools:

# Clone the repository
git clone https://github.com/CelestoAI/SmolVM.git
cd SmolVM

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Type checking
mypy src

Skip Dependency Installation

If you’ve already installed dependencies manually, skip the package manager step:

Linux

sudo ./scripts/system-setup.sh --configure-runtime --skip-deps

Verifying Installation

System Diagnostics

SmolVM includes a diagnostic tool to verify your setup:

# Auto-detect backend and check dependencies
smolvm doctor

# Check specific backend
smolvm doctor --backend firecracker
smolvm doctor --backend qemu

# CI-friendly JSON output
smolvm doctor --json --strict

Test Your First VM

Run a simple test to ensure everything works:

from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("echo 'SmolVM is working!'")
    print(result.output)
    print(f"VM IP: {vm.get_ip()}")
    print(f"Status: {vm.status}")

If this runs without errors, your installation is complete!

Troubleshooting

Linux: KVM not available

If /dev/kvm doesn’t exist, ensure KVM is enabled:

# Check if KVM is loaded
lsmod | grep kvm

# For Intel CPUs
sudo modprobe kvm_intel

# For AMD CPUs
sudo modprobe kvm_amd

# Verify /dev/kvm exists
ls -l /dev/kvm

For cloud VMs, ensure nested virtualization is enabled in your hypervisor settings.

Linux: Permission denied on /dev/kvm

Add your user to the kvm group:

sudo usermod -aG kvm $USER
newgrp kvm

Verify group membership:

groups | grep kvm

Linux: Firecracker not found after installation

Ensure /usr/local/bin is in your PATH:

echo $PATH
export PATH="/usr/local/bin:$PATH"

# Make permanent by adding to ~/.bashrc or ~/.zshrc
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc

macOS: qemu-system not found

Ensure Homebrew’s bin directory is in your PATH:

# For Apple Silicon
export PATH="/opt/homebrew/bin:$PATH"

# For Intel
export PATH="/usr/local/bin:$PATH"

# Verify QEMU
which qemu-system-aarch64

Network connectivity issues

Linux: Ensure nftables is installed and running:

sudo systemctl status nftables
sudo nft list ruleset

macOS: QEMU networking uses user-mode networking by default, which should work without additional configuration.

apt-get update failures on Linux

If the setup script fails during apt-get update, your repository sources may need updating:

# Check sources
cat /etc/apt/sources.list

# Update manually
sudo apt-get update

# If sources are broken, fix them first, then rerun with --skip-deps
sudo ./scripts/system-setup.sh --configure-runtime --skip-deps

Uninstallation

Remove SmolVM Python package

pip uninstall smolvm

Remove system components

Linux

# Remove Firecracker binary
sudo rm /usr/local/bin/firecracker
sudo rm /usr/local/bin/jailer  # if installed

# Remove runtime sudoers configuration
sudo ./scripts/system-setup.sh --remove-runtime-config

# Remove user from KVM group (optional)
sudo deluser $USER kvm

# Clean up SmolVM data
rm -rf ~/.local/state/smolvm
rm -rf ~/.smolvm

macOS

# Remove QEMU (if no longer needed)
brew uninstall qemu

# Clean up SmolVM data
rm -rf ~/.local/state/smolvm
rm -rf ~/.smolvm

Next Steps

Quickstart

Start using SmolVM with simple examples

Configuration

Learn about VM configuration options

Custom Images

Build your own VM images with custom tools

API Reference

Explore the complete API