BridgeVM

Run Windows 11 Arm on Apple silicon with a Mac-native, QEMU-free Hypervisor.framework VMM.

BridgeVM is built for people who want to use, inspect, and improve a native virtualization stack. It includes persistent storage, display and input, networking, audio, guest integration, TPM/Secure Boot workflows, and snapshots. Experimental graphics research continues separately in Graphics Lab and is not part of the General Preview or v1 release scope.

Measured on real hardware

Retained campaign	Result	Evidence boundary
Fresh Windows first boot	10 / 10 passed	Product-default campaign; fixed gate required at least 9/10
CoreAudio playback and shutdown	10 / 10 passed	2,504,031 frames; zero drops and zero unexpected callback errors

These are retained campaign results on the measured hardware and exact sealed inputs, not estimates or promises for every application or Mac. The fixed thresholds and receipts are linked from the Windows capability matrix.

What works today

• installed Windows 11 Arm desktop on BridgeVM's own Hypervisor.framework VMM;
• persistent NVMe storage and UEFI variable state;
• four-vCPU execution, reset/recreate lifecycle, and clean shutdown;
• keyboard, absolute pointer, dynamic resize, network, host audio, clipboard, folder transfer, and guest-agent control;
• TPM 2.0, Secure Boot and measured-boot workflows, encrypted vTPM state, recovery/migration;
• deterministic hosted CI plus sealed real-hardware receipts for behavior that CI cannot prove.

BridgeVM distinguishes code that compiles, deterministic tests, and behavior observed in a real guest. The snapshot below is generated from the capability registry; it is the product wording source of truth.

Product state: Engineering Preview. Runs an installed Windows 11 Arm desktop on BridgeVM's own Hypervisor.framework VMM with persistent storage, display/input, dynamic resolution, network, audio, clipboard and folder integration, TPM/Secure Boot workflows, snapshots and window Coherence verbs. 3D acceleration is excluded from General Preview and v1; release-blocking evidence remains open and known defects are disclosed below.

Release-blocking criteria proven: 14 / 17. Open: A9, A11, A19.

Known open defects:

• A9: No retained clean-machine product-flow receipt yet proves either ISO installation or installed-disk import through the app. Both supported flows remain 3D-off.

• A19: Legacy managed storage relocated before identity migration is refused. Full interrupted-operation coverage, physical power-loss coverage and the remaining product lifecycle sample count are unproven.

• B6: Window title, tab and menu glyphs can be blank on the experimental Windows graphics path; body text alone does not prove glyph correctness.

• Graphics future path: Vulkan is a Graphics Lab future path, excluded from General Preview and v1; D3D11 compatibility is a Graphics Lab future path, excluded from General Preview and v1.

• Guest platform: QEMU virt-compatible guest contract with documented deviations.

State reviewed 2026-09-25 at commit 02052c31dbe2c0cdefe7e93affd31300a2e43d76. This block is generated from capabilities/windows-hvf.json by scripts/render-capability-status.py.

See the current status and Windows capability matrix for the fixed thresholds and retained receipts.

Important

BridgeVM is an Engineering Preview, not a production VM product. Bring your own licensed Windows 11 Arm ISO. The general download does not contain a Windows test driver, does not enable TESTSIGNING, and installs Windows with 3D acceleration excluded from this release scope.

Install status

There is currently no safe downloadable General Preview. The only published release, v1.0.0, predates the fail-closed driver policy, so install.sh intentionally refuses it. Build the current source by following the installation guide; do not work around the refusal or treat the superseded release as the current product.

After a safe successor is published, the installer will download the newest General Preview, verify its release contract, SHA-256 checksum, archive layout, app identity, architecture and ad-hoc code-signing seal, then install it in /Applications. It never touches VM data during an install or update.

After the app opens:

1. Choose Windows → Install from ISO.
2. Select your Windows 11 Arm ISO, a signed ARM64 storage/serial/network driver payload, its external SHA-256 manifest, and the VM size.
3. Create the VM and let the unattended installation finish.

An ISO alone is not sufficient for this Engineering Preview. The General Preview deliberately does not redistribute Windows kernel drivers; use windows-guest-payload-v1.example.tsv to describe packages you are licensed to use. BridgeVM seals those exact inputs and refuses missing, changed, unsigned-CMS, non-ARM64, or incomplete payloads. This payload is for storage, serial integration, and networking; it does not enable the unavailable 3D injection path.

Prefer a DMG or want to inspect every verification step? Read the installation guide.

Pick the right channel

Channel	Intended for	Windows graphics policy	Security boundary
General Preview	Users and contributors	Basic display; 3D acceleration is outside the release scope	No Windows test driver; TESTSIGNING is not enabled; Secure Boot policy is not weakened
Graphics Lab	Driver developers on disposable test VMs	Opt-in test-signed experimental package	Separate tooling and evidence only; may require TESTSIGNING and a different Secure Boot posture

The Graphics Lab package is not a production-signing substitute and is not bundled into the General Preview. Its B4 result proves the exact test package's pointer behavior; it does not close the A9 Microsoft kernel-policy signing requirement. Read the full distribution channel contract before using it.

Known boundaries

• The Mac app is ad-hoc signed, not Developer ID signed or Apple-notarized. Browser-downloaded DMGs therefore need the documented one-time Open Anyway step. The terminal installer states its narrower trust model and verifies every artifact before replacement.
• Windows-HVF install and import use the supported 3D-off configuration. A9 remains open until both clean-machine app journeys have retained evidence.
• Running-state suspend is outside the v1 scope; powered-off snapshots are the supported persistence boundary.

Future direction

3D acceleration is a Graphics Lab future path, not an active release commitment. The retained Vulkan and D3D11 title campaigns remain valid research evidence, including the known glyph defects, but they are non-blocking and do not describe General Preview or v1 behavior. Product work may resume after a Microsoft kernel-policy-signed ARM64 package exists and both product flows can verify it without weakening Secure Boot.

Build from source

Requirements: Apple silicon, macOS 14+, Xcode/Swift 5.9+, and Rust 1.85+.

git clone https://github.com/Ketchio-dev/bridgevm.git
cd bridgevm
cargo build --workspace --locked
swift build --package-path apps/macos
packaging/macos/build-debug-app-bundle.sh
open target/macos/BridgeVMApp.app

QEMU is needed only for the Compatibility Engine. The self-contained Windows HVF bundle has additional host dependencies checked by its packaging scripts. See Contributing for focused setup and verification paths.

Three engines, three jobs

Engine	Backend	Use it for
Windows HVF	Hypervisor.framework + BridgeVM device model	Windows 11 Arm on Apple silicon; main engineering focus
Apple VZ	Virtualization.framework	Narrow, lightweight Linux/macOS Arm guests
Compatibility	QEMU + HVF/TCG	Broad guest support and architecture emulation

The Windows guest contract is QEMU virt-compatible with documented deviations; it is not described as a bit-for-bit QEMU implementation.

Contribute

Bug reports, documentation fixes, tests, and focused code changes are welcome. Start with a good first issue or run the fast deterministic gate:

scripts/check-project.sh --fast

Read CONTRIBUTING.md before a larger change. It explains the repository map, evidence levels, private-media boundary, formatting, tests, and how to choose between hosted CI and a real-hardware gate. Security issues belong in the private process described in SECURITY.md, not a public issue.

Project map

apps/macos/                  SwiftUI apps and signed helper boundaries
crates/bridgevm-hvf/         custom Hypervisor.framework VMM and devices
crates/bridgevm-hvf-runtime/ typed Windows HVF runtime lifecycle
crates/bridgevm-{cli,core}/  CLI and shared product model
runners/                     supervised VM-engine processes
packaging/macos/             app, DMG, and release verification
scripts/                     deterministic tooling and sealed live gates
tests/integration/           product-policy and integration checks
docs/                        current guides, decisions, and dated evidence

Documentation

• Install and update
• Distribution channels
• Current status
• Windows 11 Arm guide
• Security model
• Documentation index

Run the complete deterministic gate before treating a repository change as done:

scripts/check-project.sh

Real Windows boots, graphics workloads, Hypervisor.framework behavior, and clean-machine distribution behavior require the corresponding sealed live gate; hosted CI is not a substitute.

License

BridgeVM is licensed under Apache-2.0. Third-party components retain their own licenses; see THIRD-PARTY-NOTICES.md and the licensing guide.

Copyright © 2026 Ketchio-dev.