Agent-friendly bootstrap, management, screenshots, input injection, and accessibility-tree automation for macOS virtual machines.
This directory is the canonical public source. The former
macvm-testbed repository is retained only as legacy history and a possible
future generated distribution.
MacVM Testbed fills the gap between “Tart is running” and “an automated agent can reliably operate the Mac desktop.” It provides one CLI for VM lifecycle, guest-agent commands, normalized screenshots, host-injected input, and native macOS Accessibility inspection and actions.
| Layer | Current implementation |
|---|---|
| Host | Apple-silicon macOS |
| VM provider | Tart 2.30+ / Virtualization.framework |
| Guest | macOS 26 prepared or vanilla image |
| Command channel | Configurable Tart guest agent or authorized SSH |
| Semantic UI | Native AXUIElement helper in the interactive guest session |
| Resident facade | Per-user Unix socket with machine-control/v0 envelopes |
| Composition | Native AX/Quartz/CGEvent plus optional installed Cua |
| Administrator sheets | Strict SecurityAgent, System Settings, Installer, and Gatekeeper profiles plus a non-echoing one-shot credential channel |
| Privacy fixtures | Signed API triggers and independent policy/hardware oracle |
| Framework fixtures | Deterministic AppKit, SwiftUI, Java Swing, and Electron semantics with file oracles |
| Recovery | Tart-window screenshot and CoreGraphics keyboard/mouse input |
The semantic helper has no provider-packaged exclusions for the Dock, menu bar, System Settings, or ordinary desktop applications. macOS consent and integrity boundaries still apply.
The Intel Tahoe on Linux/KVM guide covers the retained Quickemu/OpenCore appliance and disposable libvirt workspaces. Both use the installed Intel desktop package through pinned guest SSH, with QMP and loopback VNC for bootstrap and recovery. The sections below cover the Tart appliance.
brew install cirruslabs/cli/tart
tart clone ghcr.io/cirruslabs/macos-tahoe-base:latest tahoe-base
cd platforms/macos # from the machine-control checkout root
# Copy config.example to ignored config.local, then bind the selected VM as
# an exact candidate with matching MACVM_NAME and MACVM_EXPECTED_NAME.
claim="$(../../bin/machine-control --target macos claim acquire \
--duration 30m --reason 'prepare the macOS appliance' \
--claimant-authority example-agent --claimant-id session-42)"
export MACHINE_CONTROL_CLAIM_ID="$(jq -r '.data.claim.claimId' <<<"$claim")"
bin/macvm up
bin/macvm deploy-ui
bin/macvm authorize-ui
bin/macvm doctorThe final authorization opens an explicit guest macOS consent flow. Follow the bootstrap guide; do not attempt to edit TCC storage. Lifecycle commands fail closed until ignored/private configuration binds an exact candidate or disposable name. Public example defaults cannot start, stop, suspend, or shut down a VM.
Accepted VM use also requires the exact target's live exclusive claim. Direct
commands read MACHINE_CONTROL_CLAIM_ID; the common client accepts the same ID
with --claim. Renew it during long work and release through the common client
from trap/finally cleanup. Caller authority and identity are bounded,
self-asserted coordination metadata and are not tied to a particular agent
system.
Ordinary claims cover lifecycle, administration, and target-native desktop
control. Tart-window screenshot and input commands require a claim acquired
with --disruptive; an ordinary holder receives
disruptive_claim_required before Tart dispatch.
MACVM_FORBID_OUTER_UI=true remains an absolute prohibition even with a
disruptive claim.
The controller's hostAttendance (see the
target-registry guide)
adds a host-level policy. attended prohibits Tart-window screenshot and input
because someone may be using the host. unattended permits them to a
disruptive claim but disables suspend, because nobody will unlock the host to
restore a snapshot. Regardless of attendance, host input is refused while the
host session is not unlocked: it is posted to the global HID stream and would
reach the host lock screen instead of the VM. Doctor reports attendance and
host session in extensions.hostSession and the resulting states.outer.
A VM started by an agent outside the host's Aqua session may still have no
Tart window at all; see problems.
Use the existing claimed Tart guest for keyboard-layout testing. From the repository root, install its persistent Dvorak profile through the common CLI:
bin/machine-control --target macos --claim CLAIM testbed -- keyboard-profile install
bin/machine-control --target macos --claim CLAIM testbed -- keyboard-profile status
bin/machine-control --target macos --claim CLAIM testbed -- keyboard-profile standard
bin/machine-control --target macos --claim CLAIM testbed -- keyboard-profile alternateInstallation enables U.S., Dvorak and Dvorak–QWERTY Command, selects plain
Dvorak, swaps Command/Option on both sides and maps Caps Lock to Control.
The guest's Aqua LaunchAgent reapplies that profile at login. standard
temporarily switches to U.S./default modifiers; alternate restores the
normal Dvorak/remapped test configuration. The helper refuses configuration
changes outside a virtual Mac. Controller settings are never changed.
Run python3 tests/macos/keyboard-layouts.py --target macos --claim CLAIM
from the repository root for the six-cell production-resident suite, or add
--install-profile to retain the alternate setup after success. Add
--browser-smoke for isolated real Chrome for Testing effects when that
separate browser fixture is installed. Add --apps-smoke for Terminal/readline
and the standalone Electron editor across all six configurations, or
--apps-only for just that matrix; the pinned Electron framework runtime must
be installed first. This uses guest-native control and restores temporary
settings in cleanup. Ordinary shortcuts name logical modifiers and characters, independently of physical
modifier remappings. The bounded evidence and remaining layouts/frameworks are
tracked in Tactical 126.
bin/macvm doctor
bin/macvm doctor --json
bin/macvm up
bin/macvm exec /usr/bin/sw_vers
bin/macvm exec --timeout-seconds 10 -- /usr/sbin/sysctl -n kern.boottime
bin/macvm post-update audit
bin/macvm control '{"operation":"capabilities"}'
bin/macvm control '{"operation":"applications"}'
bin/macvm shell
bin/macvm suspendmacvm up submits the graphical tart run process to the current user's
launchd GUI domain. The VM therefore remains running after the invoking shell
or non-interactive command runner exits. Routine suspend, shutdown, and stop
leave no launchd-owned Tart process; the next up replaces any inactive job.
A suspend state restores only while the host session is unlocked; see
bootstrap before relying on
suspend from a controller that may lock.
Discover and operate semantic macOS controls:
bin/macvm ui apps
bin/macvm ui windows --app Safari
bin/macvm ui tree --app Safari --interactive --depth 8
bin/macvm ui find Downloads --app Safari
bin/macvm ui press Downloads --app Safari
bin/macvm ui launch TextEditFor accurate lock/readiness reporting and explicitly installed existing-session unlock, see the session-unlock runbook. Doctor and resident status share an OS observer; ordinary input refuses known locked or unknown state. The optional root helper and authorization plug-in passed SIP-enabled disposable-appliance acceptance. Ordinary deployment never installs the unlock provider implicitly. The desktop remains exposed after unlock; physical hardware and notarized distribution remain untested. The earlier investigation records the evidence and bugs that motivated this implementation.
The resident facade is the normal agent path. Deployment installs its stable
signed identity as a per-user Aqua LaunchAgent with RunAtLoad and KeepAlive,
so it returns after login, reboot, or a crash without using doctor as a start
operation. It reports the selected provider and is callable through the host
wrapper or the same guest-local CLI:
bin/macvm control '{"operation":"status"}'
bin/macvm control-local '{"operation":"status"}'Both calls reach one socket and one resident generation. Semantic references
are scoped to that generation and fail closed after restart. If the native
app lacks a TCC grant but an installed Cua daemon is healthy, results disclose
that composition and route rather than pretending the native provider ran.
Normal Aqua administrator sheets use the same resident through a strict,
short-lived lease and an interactive non-echoing credential helper; see
macOS UI automation.
The accepted logged-in Aqua corpus also covers settings-managed privacy,
native panels and sheets, notifications, Safari downloads, DMGs, Gatekeeper,
Installer, AppKit, SwiftUI, Java Swing, Electron, and target-local visual
fallback. The execution
record and original environment omissions live in
Tactical 010;
the Java/Electron closure is
Tactical 011.
doctor --json emits the minimized machine-control-doctor/v0 projection for
the common client. It reports independent power, administration, Aqua desktop,
resident, semantic, capture, input, and outer states without publishing the
configured machine identity, guest user, or network address. It is read-only
and exits nonzero when the accepted resident surface is not ready.
After a macOS, Tart guest-agent, Xcode tools, or repository update, use the bounded maintenance lifecycle:
bin/macvm bootstrap --profile development
bin/macvm post-update audit --profile development
bin/macvm post-update repair --profile development
bin/macvm appliance-certify --profile developmentAudit refuses a stopped VM before guest execution and does not start or repair
the resident. Repair requires the exact retained candidate, redeploys only the
stable checked-in resident/support identity, and may restart only enumerated
installed launchd jobs. It never edits TCC, installs Homebrew or an OS package,
handles a credential, uses Tart-window input, or reboots unless --reboot is
explicit. Certification requires clean committed source, observes a changed
guest boot epoch, verifies a digest-bound archive, runs portable and macOS
native checks with isolated state and bounded timeouts, removes staging, and
shuts down only after success.
Set MACVM_FORBID_OUTER_UI=true for ordinary software-test acceptance. In
that mode, Tart-window screenshot, click, drag, type, and key commands fail
closed while lifecycle, the selected guest command transport, and resident
control remain available.
bin/macvm host-state is a read-only acceptance oracle for the controller
host's cursor and frontmost application. It remains available under the guard
so conformance tests can prove that target-resident input did not manipulate
the host desktop; it does not observe guest pixels or inject input.
The prepared appliance can carry checksum-pinned, user-local ARM64 build runtimes without Homebrew or a system-wide package installer:
bin/macvm install-framework-runtimes
bin/macvm framework-runtime-status
bin/macvm deploy-java-fixture
bin/macvm deploy-electron-fixtureThe runtime manifest pins Eclipse Temurin 21 LTS, Node 24 LTS, and Electron to
immutable official archives and SHA-256 values. Deployment builds a Swing app
with jpackage and packages an Electron app under stable bundle identifiers;
both expose native semantics and write independent file oracles. Fixture
removal retains the reusable runtimes. Native AX drives Swing. The accepted
Electron semantic cell uses the installed Cua adapter after target activation:
live differential evidence found native AX acknowledged the Chromium button
without changing its oracle, while Cua produced the effect.
A resident capture returns a guest artifact path. Fetch that bounded artifact without reading arbitrary guest files through the artifact interface:
result="$(bin/macvm control '{"operation":"capture","scope":"display"}')"
bin/macvm artifact-fetch "$(jq -r '.data.artifactPath' <<<"$result")"Use the provider-level Tart-window path only for bootstrap or explicit recovery when the resident surface is unavailable:
bin/macvm screenshot
bin/macvm click 512 384
bin/macvm drag 300 240 700 240
bin/macvm type 'hello from the host'
bin/macvm key enterThe outer keyboard route supports US-keyboard ASCII and verified Shift/Command
chords. It still sends physical U.S. key positions; it does not translate the
guest's alternate keyboard profile. Do not use its text/secret path unless the
guest's input source is independently verified as U.S. With healthy guest
administration, keyboard-profile standard selects that temporary profile
before an explicitly authorized recovery. An unknown layout is a blocker for
outer secret entry, not a reason to try the stored password. It supplies both general and left-side device modifier flags; guest
text and menu effects proved the correction. Control, Option, and Fn remain
guarded. Use target-resident input after bootstrap; the
UI guide explains the tested scope,
diagnostic override, and secret boundary.
For the prepared image's first macOS consent sheet, the documented initial
admin credential belongs in the private file declared by inventory.
bin/macvm type-secret reads that file and sends physical keys to the exact
Tart window under a disruptive claim; recheck the consent effect afterward.
See the bootstrap guide.
Screenshots are normalized to the configured Tart guest display. A screenshot
pixel (x, y) is therefore the coordinate accepted by macvm click x y,
independent of Retina scale and the host Tart title bar.
The desktop app also has an experimental, default-off covered locked-use profile for approved bounded tasks on macOS 14 or later. It requires an awake, open-lid existing console session; native setup, capture, takeover, watchdogs, and removal are documented there. The explicit appliance unlock profile remains separate.
Host agent
|
+-- tart exec or SSH --------- guest shell and file operations
|
+-- selected transport -> macui
| semantic Accessibility tree/actions
|
+-- selected transport -> resident
| owned facade over native/Cua providers
|
+-- Tart window -------------- screenshot and injected input recovery
|
+-- tart CLI ----------------- lifecycle, IP, suspend, stop
The resident is the shared Machine Control.app, built and ad-hoc signed with
an explicit stable designated requirement and installed in the guest as
~/Applications/Machine Control.app. Tart's interactive user agent requests each
LaunchServices invocation and returns its output, while macOS sees one stable
app identity for Accessibility consent. This avoids the Windows-style
session-0 relay, but requires a logged-in Aqua session and one explicit grant.
Prepared non-vanilla Cirrus images contain the guest agent needed by
tart exec. A VM created directly from an IPSW does not. MacVM Testbed can
still see and drive Setup Assistant through the Tart window, then install the
guest agent from the read-only repository share.
Read docs/bootstrap.md for the complete prepared-image, vanilla-image, lost-password, TCC, and recovery procedures.
bin/macvm Main agent-facing CLI
bin/macui Guest semantic-control wrapper
providers/tart-macos/ Lifecycle, capture, and raw input
guests/macos/bootstrap/ Fresh-guest installation assets
resident/ Resident Swift package (guest and host)
guests/macos/ui/ Guest bundle metadata and LaunchAgent
guests/macos/fixture/ Deterministic native conformance fixture
guests/macos/admin-fixture/ Harmless administrator-sheet fixture
guests/macos/privacy-fixture/ Privacy API and System Settings fixture
guests/macos/swiftui-fixture/ Deterministic SwiftUI semantic fixture
guests/macos/java-fixture/ Deterministic Java Swing semantic fixture
guests/macos/electron-fixture/ Deterministic Electron semantic fixture
guests/macos/framework-runtimes/ Pinned runtime manifest
scripts/ Deployment and diagnostics
skills/drive-macvm/ Reusable agent operating skill
See docs/architecture.md before adding another host provider or guest implementation.
Open automation gaps found while driving real applications are tracked in docs/problems.md.
Host:
- Apple-silicon macOS with Tart
- Bash,
jq, Swift, and the built-inscreencaptureutility - Screen Recording and Accessibility permission for the invoking terminal or agent host
Guest:
- macOS with a logged-in desktop user
- Tart guest agent for
execand reliable IP discovery - or an explicitly authorized SSH account/key when SSH is selected as the guest command transport
- Xcode Command Line Tools to compile the deterministic fixtures
- Accessibility and Screen Recording permission for the deployed Machine Control app
- No credential is accepted in JSON, arguments, environment variables, repository files, logs, or results. Private inventory may locate a controller-local credential file for VM handoff; the administrator-sheet helper still streams credential bytes through its dedicated one-shot channel.
- Initial TCC consent still requires direct guest-user interaction because the resident does not yet have Accessibility permission.
- The repository share is read-only by default.
- The UI helper is non-root and cannot bypass TCC or macOS integrity levels.
- The resident socket is owned by the interactive user with mode
0600. - Privacy resets use supported APIs and
tccutil; the testbed never edits a TCC database. Local Network and notification decisions are settings-managed becausetccutildoes not expose a supported reset for them. - Ignored target-role/name guards can fail closed before clone mutation.
force-stopis an explicit recovery operation, never routine lifecycle.
MIT