---
title: "vx reference"
description: "Every vx command and MCP tool, generated from the code."
image: "https://docs.virdx.dev/img/virdx-social-card.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.virdx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# vx reference

{/* Generated by apps/vx/scripts/reference.py; run `pixi run reference`. */}

**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 challenge`
- [`vx challenge list`](#list_challenges-remote) (`ls`) [remote]
- [`vx challenge submit`](#submit_challenge-remote) [remote]
- `vx cluster`
- [`vx cluster build`](#build_image-remote) [remote]
- [`vx cluster cancel`](#cancel_run-remote) [remote]
- [`vx cluster capacity`](#get_capacity-remote) [remote]
- [`vx cluster get`](#get_run-remote) [remote]
- [`vx cluster get-vxrun-status`](#get_vxrun_status-local) [local]
- [`vx cluster inspect`](#inspect_data-local) [local]
- [`vx cluster list`](#list_runs-remote) (`ls`) [remote]
- [`vx cluster logs`](#get_run_logs-remote) [remote]
- [`vx cluster metrics`](#query_metrics-remote) [remote]
- [`vx cluster review`](#review_job-local) [local]
- [`vx cluster submit`](#submit_run-remote) [remote]
- [`vx cluster submit-vxrun`](#build_and_submit_vxrun-local) [local]
- [`vx cluster validate`](#validate_run-remote) [remote]
- `vx data`
- [`vx data get`](#get_vxdata_resources-remote) [remote]
- [`vx data query`](#query_vxdata-remote) [remote]
- [`vx data types`](#list_vxdata_types-remote) [remote]
- `vx dispatch`
- [`vx dispatch report`](#get_run_report-remote) [remote]
- [`vx dispatch submit`](#dispatch_run-remote) [remote]
- [`vx dispatch usage`](#get_usage-remote) [remote]
- `vx feedback`
- [`vx feedback send`](#send_feedback-remote) [remote]
- `vx guides`
- [`vx guides read`](#read_doc-remote) [remote]
- [`vx guides search`](#search_docs-remote) [remote]
- `vx mcp`
  - `vx mcp install` [local]
  - `vx mcp serve` [local]
- `vx minipage`
  - `vx minipage deploy` [local]
- `vx run`
  - vxrun's own commands: `vx run --help`

```sh
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:

```sh
vx challenge list --challenge bpmri-cspca-prediction
```

MCP arguments:

```json
{
  "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:

```sh
vx challenge submit --challenge bpmri-cspca-prediction --image 'mono/my-model@sha256:<digest>' --title 'my model v2' --metadata '{"model": "v2"}'
```

MCP arguments:

```json
{
  "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@&lt;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:

```sh
vx cluster build --source 'github.com/virdx/mono@<40-char sha>' --context . --dockerfile Dockerfile
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster validate --run spec.yaml --name qc-sweep --runtime-hours 6 --gpus 1
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster submit --run spec.yaml --name qc-sweep
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster list --limit 5 --phase Running
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster get --workflow qc-sweep-x7k2p
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster logs --workflow qc-sweep-x7k2p --since 2h --grep loss --tail 100
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster cancel --workflow qc-sweep-x7k2p
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster capacity --window 1h
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster metrics --expr 'sum(virdxcluster:gpu:used)' --since 24h --step 1h
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster review --repo-path . --cmd 'python train.py' --preemptible
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster inspect --source /mnt/storage/datasets/x --repo-path .
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster submit-vxrun --repo-path . --gpus 1 --dry-run
```

MCP arguments:

```json
{
  "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:

```sh
vx cluster get-vxrun-status --submission-id a1b2c3d4
```

MCP arguments:

```json
{
  "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:

```sh
vx dispatch submit --spec spec.yaml --run-id qc-sweep-001 --target fra
```

MCP arguments:

```json
{
  "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:

```sh
vx dispatch report --run-id qc-sweep-001
```

MCP arguments:

```json
{
  "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:

```sh
vx dispatch usage --group team --since 2026-11-01
```

MCP arguments:

```json
{
  "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:

```sh
vx data types
```

MCP arguments:

```json
{}
```

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:

```sh
vx data query --payload-type patient --where '{"datasource": "essen01"}' --limit 10
```

MCP arguments:

```json
{
  "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:

```sh
vx data get --identifiers patient/bb01
```

MCP arguments:

```json
{
  "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:

```sh
vx guides search --query preemptible
```

MCP arguments:

```json
{
  "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:

```sh
vx guides read --name vx/cluster/submitting-jobs
```

MCP arguments:

```json
{
  "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:

```sh
vx feedback send --kind friction --message 'Agent: submit_run needed three retries ...'
```

MCP arguments:

```json
{
  "kind": "friction",
  "message": "Agent: submit_run needed three retries ..."
}
```

Returns: `{"status": "sent"}`.

Source: https://docs.virdx.dev/vx/reference/index.mdx
