skylartaylor / gbos-vm

# gbos-vm
Runs a real Googlebook OS image in a VM on an Apple Silicon Mac — GPU-accelerated, with Chrome working.
It's not an emulator image or a generic Android build. The install script downloads Google's own recovery image for the Dell Googlebook (ARM64, Android 17), swaps the hardware-specific bits for virtual ones, and boots it under QEMU with Vulkan passed through to Metal.
> This isn't affiliated with Google or Dell, and it's not a verified Googlebook. Read System Structure before you sign into anything.
## Quick start
 [code] 
Then open the app it built:
 [code] 
Drag that into your Dock if you want it there. It boots the VM when you open it and shuts Android down properly when you quit.
The first boot takes about 45 seconds on a M5 MacBook. If you land on a user picker, click **User** — there's no password.
`install.sh` downloads about 9 GB and wants 60 GB free. On an M5 MacBook the build part takes around five minutes; the downloads take however long your connection takes.
## What you need
- An **Apple Silicon Mac**. Intel Macs won't work — this is an ARM guest running on the hypervisor, not emulation.
- **16 GB of RAM**, realistically. The VM gets 4 GB and the builds want a few more.
- **Xcode command line tools** and **Homebrew**.
- The **Android SDK** with an NDK, a build-tools version, and a platform (API 34+). Android Studio's defaults are fine. We build with NDK `28.2.13676358`; if you don't have that one the script uses your newest (30 is reported to work), or set `ANDROID_NDK` to pick.
- A **JDK**. If you have Android Studio, its bundled one gets picked up automatically.
- Optionally, the **Android Emulator** package from the SDK. Bluetooth borrows its virtual radio (see What doesn't work yet); without it the VM boots with no Bluetooth.
`install.sh` checks all of this before it downloads anything, and offers to install what's missing — the Homebrew packages, a JDK, and the Android pieces through Google's `sdkmanager` (you don't need Android Studio). It never asks for `sudo`. Run `./prereqs.sh` on its own to see where you stand.
We build and test on one machine (M5, 16 GB, macOS 27). A couple of people have reported it working on M4 Macs too — if you try it on something else, tell us how it went.
## Using it
| Shortcut | What it does |
|---|---|
| `⌃⌘F` | Full screen |
| `⌃⌘M` | Cycle pointer modes |
| `⌃⌥` | Release a captured mouse |
| `⌃⌘R` | Restart the VM |
| `⌘V` | Paste the Mac clipboard into the guest |
| `⌘,` | Settings |
Quitting (or closing the window) shuts Android down properly. Your data lives in `work/image/googlebook.raw` and sticks around between runs.
**Settings** (`⌘,`) has the pointer mode, resolution, memory, CPU cores, and toggles for networking, audio and Bluetooth. Pointer mode changes right away; everything else is a VM option, so it applies the next time you start it.
Resolution defaults to your display's native pixels at 16:10. On a notched MacBook that's exactly the area below the notch, so full screen