Hypervisor

A Go runtime and HTTP API for running OCI workloads as fast, isolated virtual machines.

Hypervisor turns container images into bootable microVM instances and manages their full lifecycle — networking, storage, ingress, snapshots, and high-density standby/restore — behind a single OpenAPI-defined API.

Linux is the primary, most complete target. macOS guests via Apple's Virtualization.framework are experimental; see macOS support.

---

Features

• Multiple runtimes — Cloud Hypervisor (default), Firecracker, QEMU, QEMU microvm, and Apple vz, all behind one hypervisor abstraction. Capabilities are discoverable at runtime via GET /capabilities, so clients gate on features rather than runtime names.
• OCI images — pull OCI machine images, convert and cache them, with configurable image retention and OCI cache garbage collection.
• Instance lifecycle — create, start, stop, delete, wait, logs, stats, exec, and file copy (guest-agent gated).
• High density — pause/resume, standby (pause + memory snapshot), restore, warm forks from stopped or memory snapshots, snapshot schedules, and auto-standby policies.
• Storage — volumes, per-instance overlays, disk I/O limits, and live disk resize where the runtime supports it.
• Devices — PCI/VFIO and vGPU passthrough on Linux.
• Networking — TAP devices, bridges, NAT, per-VM DNS, and rate limiting on Linux; automatic NAT on macOS.
• Ingress — HTTP/HTTPS routing through embedded Caddy, with automatic ACME certificates via DNS-01 challenges.
• Image builds — build OCI images from Dockerfiles with an injected builder and push them to registries.
• Observability — Prometheus /metrics, OpenTelemetry traces and metrics, and structured logs.
• One API, many clients — the OpenAPI spec drives CLI and SDK generation.

---

Supported runtimes

Runtime	Platform	Notes
Cloud Hypervisor	Linux	Default; full feature set, including snapshots, standby, and forks
Firecracker	Linux	Snapshot/restore and standby; embedded binary with optional external path
QEMU (qemu)	Linux	Standard board (q35/virt); QMP control
QEMU (qemu-microvm)	Linux amd64	Minimal microvm board; no PCI/vGPU, memory hotplug, or >8 virtio-mmio devices
Apple vz	macOS arm64	Virtualization.framework; experimental, NAT networking

Exact per-runtime feature availability is reported by GET /capabilities and documented in lib/hypervisor/README.md.

---

Requirements

Linux: Go 1.26.10+, KVM, erofs-utils, dnsmasq, the architecture-appropriate qemu-system package, IPv4 forwarding, and cap_net_admin/cap_net_bind_service on the binary.

macOS (experimental): Apple silicon, macOS 11+ (macOS 14+ for snapshots), Go 1.26.10+, Caddy, e2fsprogs, and Rosetta for linux/amd64 images.

Full setup, capability grants, and network configuration are in DEVELOPMENT.md.

---

Installation

Install the server and set it up as a systemd service (Linux) or a launchd user service (macOS):

curl -fsSL https://raw.githubusercontent.com/khulnasoft/hypervisor/main/scripts/install.sh | bash

Install the CLI separately (from khulnasoft/hypervisor-cli):

curl -fsSL https://get.hypervisor.sh/cli | bash

Build from source

git clone https://github.com/khulnasoft/hypervisor.git
cd hypervisor

make install-tools   # oapi-codegen, air, wire, xcaddy
make build           # -> bin/hypervisor (plus bin/hypervisor-uffd-pager on Linux)

---

Quick start

# 1. Create a configuration file
mkdir -p ~/.config/hypervisor
cp config.example.yaml ~/.config/hypervisor/config.yaml   # use config.example.darwin.yaml on macOS

# 2. Set a JWT secret (required, 32+ bytes)
openssl rand -hex 32

# 3. Create the data directory
sudo mkdir -p /var/lib/hypervisor && sudo chown "$USER:$USER" /var/lib/hypervisor

# 4. Run with hot reload
make dev

# 5. Generate a token for local requests
make gen-jwt

# 6. Verify the server
curl http://localhost:4973/health

The API listens on port 4973 by default. Interactive API documentation is served at http://localhost:4973/swagger, with the raw spec at /spec.yaml and /spec.json.

Shared hosts: avoid writing to /etc/hypervisor or /var/lib/hypervisor. Use a workspace-local config and data directory with CONFIG_PATH=... make dev. See DEVELOPMENT.md.

---

Configuration

Hypervisor reads YAML from the first of: $CONFIG_PATH, /etc/hypervisor/config.yaml (Linux), or ~/.config/hypervisor/config.yaml. Environment variables override any key using __ as the nesting separator (for example CADDY__LISTEN_ADDRESS).

Key	Description	Default
port	HTTP API port	4973
data_dir	Images, volumes, snapshots, and other state	/var/lib/hypervisor
jwt_secret	Secret used to sign and verify API tokens (required)	(empty)
hypervisor.default	Default runtime	cloud-hypervisor (Linux), vz (macOS)
network.bridge_name	Bridge for VM networking	vmbr0
network.subnet_cidr	VM network subnet	10.100.0.0/16
network.uplink_interface	Host interface for VM internet access	auto-detected
otel.enabled	Enable OpenTelemetry traces/metrics	false
metrics.port	Port for the /metrics endpoint	9464
logging.level	debug, info, warn, or error	info

See config.example.yaml and config.example.darwin.yaml for all options. TLS ingress requires ACME credentials under acme:.

---

Project structure

├── cmd
│   ├── api             # API server entrypoint, config, and HTTP handlers
│   ├── gen-jwt         # JWT token generator
│   ├── import-macos    # Offline macOS image importer
│   ├── test-prewarm    # Prewarm test helper
│   ├── uffd-pager      # userfaultfd pager for memory snapshots
│   └── vz-shim         # macOS Virtualization.framework shim
├── lib
│   ├── hypervisor      # Runtime abstraction (cloudhypervisor, firecracker, qemu, vz)
│   ├── instances       # Instance lifecycle and state
│   ├── images          # Image pull, conversion, and caching
│   ├── builds          # Dockerfile builds
│   ├── ingress         # Caddy-backed ingress and TLS
│   ├── network         # Linux bridge/TAP networking
│   ├── volumes         # Volume management
│   ├── snapshot        # Snapshots, standby, and forks
│   ├── devices         # VFIO and vGPU passthrough
│   └── ...             # autostandby, guestmemory, ocicache, otel, registry, ...
├── integration         # Integration tests requiring KVM and elevated permissions
├── docs                # macOS guides, proposals, and runbooks
├── specs               # Vendored upstream API specifications
├── openapi.yaml        # API contract (embedded in the Go binary)
├── Makefile            # Build, code generation, test, and release targets
└── DEVELOPMENT.md      # Full development and configuration guide

---

API

The API is defined by openapi.yaml and uses bearer JWT authentication. Main resource groups:

• /instances — lifecycle, exec, logs, stats, standby/restore, forks, snapshots, snapshot schedules, auto-standby, volumes, and guest port forwarding
• /images — pull, list, tag, and delete images
• /builds and /builders — image builds and builder management
• /pushes — push images to registries
• /volumes — create volumes and import from archives
• /ingresses — HTTP/HTTPS ingress rules
• /devices — available and assigned PCI/vGPU devices
• /capabilities, /resources, /health — host and feature discovery

Regenerate Go bindings after editing the spec:

make oapi-generate

---

Development

make dev            # hot reload (air); auto-selects Linux or macOS paths
make test           # full test suite (uses sudo for network capabilities)
make test-linux     # Linux integration-style tests
make test-darwin    # macOS unit tests
make generate-all   # regenerate OpenAPI, VMM clients, Wire, and gRPC code
make build          # production binary

See DEVELOPMENT.md for prerequisites, configuration, TLS/ACME setup, local OpenTelemetry, and the macOS workflow.

---

Documentation

• Development guide
• Hypervisor abstraction
• macOS support and experimental macOS guests
• macOS snapshots and guest agent
• Proposals and runbooks

---

License

MIT © Khulnasoft