Agent VMs

Before you start

Agent VMs are retained Linux or macOS guests on your paired machines. Mirage keeps their disks, files, SSH identities, selected images and resource shapes across stop and resume. They share capacity with CI and other detected VMs. API tokens cannot manage agent VMs; sign in as the person who paired the machine with a writable CLI session.

Create a VM

Use Mirage CLI 0.2.35 or newer and an updated host. List prepared images and capacity first:

mirage vm images DEVICE
mirage vm budget DEVICE
mirage auth status --verify

mirage vm create DEVICE --name review-agent
mirage vm create DEVICE --name linux-agent --profile linux-arm64 --cpus 2 --memory-mib 4096 --disk-gib 20
mirage vm create DEVICE --name x64-agent --profile linux-x64 --image PREPARED_IMAGE_ID
mirage vm list

CPU, memory and disk sizes belong to the VM request. Omitted sizes use the default allocation on allocation-capable hosts and prepared profile defaults on older hosts. A Mac defaults to macOS; a Linux connector defaults to its prepared native Linux profile. --image accepts only an image listed by vm images. It does not import or prepare an image. Mirage creates and stores a separate SSH key for each guest.

Macs run Linux arm64 natively. Their Linux x64 profile has an arm64 kernel and x64 userland through Rosetta. It cannot run an x64 kernel or x64 kernel modules. Proxmox runs native x64 or arm64 guests only on a matching, validated node and prepared template; arm64 requires compatible Proxmox hardware. Multiple VMs can run when their allocations, shared slots and platform limits fit. macOS remains limited to two VMs in total, including CI and detected external Tart guests.

SSH, files, and desktop access

mirage vm ssh review-agent
mirage vm cp review-agent ./notes.txt /Users/admin/notes.txt
mirage vm cp linux-agent ./notes.txt /home/runner/notes.txt
mirage vm cp linux-agent /home/runner/result.txt ./result.txt --from
mirage vm screen review-agent

SSH and copy use admin for macOS and runner for Linux. Add --recursive for directories. Linux guests provide SSH, SFTP and Docker without starting an Actions runner. Screen Sharing is available only for macOS. vm screen explicitly retrieves and displays its password; routine create, list, status, action and dashboard responses contain no screen credentials. The password never appears in a process argument or VNC URL.

Connection commands resume stopped guests by default. Their readiness deadline is five minutes, including establishing the host-to-guest connection:

mirage vm ssh linux-agent --no-resume --wait-timeout 30s
mirage vm cp linux-agent ./notes.txt /home/runner/notes.txt --wait-timeout 2m
mirage vm ssh linux-agent --wait-timeout 0

--no-resume rejects a stopped guest and can wait for one already starting. Zero performs one immediate state check and never resumes. A timeout explains the latest state and capacity reason. It leaves the VM request active; it does not stop or cancel the guest. The readiness deadline does not limit an established SSH command or file transfer. Legacy mirage remote vm ssh, cp and tunnel accept the same controls.

Tunnels listen only on your computer’s loopback address. mirage remote vm tunnel DEVICE VM --port ssh supplies a local port for another client. An opened tunnel connects to the guest before reporting ready and holds an active connection until it closes. Use --listen-port to change the local port.

Capacity and idle stop

vm budget DEVICE shows physical capacity, the effective host reserve, CI reservations, admitted agent VMs, detected external VMs, pending requests and remaining schedulable CPU, memory and disk. The machine page shows the same in In use, one row per workload, and keeps inventory coverage and observed memory in Diagnostics. Its New VM button writes the vm create command for a name and guest you choose, and a running VM's row opens to its guest CPU, memory and disk once the host reports them. macOS CI and agent VMs share an allowance of at most two macOS guests; Linux workloads run while their resources fit the budget. Observed memory usage, compression and pressure are separate from configured allocations. A queued request commits no resources until admission. Permanently unsupported resource shapes are rejected; competing work can leave a request queued with requested and available quantities. Memory overrides use 512 MiB increments; macOS requires at least 4096 MiB.

Disk headroom comes from physical free space after the host reserve and active disk reservations. Retained disks already reduce free space; their reported file sizes stay visible without being subtracted again. On APFS, those sizes can include shared clone blocks. A stopped VM releases its disk reservation, and resuming it reserves the pinned disk request for future writes.

On Macs, a signed collector runs in each logged-in user’s session and reads Tart metadata without controlling those VMs. Install the updated signed macOS package to register its user-session launch agent; a daemon-only update cannot add that privileged installation. It covers the default store and registered custom stores:

"/Library/Application Support/Mirage/Runtime/Current/bin/MirageVMInventory" --register-store /path/to/tart-home

Coverage, sample timestamps, unreadable stores and stale reports are visible. Mirage keeps last-known external commitments during a reporting gap. User sessions and registered stores define coverage; an absent collector never proves that external usage is zero. New admissions on upgraded hosts wait for fresh, complete inventory. A collector can confirm an absent store, but Mirage retains previously running guests if their store has disappeared until a complete report confirms their stopped state. Proxmox budgets describe the target node, not its connector appliance. Incomplete API visibility prevents new admission on a connector enabled for retained VMs.

After a VM starts, connect within ten minutes. After its last tunnel closes, Mirage gives you ten minutes to reconnect before stopping it. Active tunnels suspend the idle countdown. Direct guest connections outside Mirage do not extend it. Capacity returns after the host confirms a stop. A restart or expired host lease stops guests and retains their disks.

Resume, stop, or delete

mirage vm stop review-agent
mirage vm resume review-agent
mirage vm status review-agent
mirage vm stop review-agent
mirage vm delete review-agent

The machine page also provides these actions. Whoever controls the machine (you for a personal machine, an owner of the organization for a dedicated host) can stop, resume and delete its VMs there, for example to clear a machine before removing it. Connecting, copying files and creating VMs stay with the person who paired the machine. Everyone who can open the machine page sees each VM's resources; only the person who paired it and its controllers see VM names. Resume requests capacity again and preserves the guest’s selected configuration even after catalog or host-default changes. Delete requires a stopped VM and permanently removes its disk. Proxmox guests use independent full clones, durable ownership mappings and a separate operator-configured VMID range. Mirage’s CI orphan cleanup does not remove retained guests.

Troubleshoot

Inspect the waiting reason and resource budget when a VM cannot start. A paused, disconnected, stale or updating host must become available again. Disk, memory and CPU commitments clear when competing work stops. needs_attention reports a failed start, local pressure protection or reconciliation problem; stop the guest before retrying. Mirage keeps uncertain capacity reserved until it can confirm a stop.

Plain auth status checks local credentials. auth status --verify forces OAuth refresh, persists token rotation under a per-server lock shared by CLI processes, and checks API access. It reports identity, scopes and VM access without secrets. Environment tokens are verified by the API and report refresh as unavailable. Credential storage, refresh, authorization, permission and network failures return actionable errors and a nonzero exit.

Existing Tart VM adoption, arbitrary images, automatic image preparation and a direct Linux KVM backend are not supported.