OCI Artifacts¶

Overview¶

autonomy attaches two sidecar artifacts to an OCI image:

Artifact	Default sidecar tag	Media type
Lock file (`autonomy.lock.json`)	`<tag>-lock`	`application/vnd.autonomyops.lock.v1+json`
Policy bundle (`.tar.gz`)	`<tag>-policy`	`application/vnd.autonomyops.policy-bundle.v1+tar`

Sidecars are stored as OCI artifacts in the same registry as the subject image. No external storage is required.

Attach workflow¶

1. Push a subject image¶

In production, the subject is a real agent container image. For development and the demo stack, use:

autonomy oci push-test-artifact --image localhost:5000/agent:v1

2. Attach the lock file¶

autonomy oci attach-lock \
  --image localhost:5000/agent:v1 \
  --lock  autonomy.lock.json

attached  mode=sidecar  ref=localhost:5000/agent:v1-lock  digest=sha256:...

3. Attach the policy bundle¶

autonomy oci attach-policy \
  --image  localhost:5000/agent:v1 \
  --bundle bundle.tar.gz

attached  mode=sidecar  ref=localhost:5000/agent:v1-policy  digest=sha256:...

4. Pull back and verify¶

autonomy oci pull-lock   --image localhost:5000/agent:v1 --out pulled.lock.json
autonomy oci pull-policy --image localhost:5000/agent:v1 --out pulled.tar.gz

diff autonomy.lock.json pulled.lock.json   # must be byte-identical

Attach strategies¶

The registry determines which strategy is used. The choice is automatic and cached per registry host in ~/.autonomy/registry_caps.json (1-hour TTL).

Strategy 1: OCI Referrers API (preferred)¶

Used when the registry supports OCI 1.1’s GET /v2/<repo>/referrers/<digest>.

Compatible registries: GitHub Container Registry, Zot, Harbor 2.x, AWS ECR.

The sidecar is stored as an OCI manifest with a "subject" field pointing to the image manifest digest. The sidecar is retrievable by querying the referrers index.

Strategy 2: Sidecar tag (fallback)¶

Used when the registry does not respond with Content-Type: application/vnd.oci.image.index.v1+json to a referrers probe.

Compatible registries: registry:2 (Docker distribution), most self-hosted registries.

The sidecar is pushed as a separate OCI artifact at a derived tag:

localhost:5000/agent:v1-lock     ← lock sidecar
localhost:5000/agent:v1-policy   ← policy bundle sidecar

The attach and pull commands handle both strategies transparently. The mode=sidecar or mode=referrers field in the output shows which was used.

Capability probe¶

Probe a registry to see which strategy will be selected:

autonomy oci probe --image localhost:5000/agent:v1

referrers=false  image=localhost:5000/agent:v1

For registry:2:

referrers=false  image=localhost:5000/agent:v1

For a registry supporting OCI 1.1 referrers:

referrers=true   image=registry.example.com/agent:v1

Force a fresh probe (bypass cache):

autonomy oci probe --image localhost:5000/agent:v1 --invalidate

Probe error handling¶

If the probe request fails (network error, unexpected status), the strategy defaults to sidecar. This is fail-safe: a sidecar-strategy push will always succeed against any OCI-compliant registry, at the cost of creating visible extra tags.

Round-trip integrity¶

pull-lock and pull-policy return the raw artifact bytes. The pulled bytes must be byte-identical to the pushed bytes.

Verify a lock file’s self-consistency after pulling:

autonomy lock fingerprint --in pulled.lock.json --verify

OK  blake3:e6211e169134767016b7e7f60784fe8fcb171b44801068e000d2eb179fdb3fd2

Exit code 0 = fingerprint in the file matches the recomputed value. Exit code 1 = tampered or corrupted.

Supply-chain signing¶

After attaching sidecars, sign the image and both sidecars with cosign:

COSIGN_PASSWORD=<secret> autonomy sign \
  --image  localhost:5000/agent:v1 \
  --key    cosign.key \
  --lock \
  --policy

--lock and --policy sign the corresponding sidecar tags (v1-lock, v1-policy) in addition to the subject image.

Verify the full supply chain:

AUTONOMY_TRUST_TIME=false autonomy verify \
  --image          localhost:5000/agent:v1 \
  --pub            cosign.pub \
  --require-lock \
  --require-policy

Exit code 0 = all four verification steps passed (signatures, OCI digests, fingerprint, semver). See security-model.md for the full verification order.

Plain HTTP registries¶

localhost and 127.0.0.1 targets are automatically treated as plain HTTP. For non-localhost plain HTTP registries, use --allow-insecure-registry:

autonomy sign \
  --image 192.168.1.10:5000/agent:v1 \
  --key   cosign.key \
  --allow-insecure-registry

Media types reference¶

Artifact	Media type
Lock file	`application/vnd.autonomyops.lock.v1+json`
Policy bundle	`application/vnd.autonomyops.policy-bundle.v1+tar`
OCI config (sidecar)	`application/vnd.oci.image.config.v1+json`

The media types are stable across sidecar and referrers strategies. Consumers can identify artifact type without parsing content by checking the media type in the OCI manifest.