Skip to content

ADR: OCI Format

Status: Proposed Date: 2026-04-29 Authors: Daniele Martinoli Reviewers: []

Context

Lola distributes modules (skills, commands, agents) via Git, Zip/Tar, local folders, and marketplace YAML catalogs. That model works for many teams but lacks enterprise supply-chain controls: cryptographic verification, SLSA-style provenance, digest-pinned immutable versions, and registry-native RBAC for regulated or air-gapped environments.

The Open Container Initiative (OCI) artifact format addresses those gaps. OCI is one supported format among many—not a replacement for Git/Zip/Tar. Users may build artifacts with Lola, skillimage, or existing CI/CD; Lola consumes OCI references such as oci://registry.io/org/module:version the same way it consumes Git URLs.

Industry alignment: Red Hat skillimage (library-first OCI skill distribution) and CNCF TOC Issue #1740 (OCI artifact standardization for AI). Marketplace discovery stays source-agnostic: repository may point at OCI, Git, or archive URLs without schema changes.

Implementation depends on the Go Migration ADR (single binary, skillimage and sigstore-go integration).

Decision

We will add OCI artifact distribution for Lola modules alongside existing sources.

  1. OCI as an optional format
  2. Support oci:// module references; no migration for current modules.
  3. Marketplace catalogs remain format-neutral.

  4. Modules still bundle skills/, commands/, and agents/.

  5. Go implementation via skillimage

  6. Use skillimage for pull, push, verify, and single-layer packaging.
  7. Lola defines semantics in the io.lola.module.* annotation namespace (skillimage handles OCI mechanics; Lola models multi-component modules).

  8. Packaging follows skillimage’s single content layer pattern; details in OCI CLI Exploration.

  9. Verify before materialize

  10. Signature and provenance verification enabled by default for OCI modules.
  11. --skip-verification disables both (development only, with warnings).
  12. Illustrative consumption flow:
import "github.com/redhat-et/skillimage/pkg/oci"

artifact, err := oci.Pull(ctx, "registry.io/lola/module:1.0.0")
err = artifact.Verify(ctx, oci.WithCosign(), oci.WithSLSA())
err = artifact.ExtractTo("/path/to/.lola/modules/") // after verification succeeds

CLI command proposals (lola build, lola push, lola sign, lola verify, phasing, metadata schema) live in OCI CLI Exploration.

  1. Deployment modes (installation adapts by target; see CLI exploration for lola install --mode)
  2. Local (default) — Pull OCI artifact, verify, unpack to ~/.lola/modules/ and generate assistant-native files (Claude Code, Cursor, Gemini CLI, etc.). Git/Zip/Tar use the same path.
  3. Container — Mount the OCI image as a read-only volume for containerized agents (e.g. OpenCode); no unpack. Requires a container runtime; OCI-only.
  4. Cloud — Verify and install into cluster workloads (e.g. OpenShift/Kubernetes Jobs or operator-driven flows); primarily for signed OCI modules in regulated environments.

Rationale

  • Format neutrality — Teams keep Git/Zip/Tar workflows; OCI is for registry-backed, verifiable distribution.
  • Reuse infrastructure — Container registries, Cosign/Sigstore, oc-mirror, and Kubernetes ImageVolumes (1.33+) instead of bespoke packaging.
  • skillimage — Avoid reimplementing OCI; align with Red Hat/CNCF direction for agent skills.
  • Separate metadata namespace — Lola modules are not single-skill SkillCards; io.lola.module.* can evolve independently.

Consequences

Positive Consequences

  • Cosign/Sigstore verification and optional SLSA provenance for audit requirements
  • Digest-pinned, immutable artifact versions
  • Registry RBAC and standard pull tooling (podman, skopeo, etc.)
  • Air-gap mirroring with signatures; read-only mounts for containerized agents
  • No change required for existing Git/Zip/Tar users

Negative Consequences

  • Backwards compatibility — Must preserve non-OCI flows; mitigated by automatic format detection.
  • skillimage dependency — External library; mitigated by open source and forkability.
  • Format choice — Users may be unsure when to use OCI; mitigated by docs in CLI exploration and defaults.
  • Go rewrite scope — OCI ships with Go migration; see go-migration.md.

Alternatives Considered

Alternative 1: Git/Zip/Tar only

  • Pros: No new format or registry operations.
  • Cons: No digest pinning, limited provenance, weak enterprise registry story.
  • Rejected: Does not meet supply-chain requirements for target deployments.

Alternative 2: Other AI packaging formats

  • Examples: Docker model-CLI (proprietary), KitOps, ONNX-only bundles, centralized hubs.
  • Cons: Poor fit for multi-component Lola modules or self-hosted registries.
  • Rejected: OCI reuses mature registry and signing tooling.

Implementation Notes

Phases (detail and estimates in OCI CLI Exploration):

Phase Focus
0 Go rewrite; port Git/Zip/Tar/marketplace; skillimage integration
1 lola mod add oci://…, verify-by-default, local unpack install
2 Optional lola build / lola push / lola sign
3 Container volume mount and cloud deployment modes

Out of scope: Mandatory OCI-only distribution; requiring Lola to build artifacts; coupling to a specific governance platform (Compass, MLflow, etc.).

References