Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions LICENSE
Original file line number Diff line number Diff line change
Expand Up @@ -75,5 +75,5 @@ The **licensor** is the individual or entity offering these terms, and the **sof
Required Notice: Copyright 2026 TUNA-NOPE (https://github.com/TUNA-NOPE)

Scope: these terms cover macbox's own files. The files in patches/ modify Reims vGPU and metal2vulkan,
which are GPL-2.0-or-later OR LGPL-3.0-or-later, and are offered under those same terms
(patches/README.md). The projects macbox builds and downloads keep their own licenses (CREDITS.md).
which are GPL-2.0-or-later OR LGPL-3.0-or-later, and are offered under those same terms; those in
patches/qemu modify QEMU and are GPL-2.0-or-later (patches/README.md). The projects macbox builds and downloads keep their own licenses (CREDITS.md).
51 changes: 32 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,10 @@ own. One command, `macbox`, sets it up and runs it.
**Website and guides:** [tuna-nope.github.io/macbox](https://tuna-nope.github.io/macbox/): macOS, Xcode and
the iOS Simulator on Linux, Expo apps, the GPU path, and AI coding agents with T3 Code.

![The macOS desktop in macbox, with two iOS 26.5 Simulators: a Liquid Glass benchmark at 1x and Safari](docs/images/hero.jpg)
![The macOS 26 desktop in macbox on Linux: Simulator.app shows an iPhone 17 Pro running Nimbus, a weather app, next to Nimbus's website in Safari](docs/images/hero.jpg)

<sub>macOS 26 Tahoe's desktop in macbox on an Intel iGPU, with two of its iOS 26.5 Simulators in front
(their screens composited onto the desktop's screenshot): GlassBench, a Liquid Glass load, and
Safari.</sub>
<sub>macOS 26 Tahoe's desktop in macbox on an Intel iGPU, captured as it is: Simulator.app with an
iPhone 17 Pro on iOS 26.5 running Nimbus, a weather app, beside its website in Safari.</sub>

```
Linux host (KVM + a Vulkan GPU + Docker)
Expand All @@ -28,8 +27,8 @@ Linux host (KVM + a Vulkan GPU + Docker)
- **macOS draws on your GPU.** [Reims vGPU](https://github.com/steelbrain/reims-vgpu) gives QEMU
Apple's paravirtual GPU, and macOS's own driver talks to it, so Metal works with no guest
driver. [metal2vulkan](https://github.com/steelbrain/metal2vulkan) runs Metal's work on Vulkan.
macbox builds both, with patches that roughly doubled the iOS Simulator's frame rate on the
GPU it was measured on (see [Performance](#performance)).
macbox builds both, with patches that took a 3x iOS Simulator from 17 to 50 fps on the GPU it
was measured on, and to 70 with the experimental Coherent switch (see [Performance](#performance)).
- **The screen** opens in a window on your Linux desktop, or in a browser tab (Selkies: H.264 on
the GPU, its bitrate following the link). Agents can see it and click and type into it
(`macbox screenshot`, `click`, `type`), so an agent can drive the macOS installer too.
Expand Down Expand Up @@ -91,19 +90,32 @@ floating glass toolbar, counted at the simulator's own screen (frames per second

<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/images/fps-dark.svg">
<img alt="iOS Simulator frame rate, Liquid Glass benchmark: 1x 53.5 to 94.2 fps, 2x 33.5 to 64.2, 3x 17.2 to 39.0, Reims as upstream shipped it vs the macbox build" src="docs/images/fps-light.svg" width="760">
<img alt="iOS Simulator at 3x, Liquid Glass benchmark: 17.2 fps as upstream shipped it, 39.0 with the October 28 macbox build, 50.6 with the cohwl build, 70.0 with Coherent on" src="docs/images/fps-light.svg" width="760">
</picture>

| | Reims 2ce3209, as upstream shipped it on 2026-10-26 | macbox build |
|---|---|---|
| iOS Simulator 1x (402x874), glass | 53.5 | **95.8 / 92.5** |
| iOS Simulator 2x (804x1748), glass | 33.5 | **67.8 / 60.5** |
| iOS Simulator 3x (1206x2622, an iPhone's pixels), glass | 17.2 | **38.5 / 39.5** |
| Safari at 3x, a page with a blurred floating bar | n/a | 66.4 / 64.2 |
| macOS desktop, Genie minimize at 3440x1440 (frames per animation) | ~12 | 19.5 |

The GPU is the limit: a 3x simulator keeps this iGPU 96 to 98% busy. On a faster GPU every number
moves up. [docs/performance.md](docs/performance.md) has what the patches do, the method, what
| iOS Simulator at 3x (1206x2622, an iPhone's pixels), glass | fps |
|---|---|
| Reims 2ce3209, as upstream shipped it on 2026-10-26 | 17.2 |
| macbox, 2026-10-28: rendering guest-RAM textures in place | 38.5 / 39.5 |
| **macbox build now** (cohwl, 2026-11-05) | **50.6** (p95 21 ms) |
| macbox build with `MACBOX_COHERENT=on` (experimental) | **70.0** (p95 18 ms) |

| | Reims 2ce3209 | macbox, 2026-10-28 | macbox now, Coherent on |
|---|---|---|---|
| iOS Simulator 1x (402x874), glass | 53.5 | 95.8 / 92.5 | not measured yet |
| iOS Simulator 2x (804x1748), glass | 33.5 | 67.8 / 60.5 | not measured yet |
| macOS desktop, dragging a window (presents/s) | | 105 (Coherent off) | 130 |
| macOS desktop, Safari scrolling (presents/s) | | 75–79 (Coherent off) | 110 |
| macOS desktop, Genie minimize at 3440x1440 (frames per animation) | ~12 | 19.5 | 29.5 / 30.5 |

Coherent keeps the GPU's image of the simulator's and the desktop's surfaces ahead of guest RAM,
and syncs a page only when the guest's CPU touches it: the copies that were left are gone, and the
GPU drops from 97% to 70% busy at 3x. It is off by default for now: it hung the GPU once on its
first day of daily use (the next boot came up without it, as designed), and the cause isn't
settled. [docs/performance.md](docs/performance.md#coherent-experimental-off-by-default) has the details.

The GPU is the limit: without Coherent a 3x simulator keeps this iGPU 96 to 98% busy. On a faster
GPU every number moves up. [docs/performance.md](docs/performance.md) has what the patches do, the method, what
didn't help, and the known limits (an idle macOS display gets no vblank from its driver, so an
animation starts about 0.1 s late: [reims-vgpu#141](https://github.com/steelbrain/reims-vgpu/issues/141)).

Expand Down Expand Up @@ -177,7 +189,7 @@ issue or PR. See [CONTRIBUTING.md](CONTRIBUTING.md) for a few simple guidelines.
| [docs/agents.md](docs/agents.md) | the agent tools, the skill, the instructions to give agents |
| [docs/troubleshooting.md](docs/troubleshooting.md) | when something doesn't work |
| [guest/README.md](guest/README.md) | what runs inside macOS |
| [patches/README.md](patches/README.md) | the patch series on Reims vGPU and metal2vulkan |
| [patches/README.md](patches/README.md) | the patch series on Reims vGPU, metal2vulkan and QEMU |
| [site/](site/README.md) | the website's source: the guides at https://tuna-nope.github.io/macbox/guides/ |

## Credits
Expand All @@ -194,7 +206,8 @@ purpose: yourself, a hobby, research, teaching, a school, a charity, a public bo
needs the author's permission**: open an issue to ask.

The patches in `patches/` modify Reims vGPU and metal2vulkan, and stay under those projects' terms,
`GPL-2.0-or-later OR LGPL-3.0-or-later` ([patches/README.md](patches/README.md)). Everything macbox
`GPL-2.0-or-later OR LGPL-3.0-or-later`; those in `patches/qemu` modify QEMU and are
`GPL-2.0-or-later` ([patches/README.md](patches/README.md)). Everything macbox
builds or downloads keeps its own license ([CREDITS.md](CREDITS.md)).

## Disclaimer
Expand Down
2 changes: 2 additions & 0 deletions container/build-reims.sh
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@ else
git -C "$R" submodule update -q --init vendor/qemu
git -C "$R/vendor/qemu" fetch -q origin "$QEMU_REF" 2>/dev/null || true
git -C "$R/vendor/qemu" checkout -q -f --detach "$QEMU_REF"
git -C "$R/vendor/qemu" am --abort >/dev/null 2>&1 || true
apply "$R/vendor/qemu" "$MACBOX_REPO/patches/qemu"
SUFFIX=-macbox
fi
COMMIT=$(git -C "$R" rev-parse --short HEAD)
Expand Down
10 changes: 6 additions & 4 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ It runs with seccomp and AppArmor unconfined, because passt needs a user namespa

`container/build-reims.sh` (run by `macbox build` in a throwaway container) checks out Reims vGPU,
QEMU and metal2vulkan at the commits [versions.env](../versions.env) pins, applies
[patches/](../patches/README.md), points Reims's Cargo at the patched metal2vulkan, and builds
[patches/](../patches/README.md) to each of the three, points Reims's Cargo at the patched metal2vulkan, and builds
`reims-ctl`, the library (`cargo xtask dist --platform vulkan`) and QEMU on it. Each QEMU goes into
`~/.local/share/reims-ctl/qemu/<date>-<commit>-macbox` and `qemu/current` moves to it. A running VM
keeps its QEMU until it restarts, and old builds stay for going back
Expand All @@ -59,8 +59,10 @@ and the QEMU command line; `reims-ctl command mac` (inside the container) prints
- `--video-acceleration=false` (no VideoToolbox/M2 scaler devices), a borderless window,
`REIMS_VGPU_STATS=1` (a line of frame statistics a second in `logs/qemu.log`).
- Before each start: `WAYLAND_DISPLAY` (sway's, or the host's), and the GPU tuning:
`M2V_LIVE=$MACBOX_HOME/run/live.conf` with `host_rt_in_place=1`, and `M2V_ARL_FACTS` on an
Arrow Lake GPU ([performance.md](performance.md)).
`M2V_LIVE=$MACBOX_HOME/run/live.conf` with `host_rt_in_place=1`,
`REIMS_VGPU_PRIVATE_SKIP_PAGE_UP=1`, `M2V_ARL_FACTS` on an Arrow Lake GPU, and with
`MACBOX_COHERENT=on` the census and Coherent switches ([performance.md](performance.md)).
The disk's options in `extra_args` are written again, so a changed `MACBOX_DISK_CACHE` applies.

The system disk starts on SATA, because macOS's installer may not find a disk on NVMe, and moves to
NVMe with `macbox disk nvme` once macOS is installed.
Expand Down Expand Up @@ -130,7 +132,7 @@ versions.env the pinned upstream commits
docker/ the image (Dockerfile, sway.conf)
container/ scripts that run inside the container: build-reims.sh, display-up.sh, stream-up.sh
lib/vmctl.py screenshots, mouse and keyboard through QMP
patches/ the series on Reims vGPU and metal2vulkan
patches/ the series on Reims vGPU, metal2vulkan and QEMU
guest/ everything copied into macOS (macbox-guest and its tools)
sims/ the agent tools on the host (mac-sim, sim-fps, android-sim) and their user units
skills/ the simulators, phone-builds and macbox (setup) skills
Expand Down
69 changes: 32 additions & 37 deletions docs/images/fps-dark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading