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
30 changes: 30 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ You're asked to give this Linux host a macOS VM with Xcode, iOS Simulators and T
panel. You can do almost all of it yourself, including the steps in macOS's GUI. Work through
`./macbox next` until every line is ticked; [docs/setup.md](docs/setup.md) explains each step.

If macbox is already installed and you're asked to update it, skip to [Updating](#updating).

## Sharing improvements upstream

macbox welcomes contributions of any kind from users and coding agents: issues, ideas,
Expand Down Expand Up @@ -78,3 +80,31 @@ mac-sim up && mac-sim run && mac-sim shot /tmp/home.png && mac-sim down

Look at `/tmp/home.png`. If the user runs T3 Code, open the simulator in their Device panel with
`device_open`, using the ids `mac-sim t3` prints.

## Updating

You're asked to bring an existing install to the latest version. The user's VM, simulators and
config stay; only macbox's checkout, its build and its links change.

1. Find the checkout: `readlink -f "$(command -v macbox)"` points into it. `git status` there: if
there are local changes, show them to the user and ask before you stash or drop anything.
2. `git log -1 --format=%h` (note it, to go back), then `git pull --ff-only`. Read what changed:
`git log --oneline ORIG_HEAD..`.
3. `./macbox agents install`: tools, skills and user units are links into the checkout, and files
can move between versions (they moved to `src/` in November 2026).
4. `./macbox doctor`. Anything it reports about the host: show the user the commands and ask.
5. If `git diff --stat ORIG_HEAD -- src/versions.env src/patches` shows anything, run
`./macbox build` in the background (20 to 60 minutes) and report progress. The running VM keeps
its QEMU until it restarts.
6. Config: compare `~/.config/macbox/macbox.env` with the defaults in docs/setup.md ("2. Config
and checks"). Values `macbox init` wrote earlier stay as they were: `MACBOX_COHERENT=off` there
is what `init` wrote before the default became `auto` (on with an Arrow Lake iGPU). Tell the user what differs and ask before you change it.
7. Ask the user when the VM may restart: it closes the simulators and apps running in macOS. Then
`./macbox down && ./macbox up`.
8. Check: `./macbox status`, `./macbox coherent status`, `./macbox next` (every line still
ticked), and the end-to-end check under "When you're done". Tell the user the old and new
commit, and what the release changed.

If the new build misbehaves, go back: point `qemu/current` in
`$MACBOX_HOME/home/.local/share/reims-ctl/qemu/` at the previous build (they stay installed), or
`git checkout <old commit>` and `./macbox build`, then restart.
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,17 @@ git clone https://github.com/TUNA-NOPE/macbox && cd macbox
`macbox next` walks you through the rest: installing macOS, Xcode, the simulator pool and the
agent tools. [docs/setup.md](docs/setup.md) has every step.

## Update

Already running macbox? Give your agent this:

```
Update macbox on this machine to the latest version: https://github.com/TUNA-NOPE/macbox. Follow the "Updating" section of its AGENTS.md and ask me before you restart the VM or change the host.
```

It pulls the new version, links the tools again, rebuilds if the GPU stack changed, and restarts the
VM when you say so. By hand: [docs/setup.md, Updating](docs/setup.md#updating).

## Performance

<picture>
Expand Down
33 changes: 33 additions & 0 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,39 @@ mac-sim up && mac-sim run && mac-sim shot /tmp/home.png && mac-sim down
`android-sim` runs a pool of Android emulators on the host itself, with KVM and the GPU. It needs
the Android SDK; see [docs/agents.md](agents.md#android).

## Updating

New versions come as commits on `main`. With an agent, paste this:

```
Update macbox on this machine to the latest version: https://github.com/TUNA-NOPE/macbox. Follow the "Updating" section of its AGENTS.md and ask me before you restart the VM or change the host.
```

By hand, in the checkout:

```sh
git status # local changes? keep them aside first (git stash)
git pull --ff-only
./macbox agents install # links the tools, skills and units again (paths change between versions)
./macbox doctor
git diff --stat ORIG_HEAD -- src/versions.env src/patches # anything here: rebuild
./macbox build # 20 to 60 minutes; the running VM keeps its QEMU meanwhile
./macbox down && ./macbox up # the new build and switches; closes what runs in the VM
./macbox status && ./macbox coherent status
```

- **Your config stays yours.** `~/.config/macbox/macbox.env` keeps the values `macbox init` wrote,
so a new default doesn't reach you by itself. Compare it with the table in
[2. Config and checks](#2-config-and-checks). For example, `MACBOX_COHERENT=off` in it is what `init` wrote
before the default became `auto`, which turns on Coherent and the switches measured with it on
an Arrow Lake iGPU.
- **Nothing inside macOS needs redoing** unless the release notes say so (then `./macbox provision`).
After a T3 Code update, run `./macbox t3 fix-hub` again, as always.
- **Going back:** every build stays installed beside the others in
`$MACBOX_HOME/home/.local/share/reims-ctl/qemu/`, and `qemu/current` points at the one that
starts. Point it at the previous one (`ln -sfn <id> .../qemu/current`), or check out the previous
commit and `./macbox build`, then `./macbox down && ./macbox up`.

## Day to day

```sh
Expand Down
1 change: 1 addition & 0 deletions docs/site/llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ publishing on their behalf.
- [README](https://github.com/TUNA-NOPE/macbox/blob/main/README.md): what it is, requirements, quick start, performance, FAQ, comparison with Docker-OSX and cloud simulators
- [AGENTS.md](https://github.com/TUNA-NOPE/macbox/blob/main/AGENTS.md): for an agent setting macbox up on a host, including the steps in macOS's GUI (macbox screenshot, click, type)
- [Setup, step by step](https://github.com/TUNA-NOPE/macbox/blob/main/docs/setup.md)
- [Updating an existing install](https://github.com/TUNA-NOPE/macbox/blob/main/AGENTS.md#updating): for an agent asked to bring macbox to the latest version; by hand in docs/setup.md#updating

## Using it from an agent

Expand Down
8 changes: 7 additions & 1 deletion docs/site/pages/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
---
<section class="hero">
<div class="wrap">
<p class="eyebrow"><img class="mark" src="/images/logo.svg" width="64" height="64" alt=""><span>macbox</span></p>
<p class="eyebrow">macbox</p>
<h1>Give your agents a&nbsp;Mac.</h1>
<p class="sub">macOS, Xcode and real iPhone simulators at up to 120&nbsp;fps, on your Linux machine and its own GPU. Your coding agent builds the app, taps through it and checks it for itself.</p>
<div class="ctas">
Expand Down Expand Up @@ -54,5 +54,11 @@ <h3>You'll need</h3>
./macbox next <span class="c"># what's done, and the next step</span></code></pre>
<p class="note"><code>./macbox next</code> always says what's done and what's next. <a href="https://github.com/TUNA-NOPE/macbox/blob/main/docs/setup.md">The full walkthrough</a></p>
</details>
<div class="needs" id="update">
<h3>Already have macbox? Update it</h3>
<p>Paste this into your agent. It pulls the new version, rebuilds what changed, and asks before it restarts the VM:</p>
<pre class="prompt"><code>Update macbox on this machine to the latest version: https://github.com/TUNA-NOPE/macbox. Follow the "Updating" section of its AGENTS.md and ask me before you restart the VM or change the host.</code></pre>
<p class="note">By hand: <a href="https://github.com/TUNA-NOPE/macbox/blob/main/docs/setup.md#updating">docs/setup.md, Updating</a>.</p>
</div>
</div>
</section>
3 changes: 1 addition & 2 deletions docs/site/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,5 @@ td strong { color: var(--ink); font-weight: 600; }
@media (max-width: 760px) { .cols { grid-template-columns: 1fr 1fr; } .cols > div { grid-column: 1 / -1; } }
@media (prefers-reduced-motion: no-preference) { html { scroll-behavior: smooth; } }

.hero .eyebrow{display:flex;flex-direction:column;align-items:center;gap:14px}
.hero .eyebrow .mark{width:72px;height:72px;filter:drop-shadow(0 8px 24px rgba(91,77,230,.28))}
.brand img{display:block;border-radius:6px}
#update { margin-top: 40px; }
Loading