Setup registries

A registry source is a fetchable manifest of skills and/or MCP servers that DefenseClaw ingests on demand. Public catalogs (clawhub, smithery), internal HTTPS YAMLs / JSONs, git repos, and on-disk YAMLs are all supported. Synced entries flow through the existing skill / MCP scanners; clean ones land in asset_policy.{skill,mcp}.registry so a later admission decision can say "approved by registry:<id>" instead of "approved by an unattributed rule someone wrote in 2024."

1asset_policy:2  skill:3    registry:4      workspace-helper@1.2.0:5        action: allow6        reason: registry:internal-catalog11asset_policy:2  skill:3    registry:4      workspace-helper@1.2.0:5        action: allow6        reason: registry:internal-catalog1

What you just saw

An on-demand registry sync verified source integrity, routed an entry through its existing scanner, and selected a deterministic outcome: promote a clean entry, hold a warning for review, or deny an unknown asset when registry_required=true. Stored sync settings do not create a runtime poller.

The seven registry kinds

Three worked examples

defenseclaw registry add clawhub \
  --kind clawhub \
  --content skill \
  --non-interactive

defenseclaw registry sync clawhub

defenseclaw registry add corp-skills \
  --kind http_yaml \
  --url https://catalog.corp.example.com/skills.yaml \
  --content skill \
  --auth-env CORP_CATALOG_TOKEN \
  --non-interactive

export CORP_CATALOG_TOKEN="$(vault kv get -field=token kv/defenseclaw/catalog)"
defenseclaw registry test corp-skills              # dry-run: fetch + parse, no writes
defenseclaw registry sync corp-skills              # fetch + scan + promote

defenseclaw registry add smithery-public \
  --kind smithery \
  --content mcp \
  --non-interactive

defenseclaw registry sync smithery-public

All twelve subcommands

The lifecycle of an entry

Promote and require — the deny-by-default story

Once entries are flowing in, asset_policy.<type>.registry_required flips the corresponding asset class to deny-by-default:

defenseclaw registry require --type skill --enabled
defenseclaw registry require --type mcp   --enabled

When registry_required=true:

• An asset whose name matches a rule in asset_policy.<type>.registry follows that rule.
• An asset whose name does not match any rule falls through to the configured registry_empty_action (default deny).
• An empty registry list with require=on blocks every asset of that class by default until the next sync populates it. Setting registry_empty_action: warn or allow relaxes only this empty-registry gate and falls through to the type default; warn is non-blocking. The CLI warns you in colour when you flip require=on against an empty list — read the warning carefully.

The Go gateway tags every admission decision with Reason="registry:<id>" (or "registry:operator-approved" for manually approved entries) so you can grep ~/.defenseclaw/gateway.jsonl to see which catalog won.

What --auth-env, --allow-private, and SHA-256 actually do

Registry fetches use the same hardened URL path in test and sync: loopback, link-local, cloud-metadata, and private-network destinations are refused by default, including DNS resolutions that rebind into a reserved range. Use --allow-private only for a registry mirror you intentionally run on an internal network. Local file registries must use absolute paths, and remote entry downloads must pass the per-entry SHA-256 check before scanner promotion can happen.

Inspect what landed

defenseclaw registry list                              # one row per source, with cached counts
defenseclaw registry show corp-skills                  # full detail + verdict summary
defenseclaw registry entries corp-skills --status warning
defenseclaw registry approve corp-skills my-skill --type skill
defenseclaw registry reject  corp-skills evil-skill --type skill

approve and reject re-promote against the cached manifest immediately by default, so the new rule lands without a network round-trip. Pass --no-repromote if you want to defer the change to the next registry sync.

Sync schedules

Today, syncing is on demand. The --auto-sync and --sync-interval-hours flags on add / edit are persisted but the runtime does not poll. Run registry sync --all from a cron / systemd timer / GitHub Actions schedule until scheduled sync ships in a future release:

# /etc/cron.d/defenseclaw-registry
0 * * * * defenseclaw registry sync --all

Common gotchas

Reference

• cli/defenseclaw/commands/cmd_registry.py — every subcommand, validator, and the lifecycle helpers.
• cli/defenseclaw/registries/ — adapters, manifest schema, sync engine, promotion rules.
• Reference → CLI — full CLI catalog.
• Setup → Skill scanner and MCP scanner — what the scanners look at when verdicts get computed.
• Policies — how asset_policy decisions blend with repo policies and the LLM judge.