Find an installed application in the image inventories by name, then choose an image yourself; optional before relay_acquire. Matches canonical names and aliases by exact, prefix and substring comparison, with an optional hard os filter (linux/macos). Returns each match's installed versions (which may be null), image keys, OS and architecture; a truncated result means whole installations were omitted, and an empty result is distinct from a catalog error. Never allocates, boots, installs, reserves capacity or chooses an image for you.

Read-only host and service facts, used to pick an image; it reports current owned state on its own, so call it again after context compaction rather than trusting earlier messages. Default scope: "host" reports host permissions and activity, VM service availability, and every guest this session holds with its state, not guest readiness. scope: "guest" with guest (an already-acquired guest) reports whether Node.js, which staging requires, is available, and, as facts, whether each relay_script language's runtime runs (/bin/sh, node, tsx, python3), the software the image lists in the catalog, and whether this lease's runs take snapshots, without installing or starting anything, and never claims capture readiness. Acquire one guest for each machine the work needs; several may run at once. Continue each guest in order: relay_acquire, relay_stage, relay_script, relay_image/relay_extract, then relay_finish or relay_release, called explicitly for every guest before you return.

Read the backend's versioned VNC console options for the images it serves. Read-only: it neither acquires a VM nor recovers ownership of one.

Acquire one machine, a guest, and start its ownership heartbeat: a fresh VM from image (a key from relay_probe or relay_search), or a durable machine, a real Mac leased whole, by machine (its name as machctl list shows it, such as Build-Mac-1). Give exactly one of them. A durable machine is on the home network and not isolated from it, a CI job may share its desktop, it has no console (vnc is refused), and its runs take snapshots only while its cua-driver daemon holds Screen Recording; every other call works on it as on a VM. The result's guest is the guest's name in this session, such as login-test-1; every later call on this guest names it with guest. Requires task (a short slug), image or machine, and extractions: every output you intend to bring home, declared before any work ([] is allowed; nothing is extracted automatically). Optional ttlHours (default 4), env (a credential pack, never baked into images), fullWorkspace (opt in to deliver the whole workspace) and vnc (default false; only prepares console-sharing capacity, never opens a viewer). Acquire one guest for each machine the work needs: several guests may run at once, each with its own lease, evidence and finish, up to the session's limit (relay_status reports maxGuests, MCP_RELAY_MAX_GUESTS, default 4); an acquisition beyond it is refused with the names of the guests held. When the host is at capacity, such as at its limit on running macOS VMs, or the durable machine is leased by someone else, the acquisition waits for it, asking again every 15 s for up to MCP_RELAY_CAPACITY_WAIT (30 minutes by default), and the result's waitedForCapacityMs says how long it waited; once the wait runs out it is refused with the backend's reason and the time waited. The backend's other refusals pass through at once. Continue with relay_stage, relay_script, relay_image/relay_extract, then relay_finish or relay_release explicitly before you return; a failed step keeps the VM for repair rather than replaying uncertain input.

Push and hash-check the guest runtime, plus an optional workspace and support files (files, landing under support/), onto the acquired guest that guest names. workspace and each files[].local lie in the project folder, relative to it or absolute inside it, with no symlinks. Staging needs only Node.js in the guest (nodePath, default node); an image without it is refused, because the relay pushes no runtime. Runs take before and after snapshots only when the image lists capture software (cua-driver); otherwise their records have none, and the result's snapshots says which. When the image lists cua-driver, staging waits up to 120 s for it to take a screenshot, since the image starts its daemon at login, and refuses if it never does. cuaDriver names the guest cua-driver the snapshots use. A failed stage can be retried; once staged, only corrected executable paths may be resubmitted, and staging does not prove capture readiness. resetRecording: true archives the current recording's evidence and starts a fresh recording on the same VM; it refuses while a receiver lock is held.

Run one guest script as one recorded operation; never hide several interactions in one call. A command is a shell script. The script drives whatever the image lists, such as cua-driver, Playwright or Chrome DevTools, through their own libraries or command lines, and its exit status says whether it succeeded, so a script that calls cua-driver checks the driver's answer itself. Requires language (shell, javascript, typescript or python) and inline: with inline: true give the script itself as code (up to 1 MiB); with inline: false give localPath, a host file in the project folder (relative to it or absolute inside it, with no symlinks). Give exactly the one inline names; any other call is refused. It runs in the staged workspace: shell with /bin/sh, JavaScript with the guest's Node.js, TypeScript with tsx from the guest's PATH or else the guest Node.js's own type stripping (22.6 or later), and Python with python3 from the guest's PATH (relay_probe scope=guest reports which run); a missing runtime refuses the run before it starts. Evidence is automatic: the relay records a step derived from the call and, when the image lists cua-driver, snapshots the display before and after. Optional reason (intent, never authorization), step (id, title, expected, inputMode) and snapshots.afterIntervalMs (default 500 ms) enrich or tune the record; consecutive keystrokes may form an explicit text group with snapshots.group (first/member/last). timeoutMs bounds execution (default 120000, up to 3600000). The result carries the outcome and bounded stdout/stderr; it names the after-snapshot as pending with its imageId while the image downloads in the background, so call relay_image with that imageId to see it. A refused, uncertain or nonzero result keeps the VM; never replay input whose effect is uncertain. diagnostic: true, for shell scripts only, records a diagnosis or repair without snapshots, even before relay_stage, running the script as /bin/sh -c; it is never visual verification, and its result has one output field with stdout and stderr combined.

Retrieve one already-saved image; never a new capture, input or directory export, and it never acquires a VM. target selects a display phase (sessionId/executionId/phase: before/after), a declared application file (name, plus a relative path for a directory declaration), or an immutable reference (imageId). PNG, JPEG and WebP only; originals up to 64 MiB and 40,000,000 decoded pixels; the delivered preview is at most 2000x2000 px and 4 MiB of base64 (PNG originals are resampled in-process; JPEG/WebP pass through only within bounds). Each delivery has a 90-second deadline and up to three transfer attempts. A run's after-snapshot is pending in its result; retrieve it here with its imageId or display selector, which waits for its background download within the same deadline. If an image did not arrive, recover it here the same way, never by repeating the input or capturing again, and stop after at most two such recovery calls if it still cannot be inspected. A closed guest returns stale-reference for a display or reference target; its delivered originals stay readable with host file tools. An attached image proves only that the block was included, not that anyone inspected or reviewed it.

Pull one or more already-declared extraction outputs home early, by names. Only outputs declared on relay_acquire may be pulled; each pull verifies source and host hashes and rejects path traversal, symlinks, or a source that changed underneath it.

Complete one guest's work: extract every declared output, deliver and verify a portable evidence package, then destroy the guest's VM and unregister it; the session's other guests keep running. The result reports delivery, snapshot completeness, execution outcome and human review as separate facts; a verified package is not a passing test, and a delivered package is not itself human approval. Call this, or relay_release, explicitly for every guest before you return, since ending the session does not do it for you. A declared output that was never produced is listed in incompleteExtractions and does not stop the delivery; any other failed extraction or delivery keeps the VM for a corrected attempt.

Abandon one guest's work: destroy the VM of the guest that guest names and unregister it, retaining whatever evidence already exists, without claiming the task succeeded; the session's other guests keep running. Use this instead of relay_finish when the task is not being completed. Safe to retry if a previous release attempt failed; a failed release keeps ownership until destruction is verified. When this session holds no guest, the result is an error saying that nothing was released; a lease acquired under another session identity is never guessed at.

Refresh this session's non-secret console-viewing status for the lease of the guest that guest names. Read-only, and it never recovers ownership. A ready status means guest preflight only, not that a viewer launched: console operations carry no screenshots and never establish authentication, displayed pixels or a human's confirmation. On macOS, viewing requires the human to choose Standard sharing of the existing console, not a new Log In session or a High Performance display, and the relay never auto-confirms that choice; server_enforced_view_only: false and an unverified viewer selection remain limitations even once transport connects. Never replay an uncertain attempt: resolve it here, or close it with relay_console_cancel.

Open console viewing for the lease of the guest that guest names, only following an explicit user request to watch. Requires console_id and attempt_id from relay_console_resolve, userRequested: true, reason (intent) and expected (what the human should expect to see); it opens on the declared service host, never a remote client, and is never triggered automatically by relay_acquire's vnc option. See relay_console_resolve for what a ready status does and does not prove. A failed or uncertain open keeps the attempt: resolve or cancel it rather than opening again with a new attempt.

Cancel an open or uncertain console-viewing attempt by console_id and attempt_id. Closes managed viewing resources only; it never releases or destroys the VM.

List every guest this session holds, by the name relay_acquire answered, each with its VM lease (backend binding, guest state, renewal, console observation, last error), staging state and evidence path, plus the most guests the session may hold (maxGuests), the project directory, the VM service origin and the selected environment in use; active:false when no guest's lease is being renewed. Read-only; it does not touch the VMs.