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 CONTRIBUTING.md → .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ what changed and what was actually verified, just like any other PR.

Do not share credentials, personal information, or confidential logs. Contributed code
and assets must be yours to submit. macbox's own code and documentation use the
[PolyForm Noncommercial License](LICENSE); upstream patches under
[`patches/`](patches/README.md) retain their separate licenses. Do not include
[PolyForm Noncommercial License](../LICENSE); upstream patches under
[`patches/`](../src/patches/README.md) retain their separate licenses. Do not include
Apple software or other proprietary binaries.

Thanks for contributing, whatever the size or topic.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ Share the use case or problem this would solve.

Links, prototypes, experiments, patches, examples, or anything else relevant.

No implementation required. All ideas are welcome. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
No implementation required. All ideas are welcome. See [CONTRIBUTING.md](../CONTRIBUTING.md).
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/improvement_or_experiment.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,4 +24,4 @@ Hardware, OS, versions, dependencies or other setup details.

Even partial experiments are welcome. If you have a working change, you can also
[open a pull request](https://github.com/TUNA-NOPE/macbox/pulls).
See [CONTRIBUTING.md](../../CONTRIBUTING.md).
See [CONTRIBUTING.md](../CONTRIBUTING.md).
10 changes: 5 additions & 5 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Builds the website (site/) and publishes it to GitHub Pages: https://tuna-nope.github.io/macbox/
# Builds the website (docs/site/) and publishes it to GitHub Pages: https://tuna-nope.github.io/macbox/
# Pull requests only build and check it; pushes to main deploy it, then tell IndexNow (Bing and
# others) which pages exist. Google reads the sitemap through Search Console.
name: Website

on:
push:
branches: [main]
paths: ["site/**", "docs/images/**", "llms.txt", "macbox", "sims/bin/mac-sim", ".github/workflows/pages.yml"]
paths: ["docs/site/**", "docs/images/**", "macbox", "src/sims/bin/mac-sim", ".github/workflows/pages.yml"]
pull_request:
paths: ["site/**", "docs/images/**", "llms.txt", "macbox", "sims/bin/mac-sim", ".github/workflows/pages.yml"]
paths: ["docs/site/**", "docs/images/**", "macbox", "src/sims/bin/mac-sim", ".github/workflows/pages.yml"]
workflow_dispatch:

permissions:
Expand All @@ -27,11 +27,11 @@ jobs:
with:
python-version: "3.13"
- name: Build and check
run: python3 site/build.py
run: python3 docs/site/build.py
- uses: actions/upload-pages-artifact@v5
if: github.event_name != 'pull_request'
with:
path: site/_site
path: docs/site/_site

deploy:
if: github.event_name != 'pull_request'
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ panel. You can do almost all of it yourself, including the steps in macOS's GUI.
macbox welcomes contributions of any kind from users and coding agents: issues, ideas,
new features, bug fixes, performance work, documentation, experiments, and more.
If you identify or create a useful improvement while working with a user, point them
to [CONTRIBUTING.md](CONTRIBUTING.md), and offer to prepare an
to [CONTRIBUTING.md](.github/CONTRIBUTING.md), and offer to prepare an
[issue](https://github.com/TUNA-NOPE/macbox/issues/new/choose) or
[pull request](https://github.com/TUNA-NOPE/macbox/pulls).
Do not publish an issue or PR on the user's behalf without their authorization;
Expand Down
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
Expand Up @@ -76,4 +76,4 @@ 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; 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).
src/patches/qemu modify QEMU and are GPL-2.0-or-later (src/patches/README.md). The projects macbox builds and downloads keep their own licenses (docs/credits.md).
245 changes: 67 additions & 178 deletions README.md

Large diffs are not rendered by default.

10 changes: 5 additions & 5 deletions docs/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ measure.
|---|---|
| `mac-sim`, `mac-sim-remote`, `sim-fps`, `android-sim`, `android-gpu-desktop`, `phone-build`, `macbox` | links in `~/.local/bin` |
| the `simulators`, `phone-builds` and `macbox` skills | links in `~/.claude/skills` and `~/.agents/skills` |
| the "Simulators" section of the instructions ([agents/simulators-snippet.md](../agents/simulators-snippet.md)) | between `<!-- macbox:simulators -->` markers in `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md` (each backed up as `.bak-macbox`) |
| the "Simulators" section of the instructions ([src/agents/simulators-snippet.md](../src/agents/simulators-snippet.md)) | between `<!-- macbox:simulators -->` markers in `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md` (each backed up as `.bak-macbox`) |
| `mac-sim-idle.timer` | a user unit, enabled: idle pool simulators shut down after 20 minutes |

Optional: a Claude Code hook that reminds the agent of the skill whenever a prompt mentions a
simulator ([agents/README.md](../agents/README.md)). `./macbox agents uninstall` removes the links
simulator ([src/agents/README.md](../src/agents/README.md)). `./macbox agents uninstall` removes the links
and the timer (it leaves the instructions).

## What an agent does with it
Expand All @@ -35,7 +35,7 @@ mac-sim record /tmp/a.mp4 10 & ...; wait; sim-fps /tmp/a.mp4 # record a flow,
mac-sim down # give it back
```

The [simulators skill](../skills/simulators/SKILL.md) is the rulebook: which simulator for what, how
The [simulators skill](../src/skills/simulators/SKILL.md) is the rulebook: which simulator for what, how
to show it to the user in T3 Code's Device panel, and the loop to run after every UI change. Run
it, screenshot it and look, record the whole flow, and check with `sim-fps` that every stretch of
motion held 60 fps with no dropped frames. Then inspect the frames. Measure motion on a 1x
Expand All @@ -62,7 +62,7 @@ android-sim up && android-sim run && android-sim shot /tmp/a.png && android-sim

It needs the Android SDK (`ANDROID_HOME`, default `~/Android/Sdk`, with cmdline-tools), a JDK 17 for
builds, `/dev/kvm`, and agent-device. For GPU rendering, `android-gpu-desktop` runs a hidden sway
with Xwayland on the GPU for the emulators (`sims/systemd/android-gpu-desktop.service`); without it
with Xwayland on the GPU for the emulators (`src/sims/systemd/android-gpu-desktop.service`); without it
they render in software. Settings are in the same config file:

| Setting | Default |
Expand All @@ -77,4 +77,4 @@ they render in software. Settings are in the same config file:
The `phone-builds` skill and `phone-build` cover builds for a real device: an `.ipa` for an iPhone,
TestFlight, an `.apk`. It uses Expo's EAS while the month's free cloud builds last, then builds
locally: Android on the host, iOS in the macOS VM. iOS device builds need a paid Apple Developer
Program membership. See [skills/phone-builds/SKILL.md](../skills/phone-builds/SKILL.md).
Program membership. See [src/skills/phone-builds/SKILL.md](../src/skills/phone-builds/SKILL.md).
38 changes: 20 additions & 18 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ host (Linux, KVM, a Vulkan GPU)

## The container

One image, `macbox:run` ([docker/Dockerfile](../docker/Dockerfile)), builds and runs everything:
One image, `macbox:run` ([src/docker/Dockerfile](../src/docker/Dockerfile)), builds and runs everything:
Ubuntu 26.10 (for Mesa 26.2 and Python 3.14), the build tools for Reims vGPU and QEMU, and the run
stack (passt, sway, wayvnc, noVNC, VA-API drivers). Selkies installs into a venv under
`MACBOX_HOME` on first use.
Expand All @@ -38,9 +38,9 @@ It runs with seccomp and AppArmor unconfined, because passt needs a user namespa

## Builds

`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) to each of the three, points Reims's Cargo at the patched metal2vulkan, and builds
`src/container/build-reims.sh` (run by `macbox build` in a throwaway container) checks out Reims vGPU,
QEMU and metal2vulkan at the commits [src/versions.env](../src/versions.env) pins, applies
[patches/](../src/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 Down Expand Up @@ -86,14 +86,14 @@ Selkies follow it.

## Driving the GUI

`macbox screenshot | click | move | scroll | type | key | wait` run [lib/vmctl.py](../lib/vmctl.py)
`macbox screenshot | click | move | scroll | type | key | wait` run [src/lib/vmctl.py](../src/lib/vmctl.py)
in the container against QEMU's QMP socket: screendumps, and absolute mouse and keyboard events. That
is enough for an agent to install macOS, go through Setup Assistant and turn on SSH by itself.
`type -` reads the text from stdin, so a password never shows in a process list.

## The guest

Everything inside macOS comes from [guest/](../guest/README.md), copied to `~/.macbox` by
Everything inside macOS comes from [guest/](../src/guest/README.md), copied to `~/.macbox` by
`macbox provision` and run as `~/.macbox/macbox-guest <step>` over SSH. Each step is idempotent.

## The simulators
Expand Down Expand Up @@ -129,17 +129,19 @@ path, name and size is a setting there, so two macboxes on one host only need di

```
macbox the CLI
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, 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
agents/ the instructions snippet and the Claude Code hook
bench/ the benchmark tools (simfps, GlassBench, GenieBench)
docs/ these documents; docs/images: the README's pictures and make-chart.py
llms.txt, AGENTS.md entry points for language models and for an agent setting macbox up
AGENTS.md the entry point for an agent setting macbox up
src/versions.env the pinned upstream commits
src/docker/ the image (Dockerfile, sway.conf)
src/container/ scripts that run inside the container: build-reims.sh, display-up.sh, stream-up.sh
src/lib/vmctl.py screenshots, mouse and keyboard through QMP
src/patches/ the series on Reims vGPU, metal2vulkan and QEMU
src/guest/ everything copied into macOS (macbox-guest and its tools)
src/sims/ the agent tools on the host (mac-sim, sim-fps, android-sim) and their user units
src/skills/ the simulators, phone-builds and macbox (setup) skills
src/agents/ the instructions snippet and the Claude Code hook
src/bench/ the benchmark tools (simfps, GlassBench, GenieBench)
docs/ these documents; docs/images: the pictures, the logo and make-chart.py
docs/site/ the website and llms.txt
.github/ the website's workflow, issue templates, CONTRIBUTING.md
```

2 changes: 1 addition & 1 deletion CREDITS.md → docs/credits.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,4 @@ the frames) follows the principles of [Appllama](https://appllama.io)'s app desi
## Apple

macOS, Xcode and the iOS Simulator runtimes are Apple's, downloaded from Apple under Apple's
terms; macbox contains none of them. See the legal note in the [README](README.md#disclaimer).
terms; macbox contains none of them. See the legal note in the [README](../README.md#disclaimer).
19 changes: 19 additions & 0 deletions docs/images/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/social-preview.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Before macbox's patches, most of that added work was copies: macOS's framebuffer
simulator's display surface lie in guest RAM, and metal2vulkan copied each into a GPU image and back
around every render pass. Those shadow copies were 51% of all GPU time with the simulator and 67%
with the desktop. Patch 0004 renders those textures in place, and Coherent (patches 0009 onwards,
with QEMU's census) removes most of the copies left ([patches/README.md](../patches/README.md)).
with QEMU's census) removes most of the copies left ([src/patches/README.md](../src/patches/README.md)).
What is left of a 3x simulator frame, measured with the pass timer on 2026-11-09:

| GPU time per 3x frame (~7.7–8.2 ms) | ms | |
Expand Down Expand Up @@ -104,7 +104,7 @@ Inside macOS, emulated SATA → NVMe: a warm 4K random read 0.54 → 0.36 ms, an
latency again.

How they were measured:
- `simfps` (in `guest/bench`, if present) counts the frames a simulator's screen produces through
- `simfps` (in `src/guest/bench`, if present) counts the frames a simulator's screen produces through
CoreSimulator's framebuffer, with no encoder in the way.
- GPU time per frame from QEMU's DRM fdinfo.
- Warm-up pass first; nothing else animating; Simulator.app closed.
Expand Down
6 changes: 3 additions & 3 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Fix every FAIL. WARN lines are advice.

This builds the Docker image (`macbox:run`: Ubuntu 26.10, Mesa, sway, passt, the stream's
dependencies), then, in a container, Reims vGPU and its QEMU on metal2vulkan with macbox's patches
([patches/README.md](../patches/README.md)), and `reims-ctl` and `reims-util`. The first build
([src/patches/README.md](../src/patches/README.md)), and `reims-ctl` and `reims-util`. The first build
takes 20 to 60 minutes and about 25 GB; later ones are incremental. `./macbox build --upstream`
builds Reims's current master as it is, without macbox's patches.

Expand Down Expand Up @@ -154,7 +154,7 @@ up to twice as fast. OpenCore finds the disk by itself.
./macbox provision
```

Copies `guest/` to `~/.macbox` on the Mac and runs it ([guest/README.md](../guest/README.md)):
Copies `guest/` to `~/.macbox` on the Mac and runs it ([src/guest/README.md](../src/guest/README.md)):
passwordless sudo (it asks for the password once), no sleep or screen lock, Spotlight indexing and
automatic update downloads off, Node, Ruby 3.4 and CocoaPods, simslim, the `setmode` tool, and the
LaunchAgent that keeps the Device panel's stream light. Safe to run again.
Expand Down Expand Up @@ -212,7 +212,7 @@ hub's own source. Run it again after T3 updates its hub. [docs/t3-code.md](t3-co

Links `mac-sim`, `sim-fps`, `android-sim` and `macbox` into `~/.local/bin`, the `simulators` (and
`phone-builds`) skill into `~/.claude/skills` and `~/.agents/skills`, and enables the timer that
shuts idle simulators down. Add [agents/simulators-snippet.md](../agents/simulators-snippet.md) to your
shuts idle simulators down. Add [src/agents/simulators-snippet.md](../src/agents/simulators-snippet.md) to your
`~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. [docs/agents.md](agents.md) explains it.

Check it from any Expo app's checkout:
Expand Down
File renamed without changes.
18 changes: 7 additions & 11 deletions site/README.md → docs/site/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,19 @@ nothing to install) and published to GitHub Pages by `.github/workflows/pages.ym
to main that touches it.

```sh
python3 site/build.py # build into site/_site and check it
python3 site/build.py --serve # the same, then http://127.0.0.1:8000/macbox/
python3 docs/site/build.py # build into docs/site/_site and check it
python3 docs/site/build.py --serve # the same, then http://127.0.0.1:8000/macbox/
```

| | |
|---|---|
| `pages/` | one HTML fragment per page. A header of `key: value` lines, then `---`. The file's path is the URL: `pages/guides/xcode-on-linux.html` is `/guides/xcode-on-linux/` |
| `pages/` | one HTML fragment per page (the home page and the 404). A header of `key: value` lines, then `---`. The file's path is the URL |
| `layout.html`, `style.css` | the frame around every page; the CSS is inlined |
| `static/` | copied as is: the favicon, the IndexNow key, search engines' verification files, and the home page's pictures in `static/images/`: `desk-*` is a real, uncropped capture of the macOS VM's whole screen (1600x1200: Simulator.app running Nimbus, a demo weather app made for these pictures, next to its website in Safari), saved as `-quality 84 desk-1600.webp`, `-resize 800x -quality 82 desk-800.webp` and `-quality 84 -interlace JPEG desk-1600.jpg`; `phone-today.webp` and `phone-cities.webp` are Nimbus's two screens from `mac-sim shot` on the 3x `sharp` simulator, `-resize 600x -quality 86`. The logos on the home page are inline SVG: Claude's from Simple Icons, OpenAI's and T3 Code's from T3 Code's repository) |
| `static/` | copied as is: the favicon, the IndexNow key, search engines' verification files, and the home page's pictures in `static/images/`: `desk-*` is a real, uncropped capture of the macOS VM's whole screen (1600x1200: Simulator.app running Nimbus, a demo weather app made for these pictures, next to its website in Safari), saved as `-quality 84 desk-1600.webp`, `-resize 800x -quality 82 desk-800.webp` and `-quality 84 -interlace JPEG desk-1600.jpg`; the favicon is `docs/images/logo.svg`. The logos on the home page are inline SVG: Claude's from Simple Icons, OpenAI's and T3 Code's from T3 Code's repository) |

The repo stays the source of truth. The guides answer one question each and link to `docs/` for the
full reference; pictures (`docs/images`) and `llms.txt` are copied from the repo at build time, not
kept twice. When a command or a number changes in the docs, change it in the guides that show it.

**Adding a guide:** a new file in `pages/guides/` with `title`, `short` (the breadcrumb),
`description` (50 to 165 characters, unique), `kind: guide`, `order` and `updated: YYYY-MM-DD`.
The guide lists, the sitemap and the structured data pick it up. Add it to `llms.txt` too.
The site is one page on purpose: what macbox is, the picture, and how to set it up. Everything
else lives in the repo's docs. The logo, the social preview and `llms.txt` are copied from the repo
at build time (`docs/images`, `docs/site/llms.txt`), not kept twice.

**The build fails on:** a broken internal link or `#anchor`, a missing or duplicate title or
description, a page without exactly one `<h1>`, and a `macbox <command>` or `mac-sim <command>` in
Expand Down
Loading
Loading