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”).

Class Attributes

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

Methods

detect_arch

Detect the host CPU architecture.
returns
str
Architecture string (e.g., “x86_64”, “aarch64”).

check_kvm

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.

check_dependencies

Check for required system dependencies:
  • ip (iproute2)
  • nft (nftables)
  • ssh (openssh-client)
returns
list[str]
List of missing dependency names (empty if all present).

find_firecracker

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.

install_firecracker

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.

validate

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

Complete Example

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 May 5, 2026