vm-relay

Overview Schema Source Related Servers Discussions Admin

Stage the guest runtime

relay_stage

Push and hash-check the guest runtime plus optional workspace and support files onto an acquired VM to prepare it for recorded sessions.

Instructions

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.

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": {
      "guest": "<guest>"
    },
    "name": "relay_stage"
  }
}

Input Schema

Name	Required	Description
`files`	No
`guest`	Yes	The guest this call acts on: the name relay_acquire answered.
`nodePath`	No	Guest Node executable, default node; use image nvm path if needed.
`cuaDriver`	No	Guest CUA executable; OS default when omitted.
`workspace`	No	Host directory copied to the guest workspace, opt-in. It lies in the project folder: relative to it, or absolute inside it; no symlinks.
`resetRecording`	No	Explicitly archive the current recording and start a new session on the same VM. Retains prior evidence; refuses while the receiver lock exists. Use after diagnosing recording damage.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.15.0Oct 19, 2026

removedInput schema / properties / browserExecutable

Removed value: -{
-  "description": "Guest browser executable for the playwright and chrome-devtools targets; default is installed Google Chrome.",
-  "type": "string"
-}

addedInput schema / properties / files / items / properties / local / description

Added value: +"Host file in the project folder: relative to it, or absolute inside it; no symlinks."

addedInput schema / properties / guest

Added value: +{
+  "description": "The guest this call acts on: the name relay_acquire answered.",
+  "pattern": "^[a-z0-9][a-z0-9-]{0,47}$",
+  "type": "string"
+}

changedInput schema / properties / workspace / description

Previous value: -"Host directory copied to the guest workspace, opt-in."New value: +"Host directory copied to the guest workspace, opt-in. It lies in the project folder: relative to it, or absolute inside it; no symlinks."

addedInput schema / required
```
Added value: +[
+  "guest"
+]
```

Addedv0.5.1Sep 24, 2026

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false), and the description goes far beyond them: hash-checking, refusal conditions, the 120 s cua-driver capture wait, before/after snapshot dependence on image software, retry limits ('only corrected executable paths may be resubmitted'), and lock behavior. This is exactly the behavioral context an agent cannot infer from the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main action is front-loaded, but the body is a dense wall of run-on sentences with nested parentheticals that mix staging, snapshot, and recording semantics. Each clause carries information, yet resetRecording guidance is stranded at the very end and the whole block would benefit from separation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter mutation tool with no output schema, the description covers refusals, retry semantics, snapshot dependence, and even return semantics ('the result's snapshots says which'). It stops short of 5 only because the relationship to sibling staging/scripting tools is never established.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 83%, so the baseline is 3, but the description adds genuine meaning: `files[].path` destinations land under `support/`, workspace/files locals must be inside the project folder with no symlinks, `nodePath` defaults to `node`, and `cuaDriver` names the executable whose snapshots result. Some of this duplicates the schema, keeping it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource chain: 'Push and hash-check the guest runtime, plus an optional workspace and support files... onto the acquired guest.' An agent knows exactly what the tool does. It does not, however, differentiate itself from siblings like relay_script or relay_finish, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real when/when-not conditions: an image without Node is refused, staging refuses when cua-driver never captures, resetRecording 'refuses while a receiver lock is held', and 'Use after diagnosing recording damage' is explicit guidance. No alternative sibling (e.g. relay_script) is ever named, so 5 is not warranted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server