Gimbal Local 0.2.2

Gimbal Local 0.2.2 — Cloud Hypervisor snapshots, rehydrated on Apple silicon.

A vanilla Cloud Hypervisor arm64 snapshot captured on a Linux/KVM host — no
fork, no patches, no flags — resumes on Apple Hypervisor.framework and comes
back to a live shell. Or cold-boot a stock kernel with no snapshot at all.

What you need

• An Apple silicon Mac (M1 or later) running macOS 14 or newer.

What you do not need

Worth saying plainly, because every comparable tool asks for at least one:

• No Linux host and no KVM machine. The Mac is the hypervisor.
• No control plane or account. Guest execution is local and can run offline;
  pulling an image from a container registry requires network access.
• No Rust toolchain, no Xcode, no source checkout. chm ships inside the app.

The app is signed with a Developer ID certificate and notarized by Apple, so it
opens without a Gatekeeper warning and its ticket verifies offline.

The accompanying GimbalLocal-0.2.2.release-metadata provenance asset
records the source commit, ZIP SHA-256, arm64 architecture, and signing identity
verified before this release was created.

Install

1. Download GimbalLocal-0.2.2.zip below.
2. Double-click it in Finder to unpack, then move GimbalLocal.app to
   /Applications. Finder shows it as Gimbal Local.
3. Open it. The engine starts itself.

If you unpack from a terminal, use ditto, not unzip:

ditto -x -k GimbalLocal-0.2.2.zip .

unzip does not understand the extended attributes this archive carries, and
writes them into the app bundle as stray ._* files. They are not covered by
the code signature, so macOS refuses to run the result. Finder and ditto both
unpack it correctly.

chm ships inside the app. To use it from a terminal:

/Applications/GimbalLocal.app/Contents/MacOS/chm --help

Before it can start anything

The app creates ~/gimbal-snapshots and ~/gimbal-images on first launch,
and both are empty — it does not ship a guest. You need one of:

• a Cloud Hypervisor arm64 snapshot (state.json + snapshot/memory-ranges,
  from ch-remote … snapshot on a Linux host) to rehydrate; or
• a directory holding an uncompressed arm64 kernel Image to cold-boot; or
• a container reference plus an arm64 kernel — for example,
  chm image build alpine:3.20 --kernel /path/to/Image. The image may also
  need the matching module tree via --modules. Registry pulls use the
  network.

Known limits

• One guest at a time. hv_vm_create is process-global on macOS.
• A guest resumed from a snapshot inherits the capture host's CPU feature
  view. On Graviton that means CTR_EL0.DIC disagrees with this Mac, which
  breaks JIT-heavy workloads such as npm. Cold-booted guests are immune by
  construction, because their kernel reads this Mac's own CTR_EL0.
• arm64 guests only. A sandbox.json asking for x86_64, and an
  amd64-only container image, are both refused by name up front. An x86_64
  snapshot is not recognised as such and will fail less clearly.