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