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 validationBundles are named once under bundles (resource for provenance, manifest
sha256as the pin, a vxs3BundleRef);inputs(shared) and each item’sinputsselect from them withprefix,pathsorpatternand 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: noneis declared for a future network-isolated mode; the cluster does not enforce it yet, sononeblocks compilation.envsets plain variables; cluster-owned names are refused.kind: workflow(steps withdepends) is validated and graphed today but does not compile yet.vxrun spec resolvepins abundle/<uuid>resource (it needs the vxdata SDK, an optional import with a clear error otherwise);build_imagein vx mcp builds a pushed commit and returns the digest forimage.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.