Skip to main content

​
Overview

The HostManager class validates the host environment and manages the Firecracker binary installation. It checks for required system capabilities like KVM access, network tools, and the Firecracker binary. The default installation directory is ~/.smolvm/bin/.

​
Constructor

​
firecracker_version
str
default:"v1.14.1"
Pinned Firecracker version to install when auto-installing (e.g., “v1.14.1”).
from smolvm import HostManager

# Use default Firecracker version
host_mgr = HostManager()

# Specify custom version
host_mgr = HostManager(firecracker_version="v1.14.1")

​
Class Attributes

​
SMOLVM_HOME
Path
SmolVM home directory: ~/.smolvm
​
BIN_DIR
Path
Binary installation directory: ~/.smolvm/bin/

​
Methods

​
detect_arch

def detect_arch() -> str
Detect the host CPU architecture.
​
returns
str
Architecture string (e.g., “x86_64”, “aarch64”).
host_mgr = HostManager()
arch = host_mgr.detect_arch()
print(f"Detected architecture: {arch}")

​
check_kvm

def check_kvm() -> bool
Check if /dev/kvm exists and is accessible with read/write permissions.
​
returns
bool
True if KVM is available with R/W permissions, False otherwise.
host_mgr = HostManager()
if not host_mgr.check_kvm():
    print("KVM is not available. Run: sudo usermod -aG kvm $USER")

​
check_dependencies

def check_dependencies() -> list[str]
Check for required system dependencies:
  • ip (iproute2)
  • nft (nftables)
  • ssh (openssh-client)
​
returns
list[str]
List of missing dependency names (empty if all present).
host_mgr = HostManager()
missing = host_mgr.check_dependencies()
if missing:
    print(f"Missing dependencies: {', '.join(missing)}")

​
find_firecracker

def find_firecracker() -> Path | None
Find the Firecracker binary by searching:
  1. System PATH
  2. ~/.smolvm/bin/firecracker
​
returns
Path | None
Path to the binary, or None if not found.
host_mgr = HostManager()
fc_path = host_mgr.find_firecracker()
if fc_path:
    print(f"Firecracker found at: {fc_path}")
else:
    print("Firecracker not found")

​
install_firecracker

def install_firecracker(version: str | None = None) -> Path
Download and install Firecracker from GitHub releases. Downloads the official tarball, extracts the firecracker binary, and installs it to ~/.smolvm/bin/.
​
version
str | None
default:"None"
Version to install (e.g., “v1.14.1”). Defaults to the pinned version from the constructor.
​
returns
Path
Path to the installed binary.
​
raises
HostError
If architecture is unsupported, download fails, or extraction fails.
host_mgr = HostManager()

# Install default version
fc_path = host_mgr.install_firecracker()
print(f"Firecracker installed at: {fc_path}")

# Install specific version
fc_path = host_mgr.install_firecracker(version="v1.14.1")

​
validate

def validate() -> HostInfo
Run all host validation checks and return a summary.
​
returns
HostInfo
Summary of validation results with the following attributes:
  • arch (str): CPU architecture (e.g., “x86_64”)
  • capabilities (dict[HostCapability, bool]): Map of capability to availability
  • missing_deps (list[str]): List of missing dependency names
  • firecracker_path (Path | None): Path to the Firecracker binary, if found
from smolvm import HostManager

host_mgr = HostManager()
info = host_mgr.validate()

print(f"Architecture: {info.arch}")
print(f"KVM available: {info.capabilities['kvm']}")
print(f"Network tools: {info.capabilities['net_tools']}")
print(f"Firecracker: {info.capabilities['firecracker']}")

if info.missing_deps:
    print(f"Missing dependencies: {', '.join(info.missing_deps)}")

if info.firecracker_path:
    print(f"Firecracker path: {info.firecracker_path}")

​
Complete Example

from smolvm import HostManager

# Initialize host manager
host_mgr = HostManager()

# Validate the host environment
info = host_mgr.validate()

if not info.capabilities['kvm']:
    print("Error: KVM is not available")
    exit(1)

if not info.capabilities['firecracker']:
    print("Firecracker not found, installing...")
    fc_path = host_mgr.install_firecracker()
    print(f"Firecracker installed at: {fc_path}")

if info.missing_deps:
    print(f"Warning: Missing dependencies: {', '.join(info.missing_deps)}")
    print("Run: sudo ./scripts/system-setup.sh --configure-runtime")

print("Host environment is ready for SmolVM!")

​
HostCapability

Enum of host capabilities that SmolVM depends on:
  • HostCapability.KVM - KVM virtualization support
  • HostCapability.NET_TOOLS - Network configuration tools (ip, nft, ssh)
  • HostCapability.FIRECRACKER - Firecracker binary availability

​
HostInfo

Pydantic model containing host validation results. See the validate() method for details.
Last modified on March 3, 2026