Documentation
Shield docsWork with your project

Registry sources and packs

Permission packs contain reusable rules for tools and workflows. Registries supply those packs; installing a pack does not install its target tool.

Start with discovery below. Pack authors and registry maintainers can skip to catalog files or dependencies.

Find and install a pack

From an initialized project, search the main registry and inspect a result:

shield pack search main/

main/ searches the built-in registry without installing anything. Copy a result’s full reference in place of PACK_REFERENCE:

shield pack info PACK_REFERENCE

Read the description and profile decisions, then add the same reference:

shield pack add PACK_REFERENCE --profile recommended
shield pack list

pack add reviews permission changes before confirmation. After acceptance, pack list shows the selection and profile. Omit --profile to choose interactively, with Recommended preselected.

Profile decisions depend on the pack: installing one does not allow every invocation, and Strict does not change Codex’s Ask fallback. See policy decisions.

Change an installed pack

Use shield pack list to find an installed selection. Copy its selector, using the displayed pack:UUID if names are ambiguous, in place of PACK_SELECTOR:

shield pack show PACK_SELECTOR
shield pack configure PACK_SELECTOR

show inspects the retained selection. configure walks through any variable questions and rule overrides, then reviews the change before activation. A variable supplies a value the pack was written to accept; an override turns a particular rule off or changes its decision. See pack variables and rule overrides for flags and local settings.

To choose another profile for that installed selection, use:

shield pack add PACK_SELECTOR --profile strict

This preserves its retained version and pin and reviews the profile change. Profile changes use retained artifacts and can work offline.

To update unpinned selections, run:

shield pack update

Review version and permission changes before confirming. Pins are skipped; resolution or verification failure leaves policy unchanged.

To remove a selection, use:

shield pack remove PACK_SELECTOR

Removal works offline and preserves custom rules. It refuses if a remaining pack requires that selection; removing a root can also remove dependencies no longer needed by another selection. Inspect shield pack list after confirmation. The dependency update and removal reference explains these rules in detail.

Register a source

Use this section when you need a local catalog or a custom HTTPS registry. You can use the pinned main source without replacing it with your own registration.

Choose registries explicitly, then review permission packs before installing them. A project registration overrides the same user alias. A project default takes precedence over the user default. The reserved main alias pins https://canonic2.github.io/shield-registry/ and the release signing key in the binary; it installs no implicit policy. The signed main catalog is published through GitHub Pages. A network-supplied public key cannot replace the pinned root.

shield registry add acme /path/to/local-registry
shield registry add team https://registry.example.com/ --scope user
shield registry list
shield registry list --scope user
shield registry default acme
shield pack search git
shield pack info acme/git
shield pack add acme/git --profile recommended
shield pack list
shield pack show pack:UUID
shield pack update
shield pack remove pack:UUID
shield registry remove acme

Registry mutations ask for terminal confirmation. Removing a registration preserves installed policy and its source identity. Registry aliases select sources for discovery; installed selectors identify retained instances. Use a displayed pack:UUID when names are ambiguous. That selector stays with the installed instance through updates and profile changes. Removing it retires the selector; reinstalling creates a new one.

New unversioned selections choose the highest engine-compatible stable version. Shield tries older stable releases when newer ones use an unsupported engine or policy format. Invalid digests or artifact identities stop acquisition. When you add a new pack without --profile, Shield asks for its profile after resolving the release, with Recommended preselected; Enter keeps it. Dependencies follow the profile you choose. An exact @version pins that release. Adding an installed selector without a version preserves its version and pin; --profile changes its profile without requiring the source to be online. Update skips pinned releases and reviews all applicable changes in one transaction. Removal works offline.

Local catalog

Registry maintainers define catalogs as described below. For project settings, see pack variables and overrides.

Suggestions for commands

Claude and Codex can suggest packs for commands that Ask. A suggestion names the source/publisher/pack and changes no permissions. Inspect its profiles with pack_info; a relevant pack may still Ask or Deny the invocation. Its summary includes bounded examples of declared Allow, Ask and Deny outcomes for each profile, with conditional rules and unmet-requirement outcomes marked. The text preview shows recommended-profile examples. Review the intended profile’s retained approval requirements alongside its allowances before describing installation benefits. Other active rules, conditions and requirements still determine effective permissions; Ask follows the host’s approval or configured fallback. Omitted examples are marked in missing/truncated.

For one candidate, the agent reviews it and offers installation once per conversation after the task, even if the command ran under Codex’s fallback. It explains the scope, proposes the change, and submits policy_apply. The host approval prompt is the installation question. Multiple candidates need selection first. See the MCP walkthrough.

Suggestions use the latest locally retained catalog metadata. Run shield pack search main/ in the project to authenticate and retain the main catalog, or replace main with an enrolled alias. Hooks never refresh catalogs or download packs. Already installed instances and removed sources are excluded.

Catalog v2 adds optional commands, for example "commands":{"acme/runtime":["node","npm","npx"]} alongside its packs. Each ID needs a listed stable release. Lists contain 1–16 unique command basenames (at most 64 ASCII letters/digits/._+-, starting alphanumeric). These hints are authenticated with the catalog, and carry relevance rather than permission. V1 catalogs remain supported and supply no command hints. V1-only clients cannot read v2 catalogs; upgrade clients before publishing v2. Checkpoints with a command index also require the updated client; downgrading is not supported for that state.

Catalog files

A local directory contains catalog.json and declarative pack artifacts:

{"schema_version":1,"packs":[{"id":"acme/git","version":"0.1.0","path":"packs/git.yml","sha256":"<64-character SHA-256>"}]}

Replace the checksum placeholder with the artifact digest. Artifact paths use ASCII letters, digits and -._~/ without empty, . or .. segments. An optional expires_at must be a whole-second UTC timestamp. An optional sequence is retained like a signed catalog’s: once a catalog carries one, later catalogs must keep a sequence that never decreases. Reads are confined to the canonical enrolled directory. Pack identity/version must match the catalog. Artifacts contain policy data, never installers. Same-version replacement bytes are refused for retained selections. Distinct registries may supply the same pack name; their retained identities keep those selections separate.

Custom signed HTTPS catalog

A custom HTTPS directory serves catalog-key.pub (64 hexadecimal characters), catalog.sig (128 hexadecimal characters), catalog.json, and the catalog’s relative artifact paths. The key is Ed25519; the detached signature covers the exact catalog bytes. The catalog adds registry_id, integer sequence and UTC expires_at metadata.

Enrollment verifies ordinary TLS, presents the origin/key for operator review, and retains that key and registry identity. Acquisition verifies signatures, expiry and retained monotonic sequence/digest checkpoints before using releases. Artifacts must match signed digests. Redirects, unsafe paths, unsigned metadata and source identity changes are refused. Offline evaluation uses retained bytes. This custom-source format does not supply the main registry’s release trust root.

Pack dependencies

Packs enable dependencies-v1 and declare dependencies in their exact artifact bytes:

schema_version: 1
kind: pack
id: acme/workflow
version: 1.0.0
description: Acme workflow permissions
license: UNLICENSED
maintainers: [Acme]
engines: {shield: '^0.8'}
capabilities: [structured-rules-v1, dependencies-v1]
dependencies:
  - pack: acme/git
    requirement: '^1.0'
rules: []

Each dependency uses publisher/name and a SemVer requirement. It inherits the parent’s enrolled source unless registry names another explicitly enrolled source identity. Use the identity shown by shield registry list, rather than its alias or the operator’s default. For example:

dependencies:
  - pack: acme/git
    requirement: '^1.0'
    registry: '<captured enrolled source identity>'

Enroll cross-source registries before acquisition. A pack cannot register a source or choose its URL or signing key. Identical pack names from different sources stay distinct; use pack:UUID when names are ambiguous.

Dependencies inherit the parent’s profile unless a complete profiles mapping selects one for each parent profile. The mapping must become at least as restrictive from Loose to Strict. Shared dependencies use the strongest required profile. A directly selected dependency keeps its explicit profile and reports a conflict if that profile is too weak. Omit both dependencies and dependencies-v1 when unused; optional fields cannot be null.

Resolution and review

Add and MCP pack-add proposals verify the full dependency set before review. A new unversioned selection chooses the highest compatible stable set; existing roots keep their versions, and exact requested versions stay pinned. Cycles, conflicts, missing releases, bad digests, or changed source identity leave active policy unchanged.

The review lists selections, dependency/profile changes, and incoming constraints. Confirmation activates the complete candidate together. shield pack list and .shield/shield.lock retain direct-selection flags, versions, profiles, source identities, digests, and dependency edges. Manual review rejects incomplete or incompatible sets. Promoting a dependency to a direct selection requires a profile satisfying all its parents.

Source verification

Dependencies can span enrolled local and signed HTTPS registries. Resolution uses one checked catalog snapshot per source and verifies every artifact digest. HTTPS acquisition uses the saved origin, identity, and signing key; it never fetches a replacement key. Signature, expiry, rollback, path, size, and timeout checks apply throughout. Redirects, unknown identities, alias substitution, and changed source bindings are refused.

Captured proposals can be confirmed offline. Profile changes and removal also use saved artifacts after registry removal. Dependencies accept no settings. Resolution is limited to 64 packs and bounded catalog, byte, and search budgets. Pack review runs no installers or pack code.

Pack variables and rule overrides

Some packs declare variables, such as the package manager or cloud profile the project uses. shield pack add asks one question per variable after resolving the pack, in the order the pack declares them, preselecting a value when a suggested file such as pnpm-lock.yaml exists. An optional variable lists leaving it unset as its first answer, which turns its checks off; a text value is typed into the question’s last row. A pack can word each question and skip it depending on an earlier answer. With more than one question, the answers are shown together before saving, and choosing one asks it again. Bind values directly with shield pack add acme/node --set package_manager=pnpm. A list value is a JSON array or comma-separated items; booleans are true or false.

shield pack configure acme/node reopens the questions for an installed selection, then lists the pack’s rules with what each one decides, with overridden rules already marked. Press Space to mark the rules to change and Enter to continue; each marked rule then asks whether to turn it off or give it another decision, and unmarking a rule returns it to the pack’s decision. Enter with nothing marked keeps every rule as the pack decides, and long lists can be searched. Its flags change values and overrides without questions:

shield pack configure acme/node --set package_manager=pnpm --unset registry
shield pack configure acme/node --override npm-publish=deny --override lockfile-check=off
shield pack configure acme/node --override scripts-require-ci=on_unmet:ask --clear-override npm-publish

Add --local to keep a change on your machine only: shield pack add --local adds a pack just for you, and shield pack configure acme/aws --set profile=acme-read-only --local sets a personal value. After the guided questions, one question chooses where the answers are saved: as the pack suggests for each value, all shared with the project, or all only yours. pack configure --local saves them locally without asking, and a pack added with --local keeps everything local. Local settings live in .shield/config.local.yml (with rules.local.yml and shield.local.lock), which Shield adds to .shield/.gitignore. A local entry can also turn off a shared pack for you with disabled: true; edit the file and review it with shield policy review. Agents cannot edit these files.

An override turns a pack rule or precondition off or replaces its decision; it cannot add rules or change conditions. Values and overrides are stored with the selection in .shield/config.yml. Every change goes through the ordinary review, which lists changed values and overrides and marks overrides that widen permissions. Updates keep values and overrides; review lists any that the new release no longer declares, and they are removed. Shield asks again when an update adds a required variable or no longer accepts the bound value. Agents can propose the same changes with the MCP pack_configure change.

Updating and removing dependency packs

shield pack update resolves one complete compatible closure for all tracking roots; direct selections from the built-in main registry use its pinned source and need no additional registry enrollment. Tracking direct selections update to their installed version or a newer release. shield pack update pack:<uuid> updates that instance and its reachable dependencies. Direct profiles and pinned versions stay fixed. Updating a pinned instance is a no-op. Dependencies reachable only from skipped pinned roots retain their versions; shared dependencies reached by tracking roots can update within every parent’s constraints. An unpinned dependency can also be updated explicitly, subject to all parent constraints. Source enrollment is checked by captured identity, so renaming an alias cannot retarget an installed instance.

Review shows each pack added, removed, updated or given another profile, and how command decisions change; shield pack list shows the resulting versions, profiles and dependency edges. Confirmation activates the whole candidate together. Failed verification, incompatible closures, canceled review and stale proposals preserve active policy. MCP pack_update proposals capture the same verified closure for operator review; confirmation can use those captured bytes after the source becomes unavailable.

shield pack remove pack:<uuid> works offline using retained artifacts. If another remaining pack requires the instance, removal refuses and names its dependents. Removing a root prunes only dependencies no longer reachable from remaining roots. Shared dependencies and explicitly selected packs remain. MCP pack_remove proposals use the same preparation and confirmation boundaries. Custom rules are preserved across both workflows.