Reference / blueprint
A composition of one or more components into a single deployable application.
JSON Schema · Specification · Examples · Source
This reference is generated from the schema bundle and is informative. Where it differs from the specification, the specification governs. A documented default is an annotation: no validator inserts it.
Structural and type validation only: cross-document reference resolution, slug/directory agreement, and platform capability checks are separate validation layers. See spec.md.
A composition of one or more components into a single deployable application.
Structural and type validation only: cross-document reference resolution, slug/directory agreement, and platform capability checks are separate validation layers. See spec.md.
Document kind discriminator. Must be BLUEPRINT.
Version of the Musher specification this document is written against.
Where one receiving input’s value comes from.
Exactly one of parameter, node with output, or value is present. The key present selects the form.
node requires output.
output requires node.
Node whose output supplies the value.
Output of that node.
Installation parameter supplying the value.
Logical non-secret literal value.
The compute a workload node runs on: a compute profile, and optional placement pins that narrow where it is placed. Required on a node whose component runs, forbidden on one whose component is EXTERNAL. See spec.md §4.3.
Optional pins narrowing the eligible hosts. Absent and a block with no pin set mean the same thing.
Compute profile slug in family.tier.size form, for example general.standard.small. The profiles actually on offer are published at https://api.musher.dev/v1/reference/compute-profiles.
Lookahead-free, so it compiles under RE2 as well as ECMA-262. Only the grammar is here; membership is a capability check (spec.md §4.3).
Parameter whose from names a connection, ${{ connections.<path> }}.
Identity and description of a blueprint document. The blueprint carries the item’s revision; its sibling listing carries none. See spec.md §3.
What this application is, in one or two plain-text sentences. Required to publish.
spec.md §3 BP-ID-004. Plain text, never rendered as Markdown, bounded like a listing summary. It describes the deployable application to the people who install and operate it; the sibling listing’s summary remains the storefront copy. Structurally optional so a blueprint can be stored while it is being written; BP-ID-005 requires it of a published one.
Item revision: the position of this release in the catalog item's lineage. Orders releases and nothing more.
Item slug, which must equal the item's directory name.
When componentRef matches ^\.{1,2}/, revision must not be present.
Otherwise, revision is required.
Explicit supplier for each receiving input, keyed by the component’s input name.
Reference to the component document this node deploys, in one of two forms. A repo-local reference begins ./ or ../ and ends .yaml or .yml, and resolves relative to the directory holding this blueprint document; its version is the referenced document's metadata.revision. A published reference is the component's UUID, which names the component across all its revisions, and requires revision to select the one deployed. The relative-path prefix is what tells the two apart: a bare slug is not distinguishable from a UUID.
Both patterns are lookahead-free so they compile under RE2 as well as ECMA-262. A path segment must begin with a letter or digit, which is how . and .. are excluded as interior segments without a negative lookahead; that leaves one spelling per target and keeps the containment check in the semantic phase from having to normalise first.
Compute profile and placement for a node whose component runs. Omitted, and forbidden, where the component is EXTERNAL; that agreement is a semantic check against the component (spec.md §4.3).
The connection parameter that satisfies each of the component’s connection requirements, keyed by requirement name.
Exposure of each of the component’s endpoints, keyed by endpoint name; an endpoint left out is PRIVATE. A WORKER endpoint is never PUBLIC.
Lineage version pinned by a published reference. Required on a published reference and rejected on a repo-local one, where the referenced document's own metadata.revision supplies it.
Storage allocated to each of the component’s volumes, keyed by the component’s volume name.
Named installation value, bound explicitly by the nodes that consume it.
When generator is present, default must not be present.
When generator is present, from must not be present.
When from is present, default must not be present.
Logical default, replaced by a submitted value. No interpolation.
One whole reference to a value outside the documents: ${{ variables.
Persisted credential generation; a submitted value is rejected.
Optional install-form presentation.
Number of random bytes generated for the value.
Encoding applied to securely generated random bytes.
Presentation metadata for an install-form parameter.
spec.md §5.4. The control is derived from the logical schema of the inputs the parameter is bound to rather than declared, so this carries only what a derivation cannot supply.
Human-readable label for each enum member, keyed by the member it names. A member left unlabelled is offered as it is spelled.
Example values illustrating the form a value takes. Never submitted; parameter.default supplies an omitted submission.
Human-readable label shown on the install form.
Relative position of the field within the form. Lower sorts first; a parameter declaring no order sorts after every parameter that declares one.
Standing of the field in the form: PRIMARY is offered directly, SECONDARY behind a disclosure the deploying user opens.
Optional pins that narrow the hosts eligible for the node’s compute profile. A pin never changes the compute the profile names. See spec.md §4.4.
Every term pin is a lowercase token rather than a member of a closed set: the grammar is fixed by this contract, the vocabularies are versioned catalog context, not part of this contract (spec.md §4.4). cpuDedication is the exception: two values are the whole concept.
Required accelerator interconnect, such as nvlink or pcie. Omit to pin nothing. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Required accelerator runtimes, such as cuda. An empty array pins nothing, and a term may not repeat. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Exact accelerator SKU class to pin. Omit to pin nothing. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Permitted CPU architectures, such as x86_64 or arm64. An empty array pins nothing, and a term may not repeat. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Whether the node's vCPU must be dedicated rather than shared. Omit to pin nothing. This is the one pin whose vocabulary this contract closes; see spec.md §4.4.
Minimum accelerator VRAM in GiB. Omit to pin no floor.
Required network class. Omit to pin nothing. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Opaque identity and immutable version of the private installation snapshot; never a secret-derived hash.
Identity and version of each organization variable the installation read.
When source is EXTERNAL, compute must not be present.
When source is EXTERNAL, gitCommit must not be present.
When source is EXTERNAL, imageDigest must not be present.
When source is EXTERNAL, exposure is required.
When source is EXTERNAL, volumes is required.
Otherwise, compute is required.
Otherwise, imageDigest is required.
When source is GIT, gitCommit is required.
Otherwise, gitCommit must not be present.
Composition, explicit input suppliers, allocation and installation parameters.
Named component instances.
Every value the installation takes from outside the documents: submitted, generated, organization variables and connections. Nothing binds by name.
An opaque identity and an immutable version.
Minimum provisioned IOPS for this volume. Omit to pin no floor.
Allocated size, at or above the component’s minSizeGiB.
Required storage class for this volume, such as local-nvme. Omit to pin nothing. The permitted terms are not a vocabulary this contract defines; see spec.md §4.3.