squib

A macOS-native, Apple-Silicon-only microVM monitor with a Firecracker-compatible HTTP API. Squib speaks the same JSON shapes, the same UDS surface, the same SDK-friendly Server: Firecracker API header that upstream Firecracker publishes — but on top of HVF + vmnet.framework rather than KVM + Linux TAP.

• Apple-Silicon-only, HVF-only (no VZ), aarch64 Linux guests only.
• Single 1.0 release with full Firecracker compat on day one.
• Snapshots: full and Diff (via hv_vm_protect dirty tracking) + Mach-exception postcopy.
• Networking: --network={shared|bridged|host|userspace} — vmnet for the entitled cases, gvproxy for the rest.

中文：README.zh-CN.md。

Status

Pre-1.0. Phase 7 ("compat suite + perf + polish") is in flight; the live end-to-end boot path tail (vCPU thread + kernel image + PL011 wiring) is tracked under specs/93-improvements-review.md "Phase 1 (lands at end of Phase 1.6)".

Quick start

# Build + ad-hoc-sign for local development (HVF needs the
# com.apple.security.hypervisor entitlement).
make sign

# Spin up an empty squib speaking the Firecracker API on a UDS.
target/release/squib --api-sock /tmp/squib.sock

# Drive it with curl, the upstream getting-started.md sequence, or any SDK that
# treats `Server: Firecracker API` as authoritative.
curl --unix-socket /tmp/squib.sock http://localhost/version

To boot a real Linux guest:

make build-reference-vm    # downloads vmlinux + alpine busybox into examples/reference-vm/build/
make demo                   # codesigned HVF integration test

Documentation

• User guide in docs/user-guide.md (中文) — install, boot a guest, drive it from an SDK, snapshot/restore, troubleshoot.
• Developer guide in docs/dev-guide.md (中文) — workspace layout, build/test loops, HVF codesigning, where to plug in for new features.
• Specs under specs/ — design, data model, runtime, HVF backend, devices, MMDS, snapshots, networking, jailer, CLI.
• Research under docs/research/ — prior-art deep dive, HVF / aarch64 / vmnet write-ups.
• API deviations in docs/api-deviations.md — every P/A/R row from the compat matrix with reproductions.
• macOS setup in docs/macos-setup.md — entitlements, codesigning, gvproxy, network-mode tradeoffs.
• Performance numbers in docs/perf/ — published per revision, never borrowed from upstream.

Compatibility

Per specs/21-api-compat-matrix.md, every upstream Firecracker endpoint, field, and CLI flag has a documented status: F (full parity), P (parity in shape, semantics differ), A (accepted no-op with a one-time warning), or R (rejected with a stable fault_message). The compat suite under tests/firecracker-compat/ drives every row.

License

Apache-2.0. See LICENSE.md.

Copyright 2025 Tyr Chen.

lib.rs:

Portable types and traits at the heart of squib.

This crate intentionally has zero OS dependencies: it defines the abstractions that backend crates (squib-vz, squib-hvf) implement, the device traits the VMM crate consumes, and the value types that flow through the API server. See specs/squib-design.md for the architectural picture.

The crate is organized as:

• error — the Error enum every fallible operation in squib returns.
• memory — guest-physical address ranges and memory protection.
• exit — the VmExit enum that subsumes KVM's VcpuExit and HVF/VZ exit shapes.
• vcpu — register file, interrupt descriptors, and the Vcpu trait.
• backend — the HypervisorBackend / [Vm] trait pair plus capability discovery.
• lifecycle — the internal LifecyclePhase state machine and the wire-shape WireVmState surfaced by GET /.