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:

aarch64 architecture support for squib.

squib-arch is the single source of truth for every architecture-specific constant and protocol the boot path depends on. It is consumed by the HVF backend (squib-hv), the FDT builder (squib-fdt), the kernel loader (squib-loader), and the VMM boot orchestrator (squib-vmm). If a constant is in this crate, no other crate is allowed to invent it.

See 13-arch-and-boot.md for the full design.

Modules

• layout — fixed memory layout (D22) with const overlap-checks and the page geometry.
• [gic] — IntId newtype that pins the FDT-cell ↔ raw-INTID mapping.
• [esr] — ESR_EL2 decoder; never panics on a malformed input.
• psci — PSCI 1.1 dispatch table; unknown IDs return NOT_SUPPORTED.
• regs — the Reg enum (X0..X30, SP, PC, PSTATE) and set_boot_regs helper.
• sysregs — curated sysreg subset (~100 regs we touch).