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