oap pin

Manage dependency pinning for MCPServers, SidecarToolboxes, Skills, and SpiceboxToolkits.

Pinning records the immutable identity (manifest hash, image digest, git SHA) of each dependency an agent uses, detects drift, and gates tool calls based on the effective pinning policy.

Subcommands: status — list all pinned dependencies with strength, digest, drift, and age diff — compare the recorded baseline against the live identity update — set the pin-refreeze annotation to accept a new baseline

oap pin diff <kind> <name>

Compare the recorded pin baseline against the live dependency identity.

Supported kinds: mcp — probe tools/list unauthenticated and compare hashes + tool names image — print the PinDrift condition (live signal from the toolbox reconciler) skill — print declared identity; diff is N/A (identity declared in spec) cli — print declared identity; diff is N/A (identity declared in spec)

oap pin status

List all pinned dependencies with strength, digest, drift, and age

Flags:

--kind string  Filter rows to one kind (skill, mcp, image, cli); skill covers both Skill and ClusterSkill rows

oap pin update <kind> <name>

Set the agentprimitives.authzed.com/pin-refreeze annotation on a dependency, requesting that the reconciler accept the given identity as the new pin baseline.

The reconciler accepts the refreeze only when the live identity equals the annotated value (race-free accept: you re-freeze exactly what you reviewed). Once honored, the annotation is cleared and PinDrift is set to PinMatch.

Supported kinds: mcp — probe tools/list unauthenticated to derive the live hash, or pass --to image — --to <sha256:digest> required (CLI cannot pull images), or --current

Rejected kinds (identity is declared in spec, not set via annotation): skill — edit spec.source.resolvedSHA or the SkillSource instead cli — edit spec.pinnedBinaryHash or versionRange instead

Flags: --to <sha256:…> explicit target identity (required for image without --current) --current accept the observed drift digest recorded by the reconciler --all accept all drifted resources in the namespace (no positional args) --kind mcp|image with --all, restrict to one resource kind

Flags:

--all          Accept all drifted resources in the namespace
--current      Accept the reconciler-recorded observed drift digest (status.pin.details.observedDriftDigest)
--kind string  With --all: restrict to one kind (mcp or image)
--to string    Target identity (sha256:… hash or image digest); required for image without --current, optional for mcp