1# Local macOS agent VM
2
3`mac-agent-vm.py` controls the `gui-agent` Tart VM on this Mac. Its runtime,
4image cache, private credentials, and VM disks live under
5`/Volumes/Documents/VM/macOS Code Sandbox` on the local SSD. `MAC_AGENT_VM_HOME` overrides that
6root. Missing storage fails explicitly; the tool does not recreate it on the
7startup disk.
8
9Documents' external volume has ownership disabled. The VM root uses
10an explicit named-Clover allow ACL before an everyone-deny ACL, with file and
11directory inheritance; mode bits alone would not protect it. This order and
12identity matching were tested on disposable files, including denied access
13despite permissive POSIX modes. The signed Tart app is protected by its
14ancestor directory ACL because macOS App Management rejects modifying the
15bundle's own ACL. Volume ownership and host security settings are unchanged.
16
17Documents is APFS-encrypted (Project, in the same container, is not). Its
18passphrase is in the host login keychain under the volume UUID, and the
19`net.paperclover.documents-unlock` LaunchAgent unlocks the volume at login.
20
21```sh
22python3 tools/mac-agent-vm.py start
23python3 tools/mac-agent-vm.py status
24python3 tools/mac-agent-vm.py exec /bin/zsh -lc 'rustc --version; node --version'
25python3 tools/mac-agent-vm.py ssh
26python3 tools/mac-agent-vm.py console
27python3 tools/mac-agent-vm.py stop
28```
29
30Everything except `exec` reaches the guest over pinned SSH at its Bonjour name.
31`exec` and the dashboard's computer operations go through Tart's guest agent so
32they run in the logged-in GUI session, and that path can crash the VM runner
33(`/Library/Logs/DiagnosticReports/tart-*.ips`, `-[VZVirtioSocketDevice
34connectToPort:]`). Use `ssh` for anything that does not need the GUI session.
35
36The `net.paperclover.mac-vm-revive` LaunchAgent runs `revive` every 30 seconds
37through `ssh localhost` (launchd jobs cannot read the VM volume). It starts the
38VM when its runner is gone unless `stop` or `suspend` left `private/stopped`;
39`start` clears that marker. Restarts and the newest Tart crash report are logged
40to `~/Library/Logs/mac-vm-revive.log`. A hung guest under a live runner is not
41restarted.
42
43To reach a server bound to guest loopback from this Mac:
44
45```sh
46python3 tools/mac-agent-vm.py forward 5173 --local-port 15173
47```
48
49Open `http://127.0.0.1:15173` on the Mac. The tunnel stays in the foreground;
50Ctrl-C closes it. Both ends use loopback, occupied ports fail explicitly, and
51no guest command or LAN listener is created. T3's browser separately requires
52its toolbar's port approval. Run `python3 tools/mac-agent-forward-test.py` to
53check a disposable guest server, a transfer larger than 512 KiB, port collision,
54and listener shutdown. This test uses the existing guest without changing its data.
55
56`start` resumes a suspended VM or boots a stopped VM, then waits for commands
57to work through the logged-in guest agent. `stop` requests a graceful
58guest shutdown and waits for it to finish. `start` launches Tart through
59`ssh localhost` (needs Remote Login and this user's key) because closing an
60agent session kills every process it spawned, even in a new session; launchd
61jobs cannot read the VM volume (TCC). `suspend` waits for Tart's RAM
62snapshot; it writes memory to disk and is not an instant CPU pause. A running
63VM holds a process-scoped idle-sleep assertion, so locking the host does not
64cause idle sleep. Host login, FileVault, and explicit sleep remain host policy.
65
66## Network and iPhones
67
68The guest is bridged onto the LAN through the host's default-route interface
69so iPhones can find it over Bonjour and connect in; Virtualization.framework
70has no USB passthrough for them. Its DHCP address and the host's are reserved
71on the router and recorded in
72[mac-studio-sandbox.json](../config/mac-studio-sandbox.json): Snow Globe
73exports NFS to `guestAddress` and the dashboard reaches the host at
74`hostAddress`. Every `start` loads a pf anchor (`com.apple/net.paperclover`)
75in the guest that refuses new inbound TCP below port 49152 from anyone but
76the host, plus Kerberos and NetBIOS over UDP. A guest that reboots itself
77stays open to the LAN until the next `start`. iPhones on iOS 27 pair in Device
78Hub with **+ → Pair Nearby Device…** and Settings → Privacy & Security →
79Developer Mode on the phone. Older iOS needs a cable, which the guest cannot
80have.
81
82The guest has 28 vCPUs, 20 GiB RAM, and a 1440×900 display. vCPUs do not reserve
83physical cores. CPU count and RAM changes require a cold boot. No automatic
84lock/unlock controller or CPU affinity is installed. The guest's 20 GiB budget
85is fixed for a run. Apple [allocates physical memory on demand](https://developer.apple.com/documentation/virtualization/vzvirtualmachineconfiguration/memorysize),
86so it need not occupy 20 GiB immediately. Stock Tart has no verified balloon or
87guest-aware reclaim path; sizing assumes previously used pages may remain
88backed until the VM stops. Clover chose 20 GiB on 2026-11-22.
89
90The 128 GB sparse disk contains a system APFS container of about 122 GB,
91a 5.4 GB recovery partition, and the original boot container. The system
92volume no longer has a separate 44 GB ceiling. Cache placement is managed by
93the guest's setup configuration under `~/.local/share/agents/vm`; projects and
94bulk caches use `/Volumes/Code`. SIP and the recovery partition remain intact.
95
96`AgentScratch` was removed on 2026-10-20 after its users stopped and legacy
97cache references were updated. A normal unmount and deletion targeted only
98volume UUID `D7650D6C-F7CC-444B-ACA3-EA472ADEB3B8`; the Code workspace and its
99replacement cache image were verified mounted afterward. Recovery archives
100are retained in the host VM home's `private/agentscratch-retirement-20261020` and the guest's
101`/Volumes/Code/scratch/setup/AgentScratch-retirement.tar`. The host restore
102matched 16,121 entries by content, mode, and symlink target, and all five
103restored SQLite databases passed integrity checks.
104
105The 2026-10-20 storage rebuild preserved the configured guest, accounts, tools,
106and automation approvals. It copied the system bytes into a sparse disk on
107Documents, moved and hash-verified the unchanged recovery partition, expanded
108the system container, and restored Scratch from the stopped original disk
109through a host read-only mount with explicit ownership. Full retained-content
110and metadata comparison, a detached-source cold boot, pinned SSH, actual screen
111capture, and browser keyboard input passed before removing the old Project
112installation. Documents is the only VM home; private rebuild evidence remains
113in `private/rebuild-20261020`. The temporary public Chromium-trial Xcode copy
114was omitted during the move; its pinned host source was verified before the
115old installation was removed.
116
117## Dashboard access
118
119The existing `gui-agent` is registered as `m3-devbox` in Snow Globe's
120VM dashboard. Only the Snow account declared in `nixos/mac-vm.nix` can see or
121operate it; other infrastructure administrators are excluded too.
122The dashboard retains its row when Mac Studio is unreachable; hardware in that
123state is the last successful observation, not live telemetry. Mac resources do
124not count against Snow Globe's Linux VM capacity.
125
126Snow Globe connects to the Mac's existing SSH service with a dedicated key at
127`/var/lib/snowglobe/mac-vm/ssh_key` and a pinned host key in the adjacent
128`known_hosts`. Both are root-only. The corresponding Mac `authorized_keys`
129entry uses `restrict,command=` to invoke `mac-vm-bridge.py`; it grants no shell,
130forwarding, PTY, or arbitrary VM selection. Its computer operation runs commands
131inside the fixed guest. Deploy the bridge and `mac-agent-vm.py` together under
132the VM home's `runtime/control` and keep that forced command pointed there,
133independent of an agent session.
134
135The existing host sshd provides supervision. Each console connection creates
136a fresh, pinned guest SSH tunnel, authenticates Screen Sharing on the Mac,
137and relays RFB into the dashboard's existing WebRTC viewer. No public VNC or
138HTTP control port is required. Dashboard ownership checks cover the screen,
139power operations, and clipboard. Unicode clipboard text travels over stdin
140to the logged-in guest's `pbcopy`, never through command arguments or logs.
141
142Supported controls are start/resume, graceful shutdown/restart, and suspend.
143Power operations are serialized; a timeout kills unfinished lifecycle commands
144while preserving the detached VM runner. Hardware edits, media attachment,
145force-off, deletion, and preset creation are unavailable for this managed VM.
146
147Dashboard WebSockets survive Caddy route reloads for up to their existing
148eight-hour session limit. Interrupted viewers reconnect with bounded backoff
149and recheck authorization. On 2026-10-20, removing the completed dashboard
150preview reloaded production routes while the Mac viewer continued the same
151video stream without reconnecting. A deliberately closed viewer connection
152also recovered without restarting the guest. The idle legacy tailnet relay
153was retired; the actively used loopback recovery console was preserved.
154
155## Computer MCP
156
157The `computer` MCP catalog uses the dashboard's OAuth flow. Grants select VMs
158owned by the account; every call rechecks the current owner, selected VM, and
159`computer:read` or `computer:control` scope. Infrastructure administrators do
160not bypass ownership. Read access provides status, screenshots, and AX trees;
161control also runs bounded zsh scripts with `agent-gui` input primitives and
162optional screenshots. The guest's passwordless sudo permits software setup.
163This managed devbox remains persistent.
164
165Install from this Mac while the guest is running:
166
167```sh
168python3 tools/install-mac-computer.py
169python3 tools/deploy.py stage dashboard --computer m3-devbox
170```
171
172The installer compiles the GUI helper in the guest, installs the stdin/stdout
173worker, refreshes the restricted host bridge, and checks permissions. The
174worker serializes operations, caps command output, and kills the command's
175process group on timeout. Commands deliberately detached into another session
176can outlive a call; this is a development shell, not a process sandbox.
177Screenshot pixels include display bounds and scale for point-based input.
178
179Dashboard previews have no computer access by default. `--computer` explicitly
180attaches the real managed guest to the preview account; subsequent staging
181updates retain that attachment. Only the preview host's configuration remaps
182ownership. Its credentials grant access to the live guest, so keep them private.
183Destroying the preview removes its access. Production ownership is unchanged.
184
185## Guest access
186
187`~/.local/bin/code-vm` links to the installed `runtime/control/code-vm` under
188the VM home, alongside its helper:
189
190```sh
191code-vm # Interactive SSH shell
192code-vm 'uname -a' # Run a guest command
193code-vm --clipboard # Copy the host clipboard into the guest
194```
195
196After copying the clipboard, focus the guest and press Command-V. Text travels
197through the guest agent into the logged-in session's pasteboard; no automatic
198keystroke or continuous clipboard sharing is enabled. SSH resolves the current
199VM address each time and reuses the existing pinned key configuration.
200
201The guest mounts Snow Globe’s NFS export at `/Volumes/Code` using `/etc/fstab`.
202[net.paperclover.code-share.plist](../guest/net.paperclover.code-share.plist)
203runs as a system LaunchDaemon at boot and retries every 30 seconds if needed.
204The workspace SSD is mounted at `/work` through a separate NFS export, bound
205on Snow Globe from `/srv/work` onto the sandbox's `.work` directory;
206`/etc/synthetic.d/snowglobe-work` creates the mount point and
207[net.paperclover.work-share.plist](../guest/net.paperclover.work-share.plist)
208retries the mount every 30 seconds and unmounts it again unless the SSD marker
209is present.
210
211The guest's `/etc/hosts` maps `file.paperclover.net` to the NAS LAN address
212`10.0.0.1`. The host's hosts file is not inherited. The previous guest file is
213`/etc/hosts.before-code-nas`.
214
215SSH uses a new private key in `private/ssh_key`, unique guest host keys pinned
216in `private/known_hosts`, and disables password authentication. No host SSH
217configuration, agent, accounts, or project directories are forwarded. The
218guest's randomized login password and auto-login credential are private to
219this VM. `admin` has passwordless sudo.
220
221The Tart guest agent runs in the logged-in guest session and supplies
222`exec` over Virtualization.framework's VM channel. Prefer that path for GUI
223commands: its Accessibility, Screen Recording, and Full Disk Access permissions
224are approved in the guest's System Settings. SIP remains enabled. Permission
225grants belong to the responsible guest agent; commands launched through another
226process may need separate guest approval.
227
228The first ScreenCaptureKit capture also requested permission to bypass the
229private-window picker; that guest prompt was approved separately. Future OS
230changes or capture-authorization renewals can prompt again: a successful
231preflight status is not proof that every future operation is prompt-free.
232Verify actual capture and input after upgrades.
233
234```sh
235python3 tools/mac-agent-vm.py exec /usr/local/bin/agent-gui status
236python3 tools/mac-agent-vm.py exec /usr/local/bin/agent-gui screenshot /tmp/screen.png
237python3 tools/mac-agent-vm.py exec /usr/local/bin/agent-gui tree
238python3 tools/mac-agent-vm.py exec /usr/local/bin/agent-gui click 400 300
239python3 tools/mac-agent-vm.py exec /usr/local/bin/agent-gui key 1 command
240python3 tools/mac-agent-vm.py exec /usr/local/bin/agent-gui type 'Synthetic test text'
241```
242
243`type -` reads UTF-8 from stdin, including newlines. `tree [PID]` returns
244roles, names, values, states, bounds, available actions, and child paths;
245`press PID 0.1.2` invokes AXPress at a freshly inspected path. Its tree has
246depth and node limits. Rebuild `mac-agent-gui.swift` with `swiftc -O`, install
247the binary at `/usr/local/bin/agent-gui` inside the guest, and recheck actual
248permissions and capture after changing its executable.
249
250The optional local recovery console is `http://127.0.0.1:17891/vnc_lite.html?autoconnect=true`.
251It reaches the guest's built-in Screen Sharing through pinned SSH, forwarding
252guest `127.0.0.1:5900` into a temporary private Unix socket. The relay handles
253the guest account authentication from `private/password` server-side. Screen
254Sharing listens on all guest interfaces behind the pf anchor; the host relay's
255TCP listeners default to loopback and check the exact HTTP Host and WebSocket
256Origin. Tart's experimental host VNC server is disabled. The viewer trusts
257every client that can reach its listener; Origin checking protects against foreign
258websites, not other clients. For remote access, bind a separate console to this
259Mac's Tailscale IPv4 address:
260
261```sh
262python3 tools/mac-agent-vm.py console --listen "$(tailscale ip -4)"
263```
264
265Use the printed IP-based URL; hostname aliases fail the exact Host check.
266This exposes desktop control to reachable tailnet peers without opening the LAN
267interface. Keep the authenticated RFB relay itself on loopback. Reconnect the
268viewer after a VM restart; each connection resolves the guest address again.
269Use the authenticated dashboard for ordinary remote access.
270Console shutdown terminates its SSH child and removes the private socket.
271If the page says “connection is closed” while SSH still works, restart the
272console relay; the VM does not need restarting. Run `console` in a host Terminal
273to keep its lifetime independent of an agent thread. Its SSH tunnel has a
274separate session so terminal hangups do not leave the HTTP listener stranded.
275Apple ARD authentication attaches the guest user's session; legacy VNC-only
276authentication is disabled. SSH encrypts its transport. Credentials never appear
277in arguments or browser URLs.
278
279## Guest policy and tools
280
281Spotlight indexing, Siri, idle sleep, screen saver, screen lock, automatic OS
282update checks/downloads/installations, crash dialogs, and automatic diagnostic
283submission are disabled in the guest. Gatekeeper assessments are disabled as
284requested. Developer mode is enabled with `DevToolsSecurity`. On 2026-10-20,
285installed applications, including Xcode and Device Hub, received Full Disk
286Access, device control, screen recording, input monitoring, developer-tool
287access, and app-management approvals through System Settings. Existing apps
288may need a normal relaunch to use new grants. These are per-app permissions;
289future apps and request-only categories can still prompt. SIP remains enabled.
290FSEvents and durable disk synchronization remain enabled. Apply OS updates
291deliberately between test runs, then recheck GUI permissions and boot.
292
293Future prompts are approved unattended by the `net.paperclover.prompt-approver`
294LaunchAgent: TCC alerts, Accessibility requests (via System Settings),
295keychain access, and administrator authorization. Password fields get the
296guest login password from `password` in its Application Support directory, or
297`keychains/NAME` for a prompt naming another keychain; `knife-signing` links to
298`~/.config/knife-signing.keychain-db.password`. A prompt still open after two
299attempts is cancelled. Every action is logged to
300`~/Library/Logs/prompt-approver.log`. Install or update it with
301`python3 tools/install-mac-prompt-approver.py`; a changed build gets a new path
302because TCC pins an ad-hoc binary's first code hash to its path, and the
303installer approves it by running a copy under the already-approved guest agent.
304
305Shared `jj`, `pnpm`, and workspace command routing is maintained in
306[project tools](project-store.md).
307
308Initial provisioning installed Rust/Cargo 1.99.1, Node 24.22.0 LTS, npm 11.19.1,
309pnpm 12.14.0, Jujutsu 0.42.0, and Apple's CLT with Clang 17 and the macOS SDK.
310Subsequent guest setup manages toolchain versions and paths in
311`~/config/users/clover/agents/vm` on the host. Its installed `env.zsh` is linked
312from the guest's `~/.zshenv`, including non-login shells. The development
313LaunchAgent publishes the same environment to newly launched GUI apps. Existing
314apps retain their inherited environment until relaunched. `/bin/zsh` has a
315separate guest Full Disk Access approval so launchd can read this configuration
316on Code. The Apple-tools LaunchAgent retries failed image attachment every
31730 seconds and recognizes already mounted images.
318
319On 2026-10-20, a fresh launchd process resolved Cargo, Node, pnpm, and Zig and
320reported the Code-backed cache paths. Existing Apple and kache mounts remained
321available. A Mac restart was explicitly deferred by Clover; these live checks
322do not establish cold-boot recovery. A dashboard clipboard round-trip preserved
323accented text, emoji, and Japanese text with UTF-8 selected explicitly for
324`pbcopy` and `pbpaste`.
325
326## Provenance
327
328Provisioned on 2026-10-19 with the signed [Tart 2.41.1 release](https://github.com/openai/tart/releases/tag/2.41.1),
329archive SHA-256 `e680a734febccfce7d4e910c1f7f13fc3b00f19a181c945e2d746de3214c32c2`.
330The Cirrus Sequoia vanilla image is pinned to
331`ghcr.io/cirruslabs/macos-sequoia-vanilla@sha256:57a83b1b52f928f5b11b0963927178fd6c4cac52c315279f227c27cc5ab81587`
332and boots macOS 15.7.7. Its default credentials were rotated after cloning.
333The [published template](https://github.com/cirruslabs/macos-image-templates/blob/master/templates/vanilla-sequoia.pkr.hcl)
334documents its original auto-login, CLT, SSH, sudo, and Gatekeeper setup.
335
336The VM agent is [Tart guest agent 0.15.0](https://github.com/openai/tart-guest-agent/releases/tag/v0.15.0),
337verified against release archive SHA-256
338`eb47f402f18e742a8ea96344115ca776179f9c4c67494bc0c46a10a68db280b7`.
339The local browser relay uses noVNC 1.7.0, websockify 0.13.0, and cryptography
340for Apple ARD authentication, following [noVNC's protocol implementation](https://github.com/novnc/noVNC/blob/v1.7.0/core/rfb.js).
341Their runtime environment stays outside the checkout. No production service
342configuration is changed.