Device
Cuttlefish on Mac: Running AOSP's Virtual Device Framework Natively on Apple Silicon
Meta open-sourced Cuttlefish on Mac (qemu-wearables and cuttlefish-wearables), porting AOSP's canonical virtual-device framework to Apple Silicon via QEMU, Hypervisor.framework (HVF), portable vhost-user sockets, and a native Cocoa BGRA display. Get the architecture breakdown and pre-flight verification script.
8 min read
Cuttlefish on Mac: Running AOSP's Virtual Device Framework Natively on Apple Silicon
Executive Summary
On November 13, 2026, Meta's Reality Labs engineering team published Cuttlefish on Mac, detailing how it ported the Android Open Source Project's (AOSP) canonical virtual-device framework—Cuttlefish—to run natively on macOS and Apple Silicon (arm64). Previously restricted to Linux hosts via crosvm and KVM, Cuttlefish boots the exact same Android system images as physical hardware, making it essential for non-phone form factors such as Meta's AI glasses and wearables.
To eliminate the operational burden of maintaining two divergent emulator stacks—Goldfish (the lightweight Android Emulator for Mac app developers) alongside Cuttlefish (for Linux CI and platform engineers)—Meta revived Cuttlefish's dormant QEMU Virtual Machine Monitor (VMM) backend and solved three macOS-specific barriers:
- Portable
vhost-userIPC: Relaxed Linux-only build gates in QEMU'svhost-userfrontends,libvhost-user, and contrib backends (such asvhost-user-blk) so out-of-process virtio devices run over sockets on macOS. - Apple
Hypervisor.framework(HVF) Memory Slots: Increased memory-region tracking slots in QEMU's HVF backend to accommodate larger Cuttlefish device topologies. - Native Cocoa BGRA Display & Code Signing: Replaced WebRTC-only display reliance with QEMU's native Cocoa display (adding
BGRApixel format support, mouse-click-as-touch input, and-ggeometry options), enabled unstablegfxstream/rutabagaRust ABI structs, and added macOSarm64JIT entitlements, code signing, and notarization.
Meta released the work across two open-source repositories—facebookincubator/qemu-wearables and facebookincubator/cuttlefish-wearables—allowing third-party Android and wearable teams to test against the exact same virtual device used in CI.
Goldfish vs. Cuttlefish on Linux vs. Cuttlefish on Mac
Per Engineering at Meta and AOSP Cuttlefish architecture documentation:
| Dimension | Android Emulator (Goldfish) | Upstream AOSP Cuttlefish (Linux) | Meta Cuttlefish on Mac (Apple Silicon) |
|---|---|---|---|
| Target Audience | App developers | Android platform & CI teams | Unified app, platform, wearable & AI agent teams |
| Host OS Support | macOS, Linux, Windows | Linux (x86_64, ARM64) |
macOS (arm64 Apple Silicon) + Linux |
| VMM & Hypervisor | Custom external/qemu fork |
crosvm on Linux KVM |
qemu-wearables on Apple HVF |
| Guest-Host Transport | Goldfish qemu pipes |
virtio-vsock + vhost-user |
virtio-vsock (vsock-user) + portable vhost-user |
| Display Path | Qt frontend | WebRTC streamer (localhost:8443) |
Native Cocoa display (BGRA + touch) |
| Hardware Fidelity | App-level hooks | Full AOSP system-image parity | Full AOSP parity (BT, Wi-Fi, Cellular, 3D, OTA, Fastboot) |
Technical Mechanics and Architecture
How Meta Bridged the Linux-Only Assumptions in Cuttlefish
On Linux, Cuttlefish orchestrates a fleet of small host processes (assemble_cvd, run_cvd) that hand virtio devices to crosvm over vhost-user sockets and communicate with the Android guest over virtio-vsock. To run that same orchestration on Apple Silicon without rewriting Cuttlefish's device backends from scratch, Meta revived qemu_manager and ported the underlying QEMU/HVF/Cocoa stack:
+-----------------------------------------------------------------------------+
| CUTTLEFISH ON MAC: APPLE SILICON (ARM64) VIRTUALIZATION STACK |
+-----------------------------------------------------------------------------+
| |
| [ AOSP CUTTLEFISH ORCHESTRATION (cuttlefish-wearables macOS Host) ] |
| cvd start -> assemble_cvd -> run_cvd (Bluetooth, Wi-Fi, Cellular, OTA) |
| | |
| +---> Portable vhost-user Sockets (libvhost-user, vhost-user-blk, vsock)|
| | |
| v |
| [ META QEMU-WEARABLES (arm64 Darwin + JIT Entitlement + Notarized) ] |
| |-- Hypervisor Backend: Apple Hypervisor.framework (HVF) |
| | +-- Expanded memory-region tracking slots for full device configs |
| |-- Graphics Pipeline: gfxstream / rutabaga (Rust ABI structs enabled) |
| +-- Interactive UI: Native Cocoa Display (BGRA + Mouse-Click-as-Touch) |
+-----------------------------------------------------------------------------+
Four engineering details make this stack work on macOS:
- Unblocking
vhost-user&vsock-user: QEMU'svhost-userfrontends andlibvhost-userwere previously gated behind Linux preprocessor checks. By making them portable to Darwin—and building on Stefano Garzarella'svsock-userwork—Cuttlefish's out-of-process device daemons attach to QEMU on macOS identically to Linux. - Expanding HVF Memory-Region Slots: Apple's
Hypervisor.framework(HVF) enforces stricter resource tracking than Linux KVM. Larger Cuttlefish virtual device topologies exceeded QEMU's default HVF memory-region slot count until Meta raised the tracking-slot limit. - Fixing Cocoa
BGRA&rutabagaABI Alignment: To avoid WebRTC browser overhead during local iteration, Meta addedBGRApixel format support (eliminating color/rendering artifacts on Apple Silicon), mapped mouse clicks to touch events, added-ggeometry flags tographic_console_init, and enabled the unstablerutabagastructs needed to match the Rust-sidegfxstream/rutabagagraphics ABI. - Darwin Toolchain, JIT Entitlement & Notarization: Running dynamic translation or HVF-accelerated VMs on modern macOS requires explicit
com.apple.security.cs.allow-jitentitlements, properarm64Darwin toolchain flags, code signing, and Apple notarization.
Defensive & Reproducible Engineering Pattern: Pre-Flight Host & Entitlement Verification
Before building or deploying qemu-wearables and cuttlefish-wearables across developer MacBooks or CI runners, engineering teams should verify Apple Silicon architecture, Hypervisor.framework availability, repo tooling, and macOS code-signing entitlements in a read-only pre-flight script:
#!/usr/bin/env bash
set -euo pipefail
echo "=== Cuttlefish on Mac: Apple Silicon Pre-Flight Check ==="
# 1. Confirm arm64 Apple Silicon host
ARCH="$(uname -m)"
if [[ "${ARCH}" != "arm64" ]]; then
echo "[ERROR] Expected arm64 Apple Silicon host, found: ${ARCH}" >&2
exit 1
fi
# 2. Verify Hypervisor.framework support via sysctl
HV_SUPPORT="$(sysctl -n kern.hv_support 2>/dev/null || echo 0)"
if [[ "${HV_SUPPORT}" != "1" ]]; then
echo "[ERROR] kern.hv_support is ${HV_SUPPORT}; Hypervisor.framework unavailable." >&2
exit 1
fi
echo "[OK] Apple Silicon (${ARCH}) with Hypervisor.framework enabled."
# 3. Check required AOSP repo tool on PATH
if ! command -v repo >/dev/null 2>&1; then
echo "[WARN] AOSP 'repo' tool not found on PATH (required for cuttlefish-wearables)."
else
echo "[OK] repo tool found at: $(command -v repo)"
fi
# 4. Inspect signed QEMU binary for required JIT entitlement (if already built)
QEMU_BIN="${1:-}"
if [[ -n "${QEMU_BIN}" && -x "${QEMU_BIN}" ]]; then
codesign -d --entitlements - "${QEMU_BIN}" 2>/dev/null | grep -E "allow-jit|hypervisor" || \
echo "[WARN] Expected JIT/hypervisor entitlements not detected on ${QEMU_BIN}."
fi
Evidence: Capabilities, AI Agent Workflows, and Benchmark Caveats
- Unified Device Capabilities: Per Meta's November 13 engineering post, running Cuttlefish natively on Apple Silicon unifies local development and Linux CI across Bluetooth pairing and connectivity, Wi-Fi, Cellular, 3D graphics (
gfxstream/rutabaga), Over-the-Air (OTA) update testing, Fastboot, and instant state snapshotting. - AI Coding Agent Validation: Meta highlights that as AI agents take on a larger role in Android development, high-fidelity virtual devices with instant snapshot-and-reset cycles allow both human engineers and automated agents to run concurrent, isolated runtime validation without competing for scarce physical wearable hardware.
- Open-Source Distribution: Released across
facebookincubator/qemu-wearablesandfacebookincubator/cuttlefish-wearables(initial repository commits visible November 7, 2026; engineering announcement published November 13, 2026), with Meta exploring upstreaming the patches to QEMU and AOSP. - Confidence Level: High on architectural changes, supported subsystems, and open-source repository structure. Benchmark Caveat: Meta's November 13 post does not publish quantitative boot-time, frame-rate, or memory-footprint benchmarks comparing
qemu-wearables(Apple HVF) against Linuxcrosvm(KVM) or Goldfish. Teams migrating CI or local workflows should benchmark guest boot latency andgfxstreamframe times on their own target AOSP images.
Deployment & Hardening Playbook for Engineering Teams
Step 1: Clone Meta's qemu-wearables and cuttlefish-wearables Repositories
- Run the pre-flight check above on target Apple Silicon (
M-series) developer workstations (kern.hv_support == 1). - Build QEMU from
facebookincubator/qemu-wearablesforarm64Darwin first, ascuttlefish-wearablesrequiresqemu-wearablesfor native macOS emulation. - Sync your AOSP checkout using Android's
repotool onPATHand apply the patch series fromfacebookincubator/cuttlefish-wearables.
Step 2: Enforce Strict Code Signing, Notarization, and Sandbox Boundaries
Because qemu-wearables requires the com.apple.security.cs.allow-jit entitlement on macOS, distribute internal builds only as signed and notarized developer packages from your internal artifact registry—never allow developers to disable Gatekeeper or run unsigned hypervisor binaries downloaded from unverified mirrors.
Step 3: Isolate Virtualized Network & ADB Bridges for AI Agent Testing
When using Cuttlefish snapshots to validate AI-generated Android code:
- Bind
adband any WebRTC/Cocoa control ports to127.0.0.1(localhost) rather than0.0.0.0so virtual devices are not exposed on corporate Wi-Fi. - Isolate test guest Wi-Fi/Cellular virtual networks from internal corporate production networks, and reset guest snapshots between untrusted agent test runs.
Step 4: Validate OTA, Fastboot, and BGRA Display Parity Against Linux CI
Before retiring legacy Goldfish emulator configs, run your full instrumentation suite (including 3D gfxstream tests, Bluetooth pairing, and OTA flows) on both macOS qemu-wearables and Linux crosvm CI runners to confirm behavioral parity.
Step 5: Rollback Notes
Keep existing Goldfish emulator scripts and Linux crosvm CI targets intact behind a feature flag (for example, USE_CUTTLEFISH_MAC=1) during initial rollout. If a specific AOSP branch or macOS minor update hits an HVF memory-slot or rutabaga ABI mismatch, engineers can immediately fall back to Linux remote Cuttlefish instances or Goldfish without blocking PR merges.
Frequently Asked Questions
1. Why couldn't AOSP Cuttlefish run natively on macOS before?
Upstream Cuttlefish relies on crosvm (which uses Linux KVM) and Linux-gated vhost-user socket backends. Apple Silicon Macs use Hypervisor.framework (HVF) rather than KVM and lacked Darwin vhost-user, Cocoa BGRA display, and macOS code-signing support in the Cuttlefish QEMU path.
2. What is the difference between qemu-wearables and cuttlefish-wearables?
facebookincubator/qemu-wearables is Meta's maintained QEMU fork containing the macOS vhost-user, HVF memory-slot, and Cocoa display patches, while facebookincubator/cuttlefish-wearables provides the AOSP/Cuttlefish patch files and build instructions to orchestrate those virtual devices on macOS.
3. Does Cuttlefish on Mac still require WebRTC in a browser to see the screen?
No. While Linux Cuttlefish defaults to a WebRTC streamer on localhost:8443, Meta transitioned local Mac development to QEMU's native Cocoa display with BGRA pixel format support, mouse-click-as-touch input, and custom -g geometry options.
4. Which hardware features does Cuttlefish on Mac support?
Meta reports unified support for Bluetooth pairing and connectivity, Wi-Fi, Cellular, 3D graphics (gfxstream/rutabaga), Over-the-Air (OTA) update testing, Fastboot, and state snapshotting.
5. Did Meta publish speed or FPS benchmarks for Cuttlefish on Apple Silicon?
No. Meta's November 13, 2026 engineering post details the architectural changes and qualitative developer/CI benefits without publishing quantitative boot-time or GPU frame-rate benchmarks.
Sources
- Engineering at Meta: Cuttlefish on Mac: Running Android's Virtual Device Framework Natively on Apple Silicon — Published November 13, 2026.
- GitHub
facebookincubator/cuttlefish-wearables: Patches and tools for running Android's Cuttlefish natively on macOS and Apple silicon — Published November 2026. - GitHub
facebookincubator/qemu-wearables: QEMU fork supporting Meta Wearables device emulation — Published November 2026. - Android Open Source Project (AOSP): Cuttlefish Virtual Android Devices — Updated September 22, 2026.
Upstream Context: qemu_manager.cpp vs. crosvm_manager.cpp
In AOSP's device/google/cuttlefish/host/libs/vm_manager/ tree, GetVmManager selects between kCrosvm, kQemu, and kGem5 modes, with crosvm_manager.cpp serving as the default Linux production path (each virtio device isolated in a seccomp jail) and qemu_manager.cpp acting as the sibling QEMU integration. Reviving that sibling QEMU path—combined with portable vhost-user sockets and Apple HVF memory-slot expansion—enabled Meta to bring Cuttlefish to macOS without rewriting guest system images.