Reference

RigBundle

Published April 2026

File: .rigbundle · Manifest: bundle.yaml · Schema: v2 (pod-aware)

The canonical OpenRig archive format for shipping a topology as a single file. A .rigbundle packages a RigSpec, all referenced AgentSpecs, their resources, optional docs and culture files, plus integrity metadata.

This page mirrors the shipped reference and bootstrap behavior in the `openrig` repo, including the current install semantics for `rig bundle install` and `rig up <bundle>`.

Archive layout

A `.rigbundle` is a deterministic gzip-compressed tar archive. Inside the archive, all refs are rewritten to safe bundle-relative paths and every vendored file can be checked against the manifest.

my-team.rigbundletar.gz archive

bundle.yamlmanifest - vendored agents, refs, integrity

rig.yamlrewritten RigSpec with bundle-relative local: refs

CULTURE.mdoptional rig-wide culture file

SETUP.mdoptional docs file declared by the rig

agents

pm-lead

agent.yamlvendored AgentSpec

skills

openrig-user

SKILL.md

guidance

role.md

startup

context.md

researcher

agent.yamlvendored AgentSpec

guidance

research-standards.md

startup

briefing.md

rig.yaml

Rewritten RigSpec with vendored `agent_ref` paths and any rig-level startup/docs references.

agents/

Vendored AgentSpecs plus their referenced resources: skills, guidance, startup files, hooks, and runtime resources.

bundle.yaml

Manifest with schema version, vendored agent entries, original refs, and per-file integrity data.

.rigbundle.sha256

Sibling archive digest for transfer-corruption detection. This file sits next to the archive, not inside it.

Manifest shape

schema_version: 2
name: my-bundle
version: "0.1.0"
created_at: "2026-04-11T22:32:48.570Z"
rig_spec: rig.yaml
agents:
  - name: pm-lead
    version: "1.0"
    path: agents/pm-lead
    original_ref: "local:agents/pm-lead"
    hash: "ed4cff20..."
    import_entries: []
  - name: researcher
    version: "1.0"
    path: agents/researcher
    original_ref: "local:agents/researcher"
    hash: "11f8a077..."
    import_entries:
      - name: shared
        version: "1.0"
        path: agents/shared
        original_ref: "local:../../shared"
        hash: "abc123..."
culture_file: CULTURE.md
integrity:
  algorithm: sha256
  files:
    rig.yaml: "b80c0674..."
    CULTURE.md: "9354361b..."
    agents/pm-lead/agent.yaml: "ed4cff20..."

Version 2 is the current pod-aware manifest shape. Legacy version 1 bundles still load for compatibility, but new bundles should use `schema_version: 2`.

What the integrity model does and does not do

Sibling digest

The `.rigbundle.sha256` file detects corruption during transfer.

Per-file integrity

The manifest hashes detect tampering or mismatch inside the extracted archive.

Not author signing

These checks prove self-consistency, not authenticity. You still have to trust the source you got the bundle from.

CLI surface

Create

rig bundle create rig.yaml \
  -o my-team.rigbundle \
  --rig-root . \
  --name my-team \
  --bundle-version 1.0.0

Create validates the rig, vendors the referenced agents and imports, rewrites refs to bundle-relative `local:` paths, writes `bundle.yaml`, then emits the archive and sibling digest.

Inspect

rig bundle inspect my-team.rigbundle

# optional
rig bundle inspect my-team.rigbundle --json

Inspect extracts to a temporary directory for safe validation, reports digest validity and integrity results, then cleans the temp directory up. It does not install.

Install

rig bundle install my-team.rigbundle --target ~/projects/my-project

# plan-only
rig bundle install my-team.rigbundle --plan

`rig bundle install` requires `--target` in apply mode. The only exception is plan mode, where the daemon can validate and preview without an install root.

Launch directly

cd ~/projects/my-project
rig up /path/to/my-team.rigbundle

# explicit target
rig up /path/to/my-team.rigbundle --target ~/projects/my-project

# separate runtime cwd override
rig up /path/to/my-team.rigbundle --target ~/projects/my-project --cwd ~/src/app

For `.rigbundle` sources, `rig up` defaults the install target to the current working directory if `--target` is omitted. `--cwd` is separate: it changes the launched members' working directory for that run, not where packaged files are installed.

Safety and validation highlights

Unpack safety

No symlinks or hardlinks in the archive.

No absolute paths.

No `..` traversal segments.

Archive digest must match the sibling `.sha256` file.

Per-file hashes must match the manifest integrity section after extraction.

Validation rules

`schema_version` must be `2` for new pod-aware bundles.

`rig_spec` and vendored agent `path` values must be safe relative paths.

Each vendored agent entry must have `name`, `path`, and `hash`.

Integrity `algorithm` must be `sha256`.

Declared rig docs are strict: missing docs fail bundle assembly.

Culture and startup files are collected best-effort: missing files are skipped, not fatal.

`builtin:terminal` members are not vendored into the bundle.

Assembly behavior

Bundle assembly walks the rig from the top down: it validates the RigSpec, collects rig-level files, vendors each member's referenced AgentSpec, resolves and vendors imports, rewrites refs to bundle-relative `local:` paths, computes file hashes, and finally packs the result deterministically.

If multiple members resolve to the same agent spec directory, that agent is vendored once and reused. Terminal members using `agent_ref: "builtin:terminal"` are the special case: they stay bundle-native and are not vendored.

Legacy note

Version 1 bundles used the older flat-node shape and a `packages` array in the manifest. They remain supported for backward compatibility, but the website and current OpenRig reference treat pod-aware version 2 as the canonical format.