Skip to main content

​
Overview

The smolvm doctor command performs comprehensive diagnostics on your system to ensure SmolVM can run properly. It checks for required dependencies, permissions, and backend-specific requirements.

​
Basic Usage

smolvm doctor
This runs diagnostics for the auto-detected backend (Firecracker on Linux, QEMU on macOS).

​
Command Syntax

smolvm doctor [--backend BACKEND] [--json] [--strict]

​
Options

​
--backend
string
default:"auto"
Backend to validate. Choices: auto, firecracker, qemu
  • auto: Automatically detect the appropriate backend for your platform
  • firecracker: Validate Firecracker requirements (Linux + KVM)
  • qemu: Validate QEMU requirements (cross-platform)
​
--json
boolean
default:false
Emit machine-readable JSON output instead of human-friendly text
​
--strict
boolean
default:false
Treat warnings as failures. Useful for CI/CD validation

​
Examples

​
Run Diagnostics for Firecracker

smolvm doctor --backend firecracker

SmolVM Doctor
Backend: firecracker (requested: firecracker)
Platform: Linux x86_64

[PASS] kvm: /dev/kvm is available
[PASS] firecracker: /home/user/.smolvm/bin/firecracker
[PASS] command:ip: /usr/sbin/ip
[PASS] command:nft: /usr/sbin/nft
[PASS] command:ssh: /usr/bin/ssh
[PASS] network-permissions: network commands and sudo policy are available
[WARN] nft-table:ip:smolvm_nat: not created yet (will be created on first VM network setup)
[WARN] nft-table:inet:smolvm_filter: not created yet (will be created on first VM network setup)

Doctor result: OK

​
Run Diagnostics for QEMU on macOS

smolvm doctor --backend qemu

SmolVM Doctor
Backend: qemu (requested: qemu)
Platform: Darwin arm64

[PASS] qemu: qemu-system-aarch64 (/opt/homebrew/bin/qemu-system-aarch64)
[PASS] qemu-accel: Hypervisor.framework (hvf) is available
[PASS] command:ssh: /usr/bin/ssh

Doctor result: OK

​
Get JSON Output for Automation

smolvm doctor --json

{
  "backend_requested": "auto",
  "backend_resolved": "firecracker",
  "system": "Linux",
  "arch": "x86_64",
  "checks": [
    {
      "name": "kvm",
      "status": "pass",
      "detail": "/dev/kvm is available"
    },
    {
      "name": "firecracker",
      "status": "pass",
      "detail": "/home/user/.smolvm/bin/firecracker"
    },
    {
      "name": "command:ip",
      "status": "pass",
      "detail": "/usr/sbin/ip"
    }
  ],
  "summary": {
    "failures": 0,
    "warnings": 2,
    "ok": true,
    "strict": false
  }
}

​
Strict Mode for CI/CD

smolvm doctor --strict
In strict mode, warnings are treated as failures. This is useful for automated validation: 
SmolVM Doctor
Backend: firecracker (requested: auto)
Platform: Linux x86_64

[PASS] kvm: /dev/kvm is available
[PASS] firecracker: /usr/local/bin/firecracker
[PASS] command:ip: /usr/sbin/ip
[WARN] command:nft: 'nft' not found (install nftables)
[PASS] command:ssh: /usr/bin/ssh

Doctor result: FAIL (strict mode treats warnings as failures)

​
Checks Performed

​
Firecracker Backend

When validating Firecracker, smolvm doctor checks:
​
kvm
check
Verifies /dev/kvm is available for hardware virtualization
​
firecracker
check
Locates the Firecracker binary in PATH or ~/.smolvm/bin
​
command:ip
check
Ensures ip command is available (from iproute2 package)
​
command:nft
check
Ensures nft command is available (from nftables package)
​
command:ssh
check
Ensures ssh command is available (from openssh-client package)
​
network-permissions
check
Validates that network commands and sudo policies are properly configured
​
nft-table:ip:smolvm_nat
check
Checks if SmolVM’s NAT table exists (informational - created automatically)
​
nft-table:inet:smolvm_filter
check
Checks if SmolVM’s filter table exists (informational - created automatically)

​
QEMU Backend

When validating QEMU, smolvm doctor checks:
​
qemu
check
Locates qemu-system-aarch64 or qemu-system-x86_64 binaries
​
qemu-accel
check
On macOS, verifies Hypervisor.framework (hvf) acceleration is available
​
command:ssh
check
Ensures ssh command is available

​
Exit Codes

  • 0: All checks passed (or warnings in non-strict mode)
  • 1: One or more checks failed, or warnings in strict mode

​
Check Statuses

Each check returns one of three statuses:
  • PASS: Check succeeded
  • WARN: Non-critical issue detected (treated as failure in strict mode)
  • FAIL: Critical issue that prevents SmolVM from functioning

​
Common Failures

​
Missing KVM Access

[FAIL] kvm: /dev/kvm unavailable
Solution: Run the system setup script: 
sudo ./scripts/system-setup.sh --configure-runtime
This configures KVM permissions and adds your user to the appropriate group.

​
Firecracker Not Found

[FAIL] firecracker: binary not found in PATH or ~/.smolvm/bin
Solution: SmolVM will attempt to download Firecracker automatically on first VM creation. You can also manually install it: 
# Download and place in ~/.smolvm/bin/firecracker
# Or install system-wide and add to PATH

​
Missing Network Tools

[FAIL] command:nft: 'nft' not found (install nftables)
Solution: Install the required package: 
# Ubuntu/Debian
sudo apt-get install nftables

# Fedora/RHEL
sudo dnf install nftables

​
Network Permission Issues

[FAIL] network-permissions: sudo policy not configured for ip/nft commands
Solution: Run the system setup script to configure passwordless sudo for network commands: 
sudo ./scripts/system-setup.sh --configure-runtime

​
Integration with CI/CD

Use smolvm doctor in your CI pipeline to validate the environment: 
# GitHub Actions example
steps:
  - name: Install SmolVM
    run: pip install smolvm
  
  - name: Validate Environment
    run: smolvm doctor --strict --json > doctor-report.json
  
  - name: Upload Report
    uses: actions/upload-artifact@v3
    with:
      name: doctor-report
      path: doctor-report.json
The --json flag combined with --strict makes it easy to parse results and fail CI builds on any issues.

​
Troubleshooting

If smolvm doctor reports failures:
  1. Check system requirements: Ensure you’re running on a supported platform (Linux for Firecracker, macOS/Linux for QEMU)
  2. Run system setup: Execute sudo ./scripts/system-setup.sh --configure-runtime
  3. Verify permissions: Make sure your user is in the kvm group (Linux) or has appropriate privileges
  4. Install missing tools: Install any missing dependencies reported by doctor
  5. Check virtualization: Ensure hardware virtualization is enabled in your BIOS/UEFI

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us