OCI Distribution & Role Bundles

InitRunner supports publishing and installing role bundles via any OCI-compliant container registry (Docker Hub, GHCR, ECR, etc.). This gives you a distribution story comparable to Docker images, with bundled skills, schemas, and data files.

Quick Start

# Log in to a registry
initrunner login ghcr.io

# Publish a role
initrunner publish role.yaml oci://ghcr.io/org/my-agent --tag 1.0.0

# Install from a registry
initrunner install oci://ghcr.io/org/my-agent:1.0.0

# Pull (alias for install with OCI)
initrunner pull ghcr.io/org/my-agent:latest

# Inspect without installing
initrunner info oci://ghcr.io/org/my-agent:1.0.0

Bundle Format

A role bundle is a .tar.gz archive containing:

manifest.json          # bundle metadata
role.yaml              # the role definition
skills/                # referenced SKILL.md files (if any)
  web-researcher/
    SKILL.md
data/                  # schemas, samples, etc. (if any)
  schema.json

What Gets Bundled

File selection is deterministic and explicit -- no implicit directory scanning:

The role file (role.yaml) -- always included
Resolved skills -- each skills entry resolved to its SKILL.md file
Schema-referenced data files:
- output.schema_file (if set)
- ingest.sources glob patterns
- security.sandbox.bind_mounts[].source
Explicit bundle.include -- a top-level field for extra files:

name: my-agent
bundle:
  include:
    - data/examples/*.csv
    - prompts/

Declared Sandbox Backends

Since v2026.4.16, the bundle manifest carries a supported_sandbox_backends field that records which runtime sandbox backends the role expects. It is written into manifest.json inside the archive, alongside the file list.

You do not write this field yourself, and it is not a role YAML key. initrunner publish derives it from the role's security.sandbox.backend:

name: my-agent
prompt: Review the diff and report risky changes.
security:
  sandbox:
    backend: docker   # "bwrap", "docker", "ssh", "auto", or "none"

`security.sandbox.backend`	Recorded in the manifest
`none` (the default)	`[]`
`auto`	`["bwrap", "docker"]`
`bwrap`, `docker`, or `ssh`	that one backend

The manifest only ever holds bwrap, docker, or ssh; auto and none are resolved at publish time. Roles that run without a sandbox declare nothing. Pick docker when the role relies on a pinned image or bridge networking.

OCI Reference Format

OCI references use the oci:// prefix to distinguish them from other source types:

Pattern	Type	Example
`oci://registry/repo:tag`	OCI	`oci://ghcr.io/org/my-agent:1.0`
`hub:owner/name`	InitHub	`hub:alice/code-reviewer@1.0`
`bare-name`	Community index	`pr-reviewer`

The oci:// prefix is required and unambiguous.

Authentication

Credentials are resolved in this order:

Environment variables: INITRUNNER_OCI_USERNAME + INITRUNNER_OCI_PASSWORD
InitRunner auth file: ~/.initrunner/oci-auth.json (created by initrunner login)
Docker config: ~/.docker/config.json (base64 auth field only)

initrunner login ghcr.io
# Username: myuser
# Password: ********
# Login succeeded for ghcr.io

Credentials are stored in ~/.initrunner/oci-auth.json with file mode 0600.

Docker Credential Helpers

Docker credential helpers (credsStore, credHelpers) are not supported. If your Docker config uses credential helpers, use initrunner login or environment variables instead. A warning is emitted when credential helpers are detected.

Install Identity

Installed roles are tracked with qualified IDs to prevent name collisions:

InitHub: hub:owner/role-name
OCI: oci:registry/repository/role-name

You can uninstall and manage roles using either the display name or qualified ID:

initrunner uninstall my-agent                              # by display name
initrunner uninstall "oci:ghcr.io/org/my-agent/my-agent"   # by qualified ID

The initrunner list command shows the source type for each installed role.

Updating OCI Roles

initrunner update my-agent    # checks registry for new digest
initrunner update --all       # update all installed roles

For OCI sources, update performs a HEAD request to check if the manifest digest has changed, then re-pulls if needed.

Commands Reference

Command	Description
`initrunner publish <role.yaml> <oci-ref> [--tag TAG]`	Bundle and push a role to an OCI registry
`initrunner pull <oci-ref> [--force] [--yes]`	Pull and install a role from an OCI registry
`initrunner install oci://... [--force] [--yes]`	Install from OCI (same as pull)
`initrunner login <registry>`	Store credentials for a registry
`initrunner info oci://...`	Inspect bundle metadata without installing
`initrunner list`	List installed roles with source type
`initrunner update <name>`	Update an installed role

File Layout

OCI bundles are extracted to ~/.initrunner/roles/oci__<registry>__<repo>__<name>/:

~/.initrunner/roles/
  oci__ghcr.io__org__my-agent/     # OCI bundle (directory)
    manifest.json
    role.yaml
    skills/
    data/
  hub__alice__code-reviewer.yaml   # InitHub install (single file)

Security

All archive paths are validated to prevent path traversal attacks
SHA-256 integrity checks are performed on every file during extraction
Credentials are stored with restrictive file permissions (0600)
Bundle contents are deterministic -- only explicitly referenced files are included

On this page