Skip to content
VIRDX

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:

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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close