---
title: "Run specs"
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.

# Run specs

`vxrun spec` authors a batch as a single YAML file that pins everything the run
needs: the image (commit and digest), resources and routing, every bundle it
reads, the inputs each item gets, and where outputs go. See the
examples at the end of this guide (packaged with vxrun: `vxrun spec example`
prints one). The file is the lineage of the run;
`vxrun spec validate` checks it offline and reports what still blocks
submission, `vxrun spec graph` prints the data/dependency graph as Mermaid,
and `vxrun spec compile` writes the `run-batch` Workflow for `vxrun batch
plan/build/submit`:

```sh
vxrun spec validate run.yaml            # exit 1 while something blocks submission
vxrun spec graph run.yaml
vxrun spec compile run.yaml --output prepared.yaml   # prints the submit routing flags
vxrun batch submit prepared.yaml --run-id infer-001 --team ve2e --gpu-class rtx-6000-pro
vxrun spec schema > vxrun-spec.schema.json           # editor/CI validation
```

Bundles are named once under `bundles` (`resource` for provenance, `manifest`
+ `sha256` as the pin, a vxs3 `BundleRef`); `inputs` (shared) and each item's
`inputs` select from them with `prefix`, `paths` or `pattern` and land
read-only at `/inputs/<name>`. The cluster fetches them in a separate step
before the command and refuses a changed pin on a retried item. An argv that
mentions `/inputs/<name>` must declare that input. `isolation.network: none`
is declared for a future network-isolated mode; the cluster does not enforce it
yet, so `none` blocks compilation. `env` sets plain variables;
cluster-owned names are refused. `kind: workflow` (steps with `depends`) is
validated and graphed today but does not compile yet. `vxrun spec resolve` pins a
`bundle/<uuid>` resource (it needs the vxdata SDK, an optional import with a
clear error otherwise); `build_image` in vx mcp builds a pushed commit and returns
the digest for `image.ref`.

A spec with `image.ref` filled is also what vxdispatch accepts (`POST
/api/runs` with `target` and a stable `run_id`; `read_doc("vx/cluster/dispatch")` in vx mcp).
That path records the run durably and is the only one to the AWS target.

## Resolve before you size

`vxrun spec resolve run.yaml --write` turns each `bundle/<uuid>` resource into
its catalog pin (`manifest` + `sha256`, needs `VXDATA_TOKEN`) and reads each
pinned manifest once to fill `bytes` on every input selection; an empty
selection is an error here rather than in the cluster. `validate` then
reports `storage`: `shared_bytes` (inputs every item gets), `item_max_bytes`
(the largest item's own inputs), `inputs_max_bytes` (their sum, the most one
item volume must hold) and `minimum_local_cache` (the smallest enum value
leaving as much again for outputs and packing). A `local_cache` below the
floor blocks submission. `shared_bytes` is also the size a future batch-level
shared volume would need.

## The file after submission

`image.ref` and `build` are written by preparation, in place when
`vxrun workflow build` is given the spec (the digest that was built,
the commit it came from and the build's labels), and
`outputs.prefix` + `run` by submission, so the same file records what ran and
where its results are. `vxrun.virdx.com/spec-sha256` on the Workflow is the
fingerprint of the file without those post-submission fields.

## Examples

Packaged with vxrun; `vxrun spec example [batch-spec.yaml|workflow-spec.yaml]`
prints one to copy from.

Source: https://docs.virdx.dev/vxrun/specs/index.mdx
