Cuttlefish on Mac: Running Android’s Virtual Device Framework Natively

Meta has ported the Android Open Source Project’s Cuttlefish virtual device framework and its QEMU backend natively to macOS on Apple silicon, as detailed in Meta Engineering's report. The engineering effort, spearheaded by Meta Reality Labs engineers Hadrien Zalek, Joe Knox, Alex Chong, and Marcel Apfelbaum, removes the historical Linux requirement that prevented local macOS developer machines from running the high-fidelity Android virtual device framework.

This breakdown examines how the team resolved Linux-specific assumptions inside QEMU and Cuttlefish, adapted device acceleration to Apple’s native hypervisor, and created open-source patches for Android platform and application developers. The resulting architecture gives local engineers building wearable software identical virtual device capabilities to continuous integration environments without maintaining separate emulator stacks.

01Linux fragmentation across dual emulator platforms

Developing non-phone Android hardware such as smart glasses relies on virtual devices that faithfully mirror real system software behavior. Previously, Meta Reality Labs maintained two separate tools: Goldfish, a lightweight emulator running across operating systems for app developers, and Cuttlefish, a high-fidelity system-image platform restricted to Linux hosts.

This split mirrored the division in upstream AOSP, where platform teams used Cuttlefish while application developers worked in Goldfish. Running both platforms drained computing resources, divided toolchain engineering capacity, and left bugs hidden until late stages when lower-fidelity Goldfish instances missed hardware-specific edge cases.

Engineers decided to unify the entire development environment on Cuttlefish so that local macOS developers run the exact virtual device used in central automation. Achieving parity required porting the orchestration layer and virtual machine monitor to run natively on Apple silicon hardware.

02Portable vhost-user backends and hypervisor limits

Cuttlefish serves as an orchestration engine, delegating guest operating system virtualization to a virtual machine monitor. While Linux deployments rely primarily on crosvm, Meta revived QEMU integration because of its cross-platform architecture and existing arm64 hardware support.

Many Cuttlefish virtual devices communicate over sockets using vhost-user backends to expose virtio hardware interfaces to QEMU. Because frontends, libvhost-user, and helper backends like vhost-user-blk were historically gated strictly to Linux, Meta modified build rules to enable cross-platform macOS compilation and runtime operation.

Acceleration on Apple silicon runs through Hypervisor.framework rather than Linux KVM. Meta encountered resource constraints where QEMU’s HVF backend could not track enough memory regions for larger Cuttlefish profiles, prompting engineers to raise the backend's memory tracking-slot allocation.

03Native Cocoa display and arm64 packaging

Interactive local development requires low-latency display access without routing video through WebRTC browser connections. The team updated QEMU’s native Cocoa interface to handle local rendering and direct window interactions on macOS desktops.

These Cocoa updates introduced BGRA pixel format support to remove visual rendering artifacts on Apple silicon graphics pipelines. Meta also implemented pointer-to-touch translation for touchscreen testing and added a custom geometry configuration flag to the graphic console initialization routine.

Graphics integration also required enabling unstable Rutabaga structures to match Rust-side graphics application binary interfaces in gfxstream environments. The packaging workflow added arm64 Darwin compilation targets, macOS host build configurations for Cuttlefish, code signing, notarization, and the JIT entitlement.

04Unified capabilities for teams and automated agents

Unifying on Cuttlefish eliminated redundant tooling while ensuring local development instances reproduce continuous integration behaviors exactly. The shared platform supports complex system features including Bluetooth pairing, Wi-Fi, cellular networks, 3D graphics rendering, Fastboot, over-the-air update testing, and rapid snapshot restoration.

External developers creating software for Meta's ecosystem receive identical virtual device builds, aligning third-party testing with internal operating system validation workflows. This environment parity prevents platform-specific drift between company engineers and ecosystem partners.

The infrastructure also accommodates automated AI agents handling code generation and system-level test execution. By running concurrent headless instances with instant state reset capabilities, software teams can automate validation loops repeatedly without depending on physical hardware availability.

05Open-source repositories and community distribution

Meta released the code publicly across two community distribution repositories rather than keeping the macOS adaptations internal. These resources allow external developers to adopt the Apple silicon integration directly on their own workstations.

The first repository, qemu-wearables, is a Meta-maintained QEMU fork containing all macOS hypervisor, display, and vhost-user patches. The second repository, cuttlefish-wearables, provides patch files alongside application instructions for standard Android Open Source Project source trees.

The engineering team credited Stefano Garzarella’s vsock-user implementation for enabling the macOS integration, alongside foundational development by Meta engineers Olya Arkhangelskaia, Tom Care, and Jeffrey Effendy. Meta is currently evaluating paths to contribute these modifications upstream into mainline QEMU and AOSP trees.