Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
MCP_VM_RELAY_URLNoThe loopback vm-service origin. Non-loopback servers, redirects and physical targets are refused.http://localhost:6240
MCP_VM_RELAY_PYTHONNoThe Python 3 used for the registry lock.python3
VM_ENVIRONMENT_FILENoA selected environment profile; it overrides the URL, state directory and registry above and binds the Tart store.
MCP_VM_RELAY_PROJECTNoThe project directory (the plugin passes Claude Code's). Evidence lands under `relay-evidence/<task>/` there.
MCP_VM_RELAY_SESSIONNoAn explicit session identity. By default each server process takes a fresh random one; a stable identity lets a restarted server reconcile and reattach the enclosure of the same identity.
MCP_VM_RELAY_REGISTRYNoAn explicit task registry file; otherwise an existing compatible `~/AGENTS.md` VM table, or a private managed `registry.md` in the state directory.
MCP_VM_RELAY_STATE_DIRNoHost state directory, otherwise `$XDG_STATE_HOME/mcp-vm-relay` or `~/.local/state/mcp-vm-relay`, one subdirectory per session.

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
relayA

One VM enclosure interface. Required action; run and console-open require intent in reason. search: required application name, optional hard os linux/macos; exact, prefix, substring canonical-name/alias matching. Returns installed versions (possibly null), image keys, OS and architecture; truncated means whole installations were omitted. No allocation, boot, installation, capacity reservation or automatic image choice. Empty success is distinct from catalog errors. probe: default scope=host reports host permissions/activity, VM service availability and owned lifecycle state, not guest readiness. scope=guest checks executables on the owned guest before staging or after repair without installing software; capture/browser readiness remains unverified. Unknown is not idle. acquisition-capabilities: read-only versioned VNC options, no acquisition or ownership recovery. console-resolve: read-only status for the owned lease/environment. console-open: explicit user request only, require userRequested=true, console_id, attempt_id, reason and expected; opens on service-host only, never automatically at acquisition. console-cancel: require console_id and attempt_id; closes managed viewing resources, never releases the VM. Console actions are lifecycle operations without screenshots, not authentication/pixel/human evidence. Resolve uncertain attempts; never automatically replay open. Console status ready is guest preflight, not nested attempt success. macOS requires human Standard sharing of the existing console, not a new Log In session or High Performance display. Never auto-confirm selection; server_enforced_view_only=false and viewer-selection-unverified remain limitations even after transport connects. acquire: one fresh VM for this prompt-composed subagent, register ownership and heartbeat; require task, image and extractions (declare outputs up front, [] allowed); optional ttlHours/env/fullWorkspace/vnc (boolean, default false; prepares sharing without opening). stage: hash-check runtime and optional workspace/files/nodePath/cuaDriver/browser. Corrected setup can be retried after errors; a staged runtime accepts corrected executable paths. resetRecording=true explicitly archives existing recording evidence and starts a fresh recording on the same VM, refusing an existing receiver lock. Staging success does not prove capture readiness. Guest Node and driver must exist; support goes under support/. Linux needs native X11 and cua-driver serve --no-overlay. browser:{} enables fresh persistent guest Playwright; no download or CDP attachment. After every browser event the page is settle-waited (load, network idle, fonts, two frames; settleTimeoutMs, default 5000) and an event that changed the address gets a landing page capture; captures and their records land in workspace/browser-captures, declared as an extraction automatically. run: ONE admitted operation, require reason/kind/step/snapshots. exec needs argv; script needs localPath/language; code needs code/language; cua needs tool and optional args; browser needs one browser event: navigate, click, type, press, read, or snapshot (capture the settled page now, optional name). Do not hide multiple UI interactions in a script-level pair. Ordinary UI means real pointer/keyboard, not direct accessibility. Explicit afterIntervalMs required per event or on text group last, no defaults/stability detection. Choose semantics-appropriate waits, e.g. 100ms text, 500ms dialog, 16ms game, not prescribed values. Text groups are sender-declared consecutive first/member/last events. Failures retain the VM and allow agent-directed repair; never automatically replay uncertain input. timeoutMs defaults to 120000 and accepts integers 1..3600000 independently of snapshot delay. exec diagnostic=true explicitly records command diagnosis/repair without screenshot evidence, including before staging; do not claim visual verification. A run result carries the execution identity and outcome, the guest's bounded stdout/stderr, for a browser event the parsed browser answer (settled facts, landing or snapshot capture, read text), and the saved after-image as a typed image block when that phase was captured and delivered. image: retrieve one saved image without input, capture, directory export, or acquisition. target selects display (sessionId/executionId/phase), application (declared name and relative path for a directory), or reference (imageId). PNG/JPEG/WebP only; originals max64MiB, decoded max40M pixels; preview max2000x2000 and 4MiB base64 (PNG originals are resampled in-process; JPEG/WebP pass through only within bounds). Each image delivery has a 90s deadline and at most three eligible file-transfer attempts; recommend no more than two explicit reference recovery calls. Closed enclosures return stale-reference; delivered originals remain readable by host read. Attachment does not prove provider acceptance or inspection. extract: require names, pull only declared outputs, verify hashes and reject traversal/symlinks/changing sources. finish: extract declared outputs, deliver/verify a portable snapshot package then destroy/unregister; delivery, snapshots, execution and human review are separate. release: abandon, retain available evidence and destroy the owned VM without claiming success; safe to retry failed cleanup. Use finish or release explicitly when done. Session shutdown and agent completion pause renewal without destroying the VM; backend expiration handles abandoned leases. Inspect current owned state through probe after context compaction. Only selected-action fields are permitted; no default action. No physical/local UI targets, video API or spawn API. Text output is capped at 50 KiB / 2000 lines; larger responses are retained in a local file.

relay_statusA

Show this session's owned VM lease (backend binding, guest state, renewal, console observation, last error), staging state and evidence path, plus the project directory, the VM service origin and the selected environment in use; active:false when nothing is owned. Read-only; it does not touch the VM.

relay_reviewB

Verify a delivered relay evidence package (all artifacts, hashes and references) and open its viewer in the local human-facing browser. Human review remains pending.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation4/5

The three top-level tools are clearly separated: relay performs actions, relay_status is a read-only status view, and relay_review verifies evidence packages. The main ambiguity is that relay's probe and console-resolve actions overlap somewhat with relay_status, but the descriptions make the distinction reasonably clear.

Naming Consistency4/5

All tools share the 'relay' prefix and use underscore separation, so the naming is predictable. The main tool is simply 'relay' while the other two are 'relay_<noun>', which is a minor inconsistency but not confusing.

Tool Count3/5

Three tools is a low but plausible top-level count. However, relay is overloaded with many sub-actions (acquire, stage, run, image, extract, finish, release, console operations), so the actual action surface is much larger than the count suggests and would benefit from more top-level decomposition.

Completeness5/5

The relay action surface covers the full VM lifecycle: acquire, stage, run, image retrieval, extraction, finish, release, and console operations. relay_status and relay_review fill the status and verification gaps, so there are no obvious dead ends for the stated VM evidence workflow.