smolvm doctor

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

Status	Description
`PASS`	Check succeeded
`WARN`	Non-critical issue detected (treated as pass unless `--strict` is used)
`FAIL`	Critical requirement missing

Exit Codes

Code	Description
`0`	Success - all checks passed (or only warnings without `--strict`)
`1`	Failure - 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 setup command or manually install Firecracker:

smolvm setup

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

smolvm sandbox delete - Delete sandboxes after diagnosing issues

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Synopsis

Description

Options

Examples

Basic diagnostics

Validate specific backend

JSON output

Strict mode

Checks Performed

Firecracker Backend

QEMU Backend

Check Statuses

Exit Codes

Common Issues

Missing KVM

Firecracker not found

Missing network commands

​Synopsis

​Description

​Options

​Examples

​Basic diagnostics

​Validate specific backend

​JSON output

​Strict mode

​Checks Performed

​Firecracker Backend

​QEMU Backend

​Check Statuses

​Exit Codes

​Common Issues

​Missing KVM

​Firecracker not found

​Missing network commands

​Related Commands

Synopsis

Description

Options

Examples

Basic diagnostics

Validate specific backend

JSON output

Strict mode

Checks Performed

Firecracker Backend

QEMU Backend

Check Statuses

Exit Codes

Common Issues

Missing KVM

Firecracker not found

Missing network commands

Related Commands