remote tools run on the central server and in vx mcp; local tools need
your machine and run only in vx mcp. Every tool is also a command,
vx <group> <tool>, with JSON output. Every tool acts as you.
CLI
vx challengevx challenge list(ls) [remote]vx challenge submit[remote]
vx clustervx cluster build[remote]vx cluster cancel[remote]vx cluster capacity[remote]vx cluster get[remote]vx cluster get-vxrun-status[local]vx cluster inspect[local]vx cluster list(ls) [remote]vx cluster logs[remote]vx cluster metrics[remote]vx cluster review[local]vx cluster submit[remote]vx cluster submit-vxrun[local]vx cluster validate[remote]
vx datavx data get[remote]vx data query[remote]vx data types[remote]
vx dispatchvx dispatch report[remote]vx dispatch submit[remote]vx dispatch usage[remote]
vx feedbackvx feedback send[remote]
vx guidesvx guides read[remote]vx guides search[remote]
vx mcpvx mcp install[local]vx mcp serve[local]
vx minipagevx minipage deploy[local]
vx run- vxrun’s own commands:
vx run --help
- vxrun’s own commands:
vx mcp install # register the local server with claude, codex and pi
vx mcp # what your agent runs: stdio, every tool, as your kubectl login
vx mcp serve # the central HTTP server (remote tools only)
vx cluster ls # every MCP tool is a command too: vx <group> <command>
vx run --help # vxrun's CLI: run, batch, workflow, spec, status, ...
vx minipage deploy my-page ./site --title T --description D --author A
vx challenge lschallenge
Nanochallenges: list them and submit images.
list_challenges (remote)
The nanochallenges: slug, title and what they score. Pass challenge for one entry with all its fields.
| Argument | Type | Default |
|---|---|---|
challenge |
str | None |
None |
CLI:
vx challenge list --challenge bpmri-cspca-predictionMCP arguments:
{
"challenge": "bpmri-cspca-prediction"
}Returns: The challenge entries (one with it).
submit_challenge (remote)
Submit a pinned image (repo@sha256:…) to a nanochallenge as the caller. The result goes to vxdata at api (prod feeds the leaderboard). preemptible borrows idle GPUs; false uses the personal queue (Ada GPUs only). metadata lands in the result. Returns the Workflow name: watch it with get_run.
| Argument | Type | Default |
|---|---|---|
challenge |
str |
required |
image |
str |
required |
title |
str |
'' |
limit |
int |
0 |
api |
str |
'https://data.fra.virdx.dev' |
preemptible |
bool |
True |
metadata |
dict[str, str] | None |
None |
CLI:
vx challenge submit --challenge bpmri-cspca-prediction --image 'mono/my-model@sha256:<digest>' --title 'my model v2' --metadata '{"model": "v2"}'MCP arguments:
{
"challenge": "bpmri-cspca-prediction",
"image": "mono/my-model@sha256:<digest>",
"title": "my model v2",
"metadata": {
"model": "v2"
}
}Returns: workflow, the run to watch with get_run; the score lands in vxdata (api).
cluster
Build, submit and watch runs on the cluster; capacity and metrics.
build_image (remote)
Build an image from a pushed commit (github.com/org/repo@<40-char sha>) on the cluster. Safe to repeat: the same source finds the same build. state is running, succeeded (with image_ref, a digest to put in a spec’s image.ref) or failed; while running, call again later. Skip this when the image is already built.
| Argument | Type | Default |
|---|---|---|
source |
str |
required |
context |
str |
'.' |
dockerfile |
str |
'Dockerfile' |
CLI:
vx cluster build --source 'github.com/virdx/mono@<40-char sha>' --context . --dockerfile DockerfileMCP arguments:
{
"source": "github.com/virdx/mono@<40-char sha>",
"context": ".",
"dockerfile": "Dockerfile"
}Returns: state is running (call again later), succeeded with image_ref (zot.../mono/...@sha256:...) or failed with a message.
validate_run (remote)
Check a run spec or native Argo DAG offline; calls nothing. Returns what blocks it, warnings (show any ‘Not repeatable’ one), routing and the inspection. Pass hints for a scheduling recommendation. Use it before submit_run or dispatch_run.
| Argument | Type | Default |
|---|---|---|
request |
RunRequest |
required |
request.run |
dict[str, Any] |
required |
request.name |
str |
required |
request.team |
str |
'' |
request.preemptible |
bool |
False |
request.gpu_class |
Literal['auto', 'rtx-6000', 'rtx-6000-pro'] |
'auto' |
request.image |
str | None |
None |
hints |
Hints | None |
None |
hints.runtime_hours |
float |
required |
hints.checkpoints |
bool |
False |
hints.gpus |
int |
0 |
hints.vram_gb |
int | None |
None |
hints.cpu |
int |
16 |
hints.memory_gi |
int |
128 |
hints.urgency |
Literal['normal', 'urgent', 'background'] |
'normal' |
hints.team |
str | None |
None |
CLI:
vx cluster validate --run spec.yaml --name qc-sweep --runtime-hours 6 --gpus 1MCP arguments:
{
"request": {
"run": {
"apiVersion": "vxrun.virdx.dev/v1alpha1",
"kind": "batch",
"name": "qc-sweep",
"...": "..."
},
"name": "qc-sweep"
},
"hints": {
"runtime_hours": 6,
"gpus": 1
}
}Returns: ok, blocked (empty when it can run), warnings, routing and, with hints, a recommendation (mode, GPU class, reasons).
submit_run (remote)
Submit a run spec (image.ref set) or a native Argo DAG as the caller, after validate_run and the user’s go-ahead. Returns the Workflow name, the run’s id for get_run, get_run_logs and cancel_run.
| Argument | Type | Default |
|---|---|---|
request |
RunRequest |
required |
request.run |
dict[str, Any] |
required |
request.name |
str |
required |
request.team |
str |
'' |
request.preemptible |
bool |
False |
request.gpu_class |
Literal['auto', 'rtx-6000', 'rtx-6000-pro'] |
'auto' |
request.image |
str | None |
None |
CLI:
vx cluster submit --run spec.yaml --name qc-sweepMCP arguments:
{
"request": {
"run": {
"apiVersion": "vxrun.virdx.dev/v1alpha1",
"kind": "batch",
"name": "qc-sweep",
"...": "..."
},
"name": "qc-sweep"
}
}Returns: workflow (e.g. qc-sweep-x7k2p, the run’s id from now on) and the Argo url.
list_runs (remote)
The caller’s recent runs, newest first.
| Argument | Type | Default |
|---|---|---|
limit |
int |
20 |
phase |
Optional[Literal['Pending', 'Running', 'Succeeded', 'Failed', 'Error']] |
None |
CLI:
vx cluster list --limit 5 --phase RunningMCP arguments:
{
"limit": 5,
"phase": "Running"
}Returns: Your runs, newest first: workflow, phase, url.
get_run (remote)
One run by run_id or Workflow name: vxdispatch’s record when it has one (kept after Argo deletes the Workflow), and the live Workflow (phase, steps, why Pods are pending).
| Argument | Type | Default |
|---|---|---|
workflow |
str |
required |
CLI:
vx cluster get --workflow qc-sweep-x7k2pMCP arguments:
{
"workflow": "qc-sweep-x7k2p"
}Returns: dispatch (its record, or null) and workflow (phase, steps, pending reasons).
get_run_logs (remote)
Logs of a run or a build (vxbuild-…): live, or from Loki once Pods are gone.
| Argument | Type | Default |
|---|---|---|
workflow |
str |
required |
since |
str |
'1h' |
grep |
str | None |
None |
tail |
int |
200 |
CLI:
vx cluster logs --workflow qc-sweep-x7k2p --since 2h --grep loss --tail 100MCP arguments:
{
"workflow": "qc-sweep-x7k2p",
"since": "2h",
"grep": "loss",
"tail": 100
}Returns: source is live (per pod) or loki (after the pods are gone), with the lines.
cancel_run (remote)
Stop one of the caller’s own runs: through vxdispatch when it owns it, else Argo.
| Argument | Type | Default |
|---|---|---|
workflow |
str |
required |
CLI:
vx cluster cancel --workflow qc-sweep-x7k2pMCP arguments:
{
"workflow": "qc-sweep-x7k2p"
}Returns: The run is stopped; who stopped it and how.
get_capacity (remote)
The caller’s Kueue queues and every GPU with its holder and utilisation.
| Argument | Type | Default |
|---|---|---|
window |
str | None |
None |
CLI:
vx cluster capacity --window 1hMCP arguments:
{
"window": "1h"
}Returns: Your personal and preemptible queues, every GPU with holder and utilisation, a summary.
query_metrics (remote)
PromQL through Grafana as the caller; instant, or a range over since.
| Argument | Type | Default |
|---|---|---|
expr |
str |
required |
since |
str | None |
None |
step |
str |
'1m' |
CLI:
vx cluster metrics --expr 'sum(virdxcluster:gpu:used)' --since 24h --step 1hMCP arguments:
{
"expr": "sum(virdxcluster:gpu:used)",
"since": "24h",
"step": "1h"
}Returns: The PromQL series as {labels, points, value}.
review_job (local)
Check a job’s code path, Dockerfile and settings in a local checkout against the cluster rulebook: storage, compute and repeatability (code from shared mounts, fetches at run time, unpinned bases or installs). Follows cmd through first-party imports and Hydra configs (all_files=true scans the whole project). Returns findings with file:line evidence and a fix, plus data_sources for inspect_data. Pass the preemptible/local_cache you intend to submit with. Findings are evidence, not verdicts. Read-only.
| Argument | Type | Default |
|---|---|---|
repo_path |
str |
required |
cmd |
str | None |
None |
entrypoint |
str | None |
None |
preemptible |
bool | None |
None |
local_cache |
str | None |
None |
all_files |
bool |
False |
team |
str | None |
None |
CLI:
vx cluster review --repo-path . --cmd 'python train.py' --preemptibleMCP arguments:
{
"repo_path": ".",
"cmd": "python train.py",
"preemptible": true
}Returns: findings with file:line evidence and a fix each, and data_sources for inspect_data.
inspect_data (local)
Shape of a dataset a job reads: an absolute NFS path, an s3://bucket/prefix/, or (table=true) a table whose first path-like column lists the files. Returns counts, sizes, formats, Zarr layout, findings and a suggested action. Local paths must be under /mnt/storage, /mnt/artifacts, /mnt/scratch, /cache or repo_path. Set scratch=true for ad-hoc scratch data. Bounded metadata scan, read-only; it does not measure IOPS.
| Argument | Type | Default |
|---|---|---|
source |
str |
required |
table |
bool |
False |
policy |
str |
'bulk_nvme_v1' |
repo_path |
str | None |
None |
scratch |
bool |
False |
CLI:
vx cluster inspect --source /mnt/storage/datasets/x --repo-path .MCP arguments:
{
"source": "/mnt/storage/datasets/x",
"repo_path": "."
}Returns: Counts, sizes, formats, findings and a suggested action (keep, bundle, …).
build_and_submit_vxrun (local)
Build and run a local repository from its .vxrun.yaml (the vx run run path). dry_run=true returns the plan (settings, branch, pending_changes, blocked, warnings) and a plan_token; it changes nothing. Show it, get the user’s yes, then call again with plan_token: that commits and pushes the project scope, builds and submits in the background and returns a submission_id for get_vxrun_status.
| Argument | Type | Default |
|---|---|---|
repo_path |
str |
required |
cmd |
str | None |
None |
entrypoint |
str | None |
None |
gpus |
int | None |
None |
gpu_class |
str | None |
None |
preemptible |
bool | None |
None |
cpu |
str | None |
None |
memory |
str | None |
None |
local_cache |
str | None |
None |
team |
str | None |
None |
dry_run |
bool |
False |
plan_token |
str | None |
None |
agent |
str | None |
None |
CLI:
vx cluster submit-vxrun --repo-path . --gpus 1 --dry-runMCP arguments:
{
"repo_path": ".",
"gpus": 1,
"dry_run": true
}Returns: First the plan and a plan_token; called again with the token, a submission_id.
get_vxrun_status (local)
Progress of a build_and_submit_vxrun, including its build: steps, then the workflow name, Argo URL and output path. state is running, finished (submitted, not completed) or failed. Kept in this process only; once the workflow exists, use get_run. Without submission_id, lists this session’s submissions.
| Argument | Type | Default |
|---|---|---|
submission_id |
str | None |
None |
tail |
int |
40 |
CLI:
vx cluster get-vxrun-status --submission-id a1b2c3d4MCP arguments:
{
"submission_id": "a1b2c3d4"
}Returns: state running, finished or failed, the steps so far, then workflow and url.
dispatch
Batch runs through vxdispatch, which keeps their record, usage and cost.
dispatch_run (remote)
Dispatch a batch run spec (image.ref pinned) to vxdispatch, after validate_run and the user’s go-ahead. vxdispatch submits it and keeps the record. Posting the same run_id again returns the existing run.
| Argument | Type | Default |
|---|---|---|
spec |
dict[str, Any] |
required |
run_id |
str |
required |
target |
Literal['fra', 'aws', 'auto'] |
'fra' |
CLI:
vx dispatch submit --spec spec.yaml --run-id qc-sweep-001 --target fraMCP arguments:
{
"spec": {
"apiVersion": "vxrun.virdx.dev/v1alpha1",
"kind": "batch",
"name": "qc-sweep",
"...": "..."
},
"run_id": "qc-sweep-001",
"target": "fra"
}Returns: The run’s record: state (submitted, pending-approval, rejected), cluster, url.
get_run_report (remote)
vxdispatch: what a finished run used and cost. Metrics (granted vs used), every pod attempt, cost estimates and the cloud compatibility card. Right-size the next run here.
| Argument | Type | Default |
|---|---|---|
run_id |
str |
required |
CLI:
vx dispatch report --run-id qc-sweep-001MCP arguments:
{
"run_id": "qc-sweep-001"
}Returns: metrics, pods, cost, cloud; a part is unavailable until the run finished.
get_usage (remote)
vxdispatch: runs, GPU/CPU/wall hours, preempted and OOM-killed pods and cost estimates, per user, team or cluster. You see your own unless you are an admin. ISO dates.
| Argument | Type | Default |
|---|---|---|
group |
Literal['user', 'team', 'cluster'] |
'user' |
since |
str | None |
None |
until |
str | None |
None |
CLI:
vx dispatch usage --group team --since 2026-11-01MCP arguments:
{
"group": "team",
"since": "2026-11-01"
}Returns: One row per team: runs by outcome, GPU/CPU/wall hours, cost estimates.
data
Read-only vxData queries.
list_vxdata_types (remote)
vxdata payload types queryable with query_vxdata.
| Argument | Type | Default |
|---|
CLI:
vx data typesMCP arguments:
{}Returns: The payload type names, e.g. patient, histo_scan.
query_vxdata (remote)
Query one vxdata payload type: public rows centrally, your own access in vx mcp with VXDATA_TOKEN set. where holds field == value filters; at most 200 rows.
| Argument | Type | Default |
|---|---|---|
payload_type |
str |
required |
where |
dict[str, Any] | None |
None |
fields |
list[str] | None |
None |
limit |
int |
50 |
CLI:
vx data query --payload-type patient --where '{"datasource": "essen01"}' --limit 10MCP arguments:
{
"payload_type": "patient",
"where": {
"datasource": "essen01"
},
"limit": 10
}Returns: Up to 200 rows as objects.
get_vxdata_resources (remote)
Fetch vxdata resources by identifier (e.g. patient/bb01).
| Argument | Type | Default |
|---|---|---|
identifiers |
list[str] |
required |
CLI:
vx data get --identifiers patient/bb01MCP arguments:
{
"identifiers": [
"patient/bb01"
]
}Returns: The resources as objects.
guides
The docs site, docs.fra.virdx.dev: search and read its pages.
search_docs (remote)
List the pages of docs.fra.virdx.dev (name, title, description), or search their text. A name is the page’s path, e.g. vx/cluster/submitting-jobs.
| Argument | Type | Default |
|---|---|---|
query |
str | None |
None |
CLI:
vx guides search --query preemptibleMCP arguments:
{
"query": "preemptible"
}Returns: Matching pages (name, title) with snippets.
read_doc (remote)
Read one docs.fra.virdx.dev page as markdown, by name (see search_docs).
| Argument | Type | Default |
|---|---|---|
name |
str |
required |
CLI:
vx guides read --name vx/cluster/submitting-jobsMCP arguments:
{
"name": "vx/cluster/submitting-jobs"
}Returns: The page’s markdown.
feedback
Tell the platform team what was hard.
send_feedback (remote)
Send feedback (kind: worked, friction, wish or gap) to the platform team. Use it on your own when a workflow is annoying, cumbersome, error-prone or too complex, or when you see an improvement or automation; say what happened and what would fix it. Start the message with ‘Agent:’ for your own observation, or ‘User:’ only for the user’s actual words; never invent them. Do not include patient data in feedback, and no secrets.
| Argument | Type | Default |
|---|---|---|
kind |
Literal['worked', 'friction', 'wish', 'gap'] |
required |
message |
str |
required |
CLI:
vx feedback send --kind friction --message 'Agent: submit_run needed three retries ...'MCP arguments:
{
"kind": "friction",
"message": "Agent: submit_run needed three retries ..."
}Returns: {"status": "sent"}.