Acquire a machine
relay_acquireLease a fresh VM from an image or a durable Mac by name, with task, TTL and declared extractions, to start recorded, snapshot-evidenced work in a session guest.
Instructions
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"task": "<task>",
"extractions": "<extractions>"
},
"name": "relay_acquire"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Credential pack, default none; never baked into images. | |
| vnc | No | Prepare guest console sharing, default false. Never opens a viewer automatically. | |
| task | Yes | ||
| image | No | Image key from relay action=probe, e.g. ubuntu2404 or macos26, for a fresh VM. Give exactly one of image and machine. | |
| machine | No | A durable machine, a real Mac leased whole, by the name machctl list shows, e.g. Build-Mac-1. Give exactly one of image and machine. | |
| ttlHours | No | ||
| extractions | Yes | ||
| fullWorkspace | No | Explicit opt-in to deliver the entire workspace. |