| 1 | # Phoenix box |
| 2 | |
| 3 | `m3-phoenix-box` is a macOS 15 Tart VM beside `gui-agent`, in the same VM home under |
| 4 | `/Volumes/Documents/VM/macOS Code Sandbox`. It holds Discord Phoenix and runs it against |
| 5 | Spacebar, so its network is locked from outside the guest. |
| 6 | |
| 7 | Start it with `runtime/control/start-m3-phoenix-box` in that VM home. The script owns the |
| 8 | flags: headless, `--vnc-experimental`, and Softnet with every destination blocked except |
| 9 | `100.64.0.1/32`, Snow Globe's tailnet address. This Mac's NAT only leaves through Tailscale |
| 10 | (its own routes do not reach the internet), and Snow Globe's Caddy answers on that address. |
| 11 | Softnet filters by address, not port, so the VM can reach every port Snow Globe accepts |
| 12 | on the tailnet. |
| 13 | |
| 14 | - **Recovery:** the `net.paperclover.m3-phoenix-box-revive` LaunchAgent runs |
| 15 | `start-m3-phoenix-box revive` every 30 seconds through `ssh localhost`, so a crash or |
| 16 | host reboot restarts the VM unless a dashboard stop left `private/m3-phoenix-box/stopped` |
| 17 | (any start clears it). Restarts log to `~/Library/Logs/m3-phoenix-box-revive.log`. |
| 18 | After a host reboot nothing runs until Clover unlocks FileVault and logs in. |
| 19 | - **Names:** the guest has no DNS (its gateway is blocked), so `/etc/hosts` maps |
| 20 | `phoenix-selfhosted.paperclover.net` to `100.64.0.1`. Go ignores `/etc/hosts` on macOS unless |
| 21 | `GODEBUG=netdns=go`, which `run-phoenix-spacebar` sets for the Caddy relay. |
| 22 | - **Access:** Softnet also blocks host to guest, so there is no SSH or Screen Sharing. |
| 23 | Tart's own VNC server (random password per run, printed to `run.log` in |
| 24 | `private/m3-phoenix-box`, listening on every interface of this Mac) and `tart exec` are |
| 25 | the ways in. Console login is `admin` / `admin`; SSH accepts only the key in that |
| 26 | private directory. |
| 27 | - **Softnet:** 0.23.0 at `/usr/local/bin/softnet`, owned by root with the setuid bit. |
| 28 | Releases from 0.24 need macOS 26. |
| 29 | - **Dashboard:** `nixos/mac-vm.nix` lists both Mac VMs. The Mac-side bridge |
| 30 | (`runtime/control/mac-vm-bridge.py`) maps each dashboard name to a Tart VM, so Computer |
| 31 | MCP connections can be granted `m3-phoenix-box` like any VM. It has no dashboard |
| 32 | console or suspend; power operations run `start-m3-phoenix-box` and `tart stop`. |
| 33 | |
| 34 | To manage another Mac VM, add it to `VMS` in the bridge and to `nixos/mac-vm.nix`, then run |
| 35 | `python3 tools/install-mac-computer.py <tart name>` to install the guest worker. |