The .vio Artifact Specification

The VIO Project · Authors: Vivien Roggero, Adi Vora — Viorant Inc.

The portable, signed deployment artifact for AI agents. A .vio is what gets handed from "the engineer composed this agent" to "this agent is running somewhere."

What a .vio is#

A .vio is a single self-contained, signed bundle of AI-infrastructure artifacts. It is the unit a conforming deployer consumes. One file carries everything needed to verify provenance and deploy: a manifest, the artifact bodies (or references to them), and the signatures that bind them.

Three concerns stack — none reinvents the others:

Sign      = how an artifact (or a whole bundle) is signed, verified, trust-scored   → dependency
.vio      = how signed artifacts are packaged together                              → this document
Deployer  = verifies the .vio via Sign, then deploys                                → Deployer specification

Signing is optional; its representation is not. An unsigned bundle is a valid bundle and is what a local compile-and-run produces. When a bundle is signed, the signing ceremony, key registry, verification engine, trust scoring and enforcement gate are defined by Viorant Sign (sign.viorant.ai, coming soon). This document only defines how Sign's outputs are represented inside a .vio; it does not re-specify cryptography. Sign treats vio_bundle as a first-class signable asset type with a defined canonicalize_vio_bundle() (RFC 8785 canonicalization); the format below is built to match.

1. Physical format#

• Encoding. A single UTF-8 YAML document. Chosen over JSON because every artifact body is multi-line text — prompts, skills, memory, agent definitions — and YAML block scalars keep them verbatim and diff-able instead of base64 or escaped one-liners. Chosen over an archive because .vio is a first-class format, not a renamed container.
• Top-level keys. vio (format-version integer), manifest (authoritative metadata, signed as a unit), artifacts (the bodies).
• Plain-YAML guarantee. A .vio uses only the portable YAML core — UTF-8, block scalars for bodies, base64 (ASCII) for signatures, plain scalars, maps and sequences. No anchors or aliases, no custom !tags, no merge keys (<<), no binary framing. Any YAML parser or formatter can open and lint a .vio with no format-specific tooling.
• Formatting versus the signature. Verification runs over the canonical form (canonicalize_vio_bundle, RFC 8785), not the on-disk bytes, so cosmetic reformatting — key order, flow versus block style, quoting, indentation — is signature-safe. The one exception: a formatter that rewrites a block scalar (| to |-, trailing newline, internal whitespace) changes that artifact's body string, therefore its digest, therefore its sig. That is tamper detection working as designed. Read and lint with any tool freely; only an authoring or save path must preserve block scalars exactly (use a canonical writer) or re-sign.

1.1 The embed-versus-reference rule#

A single text document cannot hold model weights or multi-file code. So:

The deployer resolves a ref on the target at deploy time; the manifest digest guarantees the resolved bytes are the ones that were signed for.

1.2 Manifest field reference#

1.3 Artifact index entry#

Each row in manifest.artifacts[] is the authoritative descriptor for one artifact:

1.4 Worked example#

A CrewAI research agent bundling a signed prompt, one declarative and one executable skill, a memory reference and a self-hosted model reference. The full document is on the front page; the shape is reproduced in the reader.

Three properties of this design:

1. Self-describing. The agent body references siblings by local id; the deployer wires them at deploy. No external lookup is needed to understand composition.
2. Per-artifact deploy. Routing is declared, not inferred — the deployer reads deploy and sends each artifact to Runtime, Registry or Store.
3. Forward-compatible. Unknown type / framework / deploy / kind values are reserved — a verifier that does not understand a value rejects cleanly rather than mis-deploying. Unknown keys, by contrast, are also rejected — so adding a field costs a format version. The format does not grow without breaking older readers.

1.5 Templated artifacts — sections, variables, binding#

An authored artifact is a template, not a finished string. A prompt's content is a map of framework-neutral sections; the .vio stays framework-neutral and a framework adapter assembles the native form at instantiate — the same principle as {{var}}.

Prompt artifact shape

Variable schema

variables:
  - { name: client, type: string, required: true,  source: input }
  - { name: today,  type: date,   required: false, source: env,    default: "now()" }
  - { name: tier,   type: enum,   values: [fast, deep], default: deep, source: static }

source ∈ input | env | task | connector | secret | static:

• input — supplied by the caller at each run (kept dynamic)
• env / task / connector — resolved by the system: deploy environment, upstream task output, tool result
• secret — a secret://org/team/key reference, resolved at run from a secret store; the value never enters the .vio
• static — baked at compose time (effectively fixed)

Binding — the explicit "what stays dynamic" — maps each variable to its source. Bindings sit at the artifact level (so a lone prompt runs on its own) and an agent may override them when it composes the prompt. The override is recorded in the agent's signed content, leaving the prompt's signature intact. The agent aggregates unbound input variables into its inputs contract; a run that omits a required input fails validation before execution.

Why templates, not finished strings. Values bind at runtime, outside the signature — so one signed template serves every run without re-signing, and injected values are still bound to a verified template (§2.4).

1.6 Skills and tools#

A skill is a file tree, not one file. Skills are directories — SKILL.md plus scripts/, references/ and assets. The tree is represented as a files map keyed by relative path, plus an entry pointer; the manifest index entry carries entry and the one digest over the canonicalized tree:

# manifest index entry
- { id: research, type: skill, kind: executable, runtime: python,
    entry: scripts/run.py, deploy: runtime/standalone, digest: sha256:…, sig: base64… }

# artifacts body
- id: research
  type: skill
  entry: scripts/run.py
  files:
    SKILL.md:                  | …     # how and when to use
    scripts/run.py:            | …     # entrypoint
    scripts/helpers.py:        | …
    references/methodology.md: | …
  tools: [ … ]

• The tree is the signed unit. digest is sha256 over the canonicalized file map (sorted paths, per-file NFC) — exactly Sign's canonicalize_skill. Renaming a path or editing any file breaks the signature; paths are part of the signed structure, not just contents.
• Embed-versus-reference still applies. Small text tree → inline files; heavy or binary tree (vendored dependencies, large assets) → ref plus digest (packed archive or OCI image), like models.
• Single-file skills keep the content: | shorthand (a one-file tree); files is the general form. The same entry/files model applies to declarative skills (just SKILL.md).

A skill also declares the tools it uses. Tools come in two kinds:

Tool declaration on the skill artifact pins the exact tool and, for MCP, the connector and scopes — least privilege:

tools:
  - { ref: http_get,   kind: viorant }
  - { ref: serp_query, kind: mcp, connector: serpapi, scopes: [search.read] }

Connectors are control-plane references, never packaged in the .vio. A connector is org- or team-specific, OAuth-bound infrastructure — not a portable, signable artifact. The bundle surfaces its connector dependencies at the manifest level so a deployer can gate and resolve auth without parsing every skill body:

manifest:
  requires:
    - { connector: serpapi, scopes: [search.read], auth: oauth }

Capability is signed; credentials are not. The skill's signed content includes its tools declaration (connector and scopes), so a signed skill has a tamper-proof, auditable capability surface — you cannot add a tool or widen a scope without breaking the signature. OAuth tokens never enter the .vio: they live in the control-plane connector store and are injected to the runtime at run via a connection://org/team/connector handle (the same shape as the secret:// variable source; source: connector covers tool-result values).

1.7 Models and inference#

The model type covers local, self-hosted models only. A model artifact is a reference plus an inference descriptor — never weights. The .vio carries a model://… ref (digest-pinned) plus the descriptor a deployer needs to stand it up, on the manifest index entry so it is covered directly by the bundle signature; the model itself stays body-less.

- { id: llama, type: model, deploy: runtime, ref: "model://viorant/llama3-8b",
    engine: vllm, quantization: q4_k_m, context_length: 8192, served_as: llama3-8b,
    digest: "sha256:7c33…" }   # no sig — integrity-only tier

• Integrity-only, descriptor included. A model carries no sig — you cannot author-sign someone's weights — but the descriptor sits in the signed manifest and the digest covers the resolved weights. Both how it is stood up and what bytes run are tamper-evident (§2.3).
• Hosted models are connectors, not model artifacts. A hosted LLM is not a type: model. type: model means self-hosted weights you deploy; a hosted model is an API credential you resolve, so it rides the connector rail — a control-plane connection, key injected at run via connection://, exactly like SerpAPI. The two trust and deploy profiles (deploy a container versus resolve a credential) stay cleanly separated.

Decode parameters are agent-level — not model- or prompt-level. How to stand the model up is the model's concern; how to sample it is how the agent uses it. Decode params (temperature, max_tokens, top_p, stop, …) layer like bindings:

# agent body
model:
  ref: llama
  params: { temperature: 0.2, max_tokens: 1500 }   # agent override

Precedence is run > agent > model-default: a model may publish recommended params on its manifest entry, the agent overrides, and a run may override per invocation. Params are config, not secrets — they live in the file as part of the agent's signed content. A prompt stays sampling-neutral, so params are never prompt-level.

1.8 Memory bodies and the layer field#

A memory artifact ships its .memory.md text inline as a body. A workspace holds two structurally identical kinds of memory — a curated seed the user authored, and an agent's local runtime scratch written by a remember tool — so the body declares which it is:

artifacts:
  - id: 01M1NC0WFNSS0WWN1690VY2FR8
    type: memory
    layer: seed                       # curated — ships with its body text intact
    content: |
      ---
      meta: {id: 01M1NC0WFNSS0WWN1690VY2FR8, schemaVersion: "1"}
      name: Memory 1
      description: Persistent memory for agent runs.
      ---
      Viorant is an AI infrastructure company…
  - id: 01KYRN79YYQ841RD37EKSMGKK9
    type: memory
    layer: runtime                    # agent-local scratch — frontmatter only, body empty
    content: |
      ---
      meta: {id: 01KYRN79YYQ841RD37EKSMGKK9, schemaVersion: "1"}
      name: confluence-updates
      description: Persistent memory for agent runs.
      ---

• Omitted means seed. A pre-layer bundle parses unchanged and is read as curated content — which is what those bundles actually carried. This is the safe default direction.
• It lives on the body, not the manifest index entry. The body is where the deployer and runner read from; widening the index too would double the compatibility surface for no consumer.
• It is not part of the digest subject. A memory artifact digests { content } only, so adding or changing layer leaves every existing manifest.artifacts[].digest valid — no forced re-export, no digest_mismatch on already-deployed bundles.
• Materialization is layer-driven. A deployer writes seed → {id}.memory.md at the memory root and runtime → .runtime/{id}.memory.md, so the instance classifies each memory correctly on its first run rather than only after its first write.
• A runtime body ships frontmatter-only, but it still ships. The producer emits the parsed frontmatter with an empty body: the agent's accumulated local history stays local, while the ULID binding survives. Omitting the artifact entirely is not an equivalent optimization — an absent write target fails the first run with a dangling reference.
• A redeploy never clobbers accumulated runtime state. The deploy target checks for an existing runtime object before writing and skips it, emitting a preservation notice instead.
• Compatibility runs consumers-first. The memory body schema is strict and the runtime parses the whole bundle at boot, so a bundle carrying layer is rejected by a runtime built against a pre-layer schema. Producers must ship after consumers — the reverse of the usual order.

2. How signing is represented in a .vio#

The full cryptography belongs to Sign; this section defines only what appears in the file.

2.1 Two-tier trust#

2.2 Two signing domains#

• Per-artifact (sig). Each authored artifact is itself a Sign asset with its own signature, so it stays independently verifiable even when pulled out of this bundle — a signed prompt reused from a registry, for example. Algorithms per Sign algo_id: default 0x02 = RSA-2048 + ECDSA-P256; 0x04 = Ed25519; 0x03 = with Dilithium (post-quantum). The authoring tool runs the Sign ceremony when the artifact is authored.
• Bundle (vio_bundle signature). The whole .vio is signed as one Sign vio_bundle asset over the canonical-YAML form of the manifest (canonicalize_vio_bundle(), RFC 8785). Because manifest.artifacts[] lists every artifact's digest, this single signature transitively binds all content — including the digest-only memory and model.

2.3 Why digest-only is still tamper-evident#

A model cannot be author-signed, but its digest sits inside the manifest that is signed as a vio_bundle. Tampering with the model on the target changes its hash; the manifest digest no longer matches; bundle verification fails. Reference-only artifacts therefore get integrity without authorship: provenance is not claimed, but tampering is caught. The model's inference descriptor lives in the manifest index entry, so it is covered directly by the bundle signature; the weights digest additionally catches tampering with the resolved weights on the target.

2.4 What is signed for a templated artifact#

The signed or digested content of a prompt or skill is the whole authored structure. For a prompt: mode, the system/user sections, the variables schema and default bindings. For a skill: its code or text plus its tools declaration (connector and scopes) — canonically serialized (RFC 8785), never the bound values or OAuth tokens. Consequences:

• Tampering with a section, adding a stray {{slot}}, changing a variable's type, redirecting a binding (e.g. to a different secret://…), adding a tool or widening a connector scope → breaks the signature.
• Filling {{client}} = "Acme", or injecting an OAuth token or tool result at runtime → does not touch the signature (values and credentials live outside the signed content).

So verification happens on the template; interpolation and framework assembly happen after verification, at instantiate or run. This is exactly why a finished string would be wrong — it would force re-signing per run, or leave injected values bound to an unverified blob.

3. Implemented subset#

The specification above is the full target. The current reference implementation exercises a deliberate subset of it. This section is the line between "the standard" and "what is built".

Implemented — the local compile-and-run path

• A workspace (a folder of authored assets) compiles to a .vio: tree-shake (only assets reachable from the composed agents ship) → inline-resolve (resolve id-bound refs via the per-workspace discovery scan) → serialize to the YAML bundle above.
• Run is compile-then-run, always, through .vio. A local run compiles the workspace to an unsigned, in-memory .vio and hands it to the local runner. This removes dev/prod drift — what you run locally is the same artifact shape you later deploy.
• CrewAI only (framework: crewai); single-agent or within-crew composition.
• Format features exercised: the manifest and artifact index; embedded prompt, skill and agent bodies; the templated-artifact model (sections, variables, bindings, two-facet output); id-based refs; memory bodies with layer; the models rail (self-hosted ref and descriptor) and the connector rail (hosted models and MCP tools resolved at run).

Specified, not yet built

• Signing — the sig / vio_bundle signature representation (§2). The current compile produces an unsigned bundle; signing lands with the Sign substrate and the signed-deploy path.
• Off-machine deploy — the deploy gates and the three destinations. The current path is local compile-and-run; signed .vio plus remote deploy sit later in the release train.
• Multi-framework — LangChain, AutoGen and ACP adapters are future; the format is already neutral, only the CrewAI adapter is built.

4. Scope notes#

• Memory ships an inline body. The format reserves type: memory and the store destination; a memory artifact carries its .memory.md text inline plus a layer declaring curated seed versus agent-local scratch (§1.8).
• Model = reference, never payload. Weights are never embedded; a .vio carries a model://… ref, a digest and an inference descriptor on the manifest entry. Standing the model up is the deployer's job. Hosted models are not type: model — they ride the connector rail (§1.7).
• Reserved compositions. prompt, skill, memory, model and bundle are valid compositions, but a standalone non-runnable artifact (a lone prompt, say) deploys to a registry, not a runtime.

5. Open questions#

• Canonical-YAML edge cases for vio_bundle signing (block-scalar trailing-newline rules) — inherit Sign's canonicalizer exactly; pin a round-trip test.
• Whether requires[] should also pin a registry coordinate (not just {ref, digest}) so a bundle can require an artifact that lives only in a registry, not inline. Leaning yes, post-v1.
• Multi-agent crews (composition: bundle) — threading typed source: task results between agents; the run contract already covers it, the bundle composition surface is the open thread.

Proposals against any open question go through the process in Governance. Reserved values are listed in the Reference.

Governance

Charter#

Editors: Vivien Roggero (CEO, Viorant) and Adi Vora (CTO, Viorant) author and maintain the specification. Authorship per revision is tracked on the Contributors page. The work is published as the VIO Project.

On the name. .vio takes its extension from Viorant, where the format originated. Verifiable Intelligence Object is a descriptive expansion adopted afterwards, not the origin of the letters. The format is maintained independently of any single implementation; the specification, this site and the repository are not hosted on a vendor domain.

The .vio artifact format exists so that an agent composed in one tool can be verified and deployed by another, without either reinventing the format. Its scope is packaging: how prompts, skills, memory, models and agents are bundled, digested and signed. It deliberately does not define cryptography (Sign), scheduling (deployers) or framework semantics (adapters).

Four commitments hold across revisions:

1. Readable without us. The plain-YAML guarantee is not negotiable. A revision that requires format-specific tooling to parse is out of scope.
2. Additive by default. New fields default to the behavior of bundles that omit them. The memory layer field — optional, defaulting to what existing bundles carried, outside the digest subject — is the template.
3. Reserved, not ignored. Unknown values in enumerated fields cause rejection, never a guess. Silent acceptance is how a deployer mis-deploys.
4. The built subset is published. The gap between the specification and its reference implementation is stated in the specification itself and kept current.

Change process#

Load-bearing decisions are recorded as numbered architecture decision records. A change to the format follows the path an ADR takes: proposal with the problem stated and alternatives named, review by the editors, acceptance with a date, and — where a decision supersedes an earlier one — an explicit note on the superseded record. The specification text then changes in a numbered revision that cites the ADR.

Proposals that touch the reserved value sets, the digest subject of any artifact type, or the canonical form must include a compatibility statement: what existing bundles do under the change, and whether producers or consumers ship first.

Versioning#

vio: N

The format version, an integer at the top of every bundle. It increments only when a reader built against the previous version could misread a bundle. Additive fields do not increment it.

Specification revision

The prose document carries a revision number and date. Revisions can add fields, tighten wording or record errata without changing vio.

manifest.version

The package's own semantic version, chosen by its author. Unrelated to the format version.

Changelog#

Errata#

Glossary#

artifact

One of the five typed units a bundle packages: prompt, skill, memory, model, agent.

authored artifact

An artifact with a sig — prompt, skill or agent. You sign what you author.

binding

The mapping from a variable to its source; the explicit statement of what stays dynamic.

bundle

A whole .vio document; also the composition value for multi-agent packages.

canonical form

The RFC 8785 serialization that digests and signatures are computed over.

capability surface

The tools, connectors and scopes a skill declares — inside its signature.

connector

Org-scoped, OAuth-bound infrastructure resolved on the control plane; never packaged.

connector rail

The path by which hosted models and MCP tools receive credentials at run.

deploy

An artifact's declared destination: runtime, runtime/standalone, registry or store.

digest-only

An artifact with a digest and no sig — memory and model. Integrity without authorship.

layer

A memory body's declaration of seed (curated) or runtime (agent-local scratch).

models rail

The path by which self-hosted weights are resolved, stood up and digest-checked on the target.

reserved value

Any value outside a field's enumerated set. Rejected by conforming readers.

template

What is signed: sections, variable schema and bindings — never the rendered string.

tree-shake

Producer step that ships only assets reachable from the composed agents.

two-facet output

An agent's output.expected (prose, prompt-shaping) and output.schema (typed, validating).

VIO

Verifiable Intelligence Object — the expansion used as the format's tagline. See the note on the extension's origin under Charter.

vio_bundle

The Sign asset type for a whole bundle; its signature is computed over the canonical manifest.

Citation#

@techreport{vio-spec-2026,
  title   = {The .vio Artifact Specification},
  author  = {Roggero, Vivien and Vora, Adi},
  institution = {The VIO Project},
  year    = {2026},
  note    = {VIO 1.0. Format version 1, specification revision 5 (2026-09-22)},
  url     = {https://vioformat.org/spec}
}