Skip to content
VIRDX

vx reference

Every vx command and MCP tool, generated from the code.

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 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 ls

challenge

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-prediction

MCP 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 Dockerfile

MCP 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 1

MCP 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-sweep

MCP 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 Running

MCP 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-x7k2p

MCP 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 100

MCP 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-x7k2p

MCP 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 1h

MCP 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 1h

MCP 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' --preemptible

MCP 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-run

MCP 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 a1b2c3d4

MCP 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 fra

MCP 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-001

MCP 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-01

MCP 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 types

MCP 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 10

MCP 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/bb01

MCP 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 preemptible

MCP 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-jobs

MCP 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"}.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close