Overview

What is stax?

stax is a distribution standard for AI agents. It defines how to describe, bundle, version, validate, verify, and distribute agent artifacts as OCI artifacts.

stax artifacts are the agent equivalent of docker build, docker push, and docker pull: authors build and publish immutable agent artifacts, and consumers pull, inspect, verify, materialize, install, or import them into the environments where agents run.

stax does not run agents, orchestrate them, or manage their lifecycle. Those concerns belong to runtimes, orchestrators, IDEs, CLIs, hosted agent platforms, and cloud systems built on top of the format.

stax is to agents what the OCI Image Spec is to containers, what package.json is to JavaScript packages, and what Chart.yaml is to Helm charts.

In the current market, stax is best understood first as a standard for coding-agent asset distribution. The broader vision still applies, but the most mature current fit is for instructions, instruction trees, subagents, skills, MCP config, package reuse, policy, and promotion across developer-facing agent runtimes.

Specification status

Normative language

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY in this specification are to be interpreted as described in RFC 2119 / RFC 8174.

Key Spec Sections

Scope

What stax defines

• Authoring formats for agents, packages, personas, prompt surfaces, MCP, rules, skills, knowledge, memory, and secrets
• A compiled config blob stored in OCI
• Distribution semantics for versioning, addressing, inspection, pull/push workflows, and reproducible builds
• Canonical subagent bundles for named delegate agents and agent-role packaging
• Path-scoped instruction trees for runtimes that discover instructions hierarchically
• Runtime profile artifacts for portable non-secret runtime configuration when appropriate
• Source artifacts for cacheable workspace snapshots shared across many agents
• Typed OCI layers for each brain concern
• Deterministic build rules for packaged directories and compiled JSON
• Package dependency and merge rules
• Adapter metadata describing how a consumer materializes an artifact for a runtime
• A consumer/materialization contract for turning canonical layers into runtime-native files, API payloads, bundles, or remote objects
• A baseline compatibility and install-plan contract for preflight checks before files or remote objects are changed
• A CLI contract for build, validate, inspect, plan, materialize, push, pull, and verify workflows
• Referrer conventions for signatures, evaluations, approvals, and memory snapshots

What stax does NOT define

These remain out of scope and are owned by consumers of stax artifacts.

Boundary principle

A stax artifact carries what an agent is and what it needs to start. Everything about where it runs, how long it runs, with what limits, under what policies, and in what topology is extrinsic and belongs to the consumer.

This is the same separation used by successful packaging standards:

• OCI images describe the image, not the deployment topology
• npm packages describe dependencies, not process supervision
• Helm charts describe desired resources, not cluster implementation details

Core concepts

Compatibility model

Spec compatibility

• A consumer that implements stax 1.x MUST reject artifacts with a higher unsupported major specVersion.
• A consumer SHOULD ignore unknown additive fields within the same supported major version unless a layer spec says the field is strict.
• Removing or changing the meaning of an existing field is a breaking change and requires a new major spec version.
• Adding optional fields is non-breaking.

Forward compatibility

• A consumer encountering an unknown OCI layer media type within a stax artifact MUST skip the layer and SHOULD warn. Unknown layers MUST NOT cause a build or materialization failure.
• A consumer encountering unknown fields in a config blob or JSON layer MUST ignore them and SHOULD warn, unless the field is in a namespace the consumer explicitly manages.
• Builders SHOULD NOT strip unknown fields from JSON layers or config blobs when re-packaging or copying artifacts.

Deprecation process

To deprecate a field or feature in a future minor version:

1. The spec MUST document the field as deprecated with a target removal version
2. Builders SHOULD warn when deprecated fields are used
3. Deprecated fields MUST NOT be removed until a new major spec version
4. Consumers MUST continue to accept deprecated fields for the entire major version

Adapter compatibility

Adapters MUST declare:

• type — adapter identifier (for example claude-code)
• runtime — target runtime family (for example claude-code)
• adapterVersion — adapter schema version
• features — supported translation features

Consumers SHOULD warn when an artifact uses features unsupported by the selected adapter or runtime.

Consumers SHOULD also expose a machine-readable compatibility and install-impact summary before applying changes when the selected operation would write files or mutate a remote consumer.

Determinism principle

stax artifacts are intended to be reproducible.

Two conforming builders given the same source tree, ignore rules, dependency lockfile, and build options SHOULD produce identical OCI layer digests.

Deterministic packaging rules are defined in 03 — Layers.

Architecture

┌──────────────────────────────────────────────────┐
│                     stax                         │
│              (distribution standard)             │
│                                                  │
│  TypeScript SDK → OCI Artifact → Registry        │
│                                                  │
│  defineAgent()     Typed layers    Push/Pull     │
│  definePackage()   Config blob     Inspect       │
│  definePersona()   Lockfile        Materialize   │
└──────────────────┬───────────────────────────────┘
                   │
                   │ OCI artifacts consumed by:
                   │
     ┌─────────────┼─────────────┬─────────────────┐
     ▼             ▼             ▼                 ▼
  Your           Agent         Cloud           Community
  Orchestrator   Platforms     Providers       Tools

Conformance levels

Specification Documents

Core Specs

Layer Specs

Runtime and CLI

Adapter Specs

Extended Specs

Forward-Looking Drafts