Skip to content
docs.microagent.sh

microagent doctor

Last updated: 2026-06-23

microagent doctor [--arch <arch>] [--supervisor <path>]

doctor reports host support for the installed host backend and the default kernel status. Run it first when something isn’t working. Use host when you want the same information as an inspectable capability report rather than a health check.

Examples

Section titled “Examples”

Check the host:

Terminal window
microagent doctor
microagent --json doctor

Text output is a short health summary:

Backend: linux-kvm
Status: ok
Host: amd64, supervisor=/usr/local/lib/microagent/firecracker-supervisor, supervisor available, virtualization supported, KVM available, vsock available
Console: available (interactive)
Kernel: installed (/home/user/.microagent/kernels/linux-kvm/amd64/vmlinux)

The Networking: line is backend-specific. Linux reports isolated and user readiness, including whether pasta, unprivileged user namespaces, and /dev/net/tun are present for user mode. Apple VF reports its local isolated and user readiness.

doctor shares the structured shape with host: microagent --json doctor returns the same vmkit.Response with ok, backend, host, and kernel populated. ok is false when any required check fails.

What it checks

Section titled “What it checks”
  • Apple VF (macOS): Virtualization.framework available, supervisor reachable, default kernel installed, interactive console available.
  • Firecracker (Linux): firecracker binary on PATH (or MICROAGENT_FIRECRACKER), /dev/kvm present, /dev/vhost-vsock present, /dev/net/tun present, pasta available for user-mode networking, unprivileged user namespace creation actually works (a live CLONE_NEWUSER probe, so policy layers like AppArmor’s kernel.apparmor_restrict_unprivileged_userns are caught, not just the classic userns sysctls), default kernel installed, interactive console available.
  • Windows Hyper-V (experimental): Windows Host Compute Service available, Hyper-V / Windows Hypervisor Platform support available, HCS access allowed for the current user, HCN/HNS networking available, Hyper-V sockets available, default kernel installed, guest-init available, and HVSock console support available.

On Linux, run microagent doctor outside sandboxed agent environments so KVM visibility is honest. On Windows, run it from the same user account that will start workspaces. HCS access usually requires Administrator or membership in the Hyper-V Administrators group.

Flags

Section titled “Flags”

You’ll rarely need flags here - --backend to probe a backend other than the detected one, --arch when you plan to run non-native guests.

FlagDescription
--backend <name>Backend override (apple-vf, linux-kvm, or windows-hyperv)
--arch <arch>Guest architecture (amd64, arm64)
--supervisor <path>Override the installed host backend supervisor path
--jsonGlobal flag before doctor; print structured JSON output

See global flags for --json/--text/--output/--mode/--supervisor.

Exit status

Section titled “Exit status”

doctor exits 0 when every required check passes; nonzero when any required check fails. The printed summary still includes the full check detail either way. In AX mode a failure is additionally written as a structured error envelope.

Section titled “Related”