Skip to main content

​
Synopsis

smolvm doctor [OPTIONS]

​
Description

The doctor command runs comprehensive diagnostics on your system to verify that all prerequisites for running SmolVM are met. It checks for required binaries, permissions, KVM availability, and network configuration.

​
Options

​
--backend
string
default:"auto"
Backend to validate. Choices: auto, firecracker, qemu.
  • auto: Automatically detect the best backend for your platform
  • firecracker: Validate Firecracker-specific requirements (Linux only)
  • qemu: Validate QEMU-specific requirements
​
--json
flag
default:"false"
Emit machine-readable JSON output instead of human-readable format.
​
--strict
flag
default:"false"
Treat warnings as failures. When enabled, the command exits with code 1 if any warnings are present.

​
Examples

​
Basic diagnostics

Run diagnostics with auto-detected backend: 
smolvm doctor
Example output: 
SmolVM Doctor
Backend: firecracker (requested: auto)
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

​
Validate specific backend

Check Firecracker-specific requirements: 
smolvm doctor --backend firecracker
Check QEMU-specific requirements: 
smolvm doctor --backend qemu
Example output (macOS): 
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

​
JSON output

Get machine-readable output for automation: 
smolvm doctor --json
Example output: 
{
  "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"
    },
    {
      "name": "command:nft",
      "status": "pass",
      "detail": "/usr/sbin/nft"
    },
    {
      "name": "command:ssh",
      "status": "pass",
      "detail": "/usr/bin/ssh"
    },
    {
      "name": "network-permissions",
      "status": "pass",
      "detail": "network commands and sudo policy are available"
    }
  ],
  "summary": {
    "failures": 0,
    "warnings": 0,
    "ok": true,
    "strict": false
  }
}

​
Strict mode

Fail on warnings: 
smolvm doctor --strict
Example output: 
SmolVM Doctor
Backend: firecracker (requested: auto)
Platform: Linux x86_64

[PASS] kvm: /dev/kvm is available
[PASS] firecracker: /home/user/.smolvm/bin/firecracker
[PASS] command:ip: /usr/sbin/ip
[FAIL] command:nft: 'nft' not found (install nftables)
[PASS] command:ssh: /usr/bin/ssh

Doctor result: FAIL

​
Checks Performed

​
Firecracker Backend

When validating the Firecracker backend, doctor checks:
  • KVM: /dev/kvm availability (hardware virtualization)
  • Firecracker binary: Located in PATH or ~/.smolvm/bin
  • ip command: From iproute2 package (network management)
  • nft command: From nftables package (firewall rules)
  • ssh command: From openssh-client package (VM access)
  • Network permissions: Sudo access for network operations
  • nftables tables: Checks for existing smolvm_nat and smolvm_filter tables

​
QEMU Backend

When validating the QEMU backend, doctor checks:
  • QEMU binary: qemu-system-aarch64 or qemu-system-x86_64
  • Hardware acceleration:
    • Linux: KVM support
    • macOS: Hypervisor.framework (hvf) support
  • ssh command: From openssh-client package (VM access)

​
Check Statuses

StatusDescription
PASSCheck succeeded
WARNNon-critical issue detected (treated as pass unless --strict is used)
FAILCritical requirement missing

​
Exit Codes

CodeDescription
0Success - all checks passed (or only warnings without --strict)
1Failure - one or more checks failed (or warnings with --strict)

​
Common Issues

​
Missing KVM

[FAIL] kvm: /dev/kvm unavailable
Solution: Ensure KVM is enabled in your system’s BIOS/UEFI and that the kvm kernel module is loaded.

​
Firecracker not found

[FAIL] firecracker: binary not found in PATH or ~/.smolvm/bin
Solution: Run the system setup script or manually install Firecracker: 
sudo ./scripts/system-setup.sh --configure-runtime

​
Missing network commands

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

# Fedora/RHEL
sudo dnf install nftables
Last modified on March 3, 2026