aggrega registry
Manage registries and their signature trust policy
Synopsis
aggrega registryDescription
Manage the OCI registries Aggrega publishes to and resolves from, together withthe signature trust policy for each.
A registry entry records where to reach the registry and what to require of thesignatures on artifacts it serves — which identities are trusted, and whether asignature is required at all. That policy is what "aggrega pull" enforces whenit verifies an artifact and what "aggrega push" honours when it decides whetherto sign.
"aggrega registry add" can fetch a registry's own advertised trust policy ratherthan having you write it out. "aggrega registry update" builds the localsearchable index that "aggrega search" and "aggrega plugin add" read.
A registry entry is written to the global config shared across every workspaceon this machine, because a registry and the identities you trust on it areusually the same wherever you work. That makes adding or removing one amachine-wide change: every project on this machine resolves through the entryyou just wrote or dropped. Pass --workspace to write it to this project's configfile instead. Building the searchable index is the exception — that lands inthis workspace's own artifact cache and reaches no other project.Subcommands
| Command | Description |
|---|---|
aggrega registry add | Register a registry and its signature trust policy |
aggrega registry list | List configured registries and their trust posture |
aggrega registry remove | Remove a registry and its trust policy from a config file |
aggrega registry update | Build the local searchable index of configured registries |
aggrega registry add description
Register a registry host and its signature trust policy.
The entry is keyed under the host exactly as written, and every lookup of it ismade in one spelling: a lowercase host name containing a dot, localhost, a singlename followed by a port (registry:5000), an IPv4 address, or an IPv6 address inbrackets, each with an optional :port. A reference may be given instead — itsscheme, path and credentials are dropped and the entry is keyed under the host itnames — but a host written in capitals, with the default HTTPS port, or as asingle name with no port is refused, naming the spelling to write where there isone.
The entry is written to the global config shared across every workspace, since aregistry and the identities you trust on it are usually the same wherever youwork. Pass --workspace to write it to this project's config file instead; the twoflags are mutually exclusive.
By default the registry's advertised trust policy is fetched once from theregistry's own origin (https://<host>/.well-known/aggrega-trust) and pinnedlocally — trust-on-first-use. Verification at pull time always runs against thepinned local policy, never a live re-fetch. Pass --fetch-trust=false to skip thefetch and pin only what the flags supply.
A trust policy can also be set by hand: keyless (one or more --identity entries,each an "identity=issuer" pair) or keyed (--key pointing at a pinned public-keyPEM). Manual --identity / --key flags OVERRIDE the fetched set — when either issupplied, the fetch is skipped and the policy is built from the flags alone.Pass --trusted-root to pin a Sigstore trust-root bundle for air-gapped keylessverification. Adding the official hub host with no policy flags pins the built-inofficial baseline.
When the registry advertises no trust policy (a 404 or an unreachable endpoint),the add does not fail: it writes the policy from the flags (or an empty policy)and prints a notice suggesting manual --identity / --key pinning. The officialhub writes its built-in baseline instead, and the notice says the baseline waspinned.
When the workspace is offline the advertised policy cannot be fetched, so theregistry is never asked. Adding a registry other than the official hub is thenrefused unless --identity or --key supplies the policy, rather than writing anentry that trusts nothing: register it once while online, or pin it by hand.Adding the official hub offline pins its built-in baseline, with a notice sayingso, and a manual policy registers offline exactly as it does online.
Existing settings in the target config file are preserved.aggrega registry add flags
| Flag | Default | Description |
|---|---|---|
--advisory | false | Downgrade verification failures for this registry to warnings instead of halting |
--fetch-trust | true | Fetch and pin the registry’s advertised trust policy on first use. Use —fetch-trust=false to skip; manual —identity/—key also skip the fetch. |
--global | false | Write the entry to the global config shared across every workspace. A registry defaults here. |
--identity | [] | Trusted keyless identity as identity=issuer, for example dev@example.com=https://accounts.google.com (repeatable; OR-set). Overrides the fetched trust policy. |
--key | — | Path to a pinned cosign-compatible public-key PEM for keyed verification. Overrides the fetched trust policy. |
--name | — | Optional friendly alias for this registry. The host stays the identity; the alias resolves to it wherever a registry is named (e.g. —registry). Must be unique across registries. |
--require-signatures | false | Require a signature on every artifact pulled from (and pushed to) this registry |
--trusted-root | — | Path to a pinned Sigstore trust-root bundle for air-gapped keyless verification |
--workspace | false | Write the entry to this project’s workspace config instead of the global config. |
aggrega registry list description
List every registry configured in the effective merged config, one per line,with its friendly alias (if any), a short trust-posture summary, and a marker onthe default registry.
This reads the resolved configuration and never contacts a registry. Registriesare listed in ascending host order.
With -o json the same set is emitted as one structured document per registry:its host, its alias, whether it is the default, its trust posture as discretefields rather than the table's rendered sentence, and whether a credential forthat host is present in the shared credential store. The credential state reportspresence only — a credential is never read out, measured, or shown in any form,and whether the registry would accept it is not asked, since that would take anetwork round trip. Reading it consults the local credential store, which honorsa configured credential helper. The order is the same ascending host order thetable uses.aggrega registry list flags
| Flag | Default | Description |
|---|---|---|
--output, -o | table | Output format: table|json. |
aggrega registry remove description
Remove a registry's trust-policy entry from a config file, addressed by its hostor its friendly alias.
By default the entry is removed from the global config shared across everyworkspace; pass --workspace to remove it from this project's workspace configinstead. Setting both --global and --workspace is a usage error.
The default_registry pointer is left untouched — removing a registry's trustpolicy reverts that host to default trust; it does not change which registry isthe default. Where default_registry names the removed entry by its alias, thatalias names nothing afterwards, and the configuration is refused untildefault_registry is written as a host or as another entry's name.aggrega registry remove flags
| Flag | Default | Description |
|---|---|---|
--global | false | Remove the entry from the global config shared across every workspace. |
--workspace | false | Remove the entry from this project’s workspace config instead of the global config. |
aggrega registry update description
Walk each configured registry's repositories, read the latest published versionof each, and write a deterministic local searchable index to the artifact cache.
With no argument, every configured registry is indexed. With a single registryargument (a host or a friendly alias), only that registry is indexed.
This is the one registry command that reaches the network. The index it writeslands in this workspace's own artifact cache, so refreshing it changes nothinganother project on this machine resolves through. Credentials are read from asupplied or ambient source and never asked for: a registry that needs one you donot have fails with a message naming what it wanted.
For each repository the highest strict-SemVer version is selected (pre-releaseversions are skipped) and its catalog facets — kind, description, category,labels, and, for plugins, socket type and capabilities — are recorded from thepublished manifest. A repository with no conforming version is skipped; arepository that cannot be read is skipped with a note, so one unreadablerepository does not abandon the whole index.
A registry that asks the walk to slow down — a 429 answer, or a 503 that sayshow long to wait (Retry-After) — is left alone for as long as it asks, or tenseconds where it does not say, and the walk reads fewer of its repositories atonce until it answers again, then returns to its usual pace; on a terminal thewait is shown beside that registry's row. A registry that answers nothing but"slow down" for five minutes is not indexed: it keeps the index it had beforethe run, and the command names it, its last answer and how long it waited.
A read the registry fails or drops in passing — a 5xx answer, a connectionreset or timed out, an answer cut short — is asked again a few times, with agrowing wait between attempts. A repository with a read stillfailing after that is not recorded from this run: it keeps the record the indexalready holds for it, where that record was judged under the trust policy now inforce, and is otherwise left out of the index; either way it is named as arepository that could not be read, as the walk goes and again in the closingsummary under its registry's row, with the kind of the read's last failure — thestatus the registry answered, a timeout, a reset, an answer cut short — and theread that failed. So a version is never recorded unsigned,undated or without its deprecation marker because a read failed, with or without--upgrade. Each registry's row in the closing summary also says how many readswere asked again, whether or not they then succeeded — a read sent again afterthe registry asked the walk to slow down among them — and says zero when nonewas.
Every signature a registry's walk verifies against the public Sigstore trust rootis verified against the same copy of that root, fetched once for the walk ratherthan once per signature; a registry whose trust policy pins a trust root of itsown is verified against that file.
A registry whose repository listing repeats itself — naming a repository it hasalready named, or answering two pages in a row with no repository while stillpointing to a next page — is not followed round again. That registry is reportedas not indexed, with a message naming it and saying its repository listingrepeated itself; the other registries are still indexed, and the command exitsnon-zero.
A registry that is not indexed keeps the index it had before the run, unchanged:nothing is written for a registry whose walk failed, whose listing repeateditself, or that was being walked when the command was interrupted. Registriesindexed earlier in the same run keep what this run wrote for them. A registry'snew index is written aside and put in place whole, so a command stopped whilewriting one leaves that registry with a complete index — the one it had beforethe run, or the new one — or with none, never with a partial one.
Every strict-SemVer version a recorded repository publishes is listed too, eachwith the manifest digest its tag resolves to — the address of the exact bytespublished under that version. Where the registry's trust policy pins a public keyor trusted identities, and verification is not switched off, each version's ownsignatures are verified against that policy and the signer is recorded when oneverifies; a version with no signature, or none that verifies, is recorded with nosigner. Where several verify, the signer recorded is the one the transparency logrecorded earliest, whatever order the registry lists them in, so signing a versionagain never changes its recorded signer.
Each version's publication date is recorded too, with its source. Where one of theversion's keyless signatures verified, the date is the time the transparency logrecorded that earliest signature, as the verified log entry attests it (source'transparency-log') — so signing a version again never moves its date. Otherwiseit is the date the publication itself stated beside what it published (source'publisher'), the earliest where several are stated: the publishing machine's ownclock, which nothing attests, read from any registry whatever its trust policy.A version with neither — published without stating a date, and not signedkeyless in a way this policy verifies — is recorded with no date.
Only manifests, signature attachments and publication-date attachments are read:no entity's content is fetched. 'aggrega search -o json' reports these under eachrecord's 'published' field.
The per-repository records are byte-identical across two runs against the sameregistry state; the freshness timestamp is written to a sibling file so it neverdisturbs the records.
A refresh reads again only what changed, and finds every change a full re-readwould. For each repository it revalidates the tag listing with a conditionalrequest, resolves every version's tag to its manifest digest, and revalidates everyversion's attachments — its signatures, publication-date statements and deprecationmarkers — with one conditional request, plus one for the signatures of adeprecation marker it judged before. A version whose digest or attachments changedis read again in full, and its signatures and markers are verified again exactly asa full re-read verifies them; everything else is kept as recorded. A change to thisregistry's trust policy reads every version again under the policy now in force, andso does a repository whose entry in the index records none of these checks. Anunchanged registry therefore costs one conditional request per repository and twosmall requests per version (three where a deprecation marker was judged), withnothing downloaded. A version is read again on the next refresh where it carries adeprecation marker that was not honored, or where this run got no way torevalidate its attachments — which, on a registry that offers none, is everyversion.
Several repositories are read at a time. Everything the command records and printscomes out in repository order, so the index and the output are the same as readingone repository at a time would produce.
While it walks, a terminal shows the walk's progress on standard error, the waybuild and pull show theirs: a row naming each registry, a spinner while thatregistry's repository listing is read, then how many of its repositories the walkhas finished out of how many it lists, counted in repository order, and a bar forthe whole walk below the rows. On a terminal that cannot redraw in place, or with--plain, each registry gets one plain line instead, written when its walk ends,with the count it ended on and the time it took. When standard error is not aterminal, no progress is shown. The progress changes nothing the command prints onstandard output.
Use --upgrade to read every repository in full, comparing nothing with the indexalready written — to rebuild an index from the registry alone. It finds no change arefresh without it would miss.
Each published version's deprecation markers are read as the walk goes, and the oneswhose own signature verifies are recorded into the index. Every marker read isreported, whether or not it was recorded — a version kept as recorded is not read, soits marker is not reported again — and each registry reports how many markers itsindex now records, including when that number is zero. Where signatureverification is disabled for a registry, the walk reports that its markers were notexamined rather than a count, so a registry that published nothing is never confusedwith one this run had no basis to judge.aggrega registry update flags
| Flag | Default | Description |
|---|---|---|
--upgrade | false | Read every repository in full, comparing nothing with the index already written (a refresh without it already re-reads whatever changed) |
What registry update reports about deprecation markers
While it walks a registry, aggrega registry update reads each published version’s
deprecation markers and records the ones it can authenticate into the local index.
It reports the outcome of that scan on every path, so a registry that published no
marker is distinguishable from a run that did not look for one.
Each marker the walk reads produces one line naming the repository, the version, and
the severity the publisher recorded — warning, error or retracted — together
with whether the marker was recorded. A version whose attachments are unchanged since
the last refresh is kept as recorded rather than read, so its marker is not reported
again; the count below still includes it. A marker is recorded only when its own
signature verifies against the signers the registry’s trust policy honors. One that
is present but does not decode, or present but not honored, is reported as such and left
out of the index rather than recorded on evidence that could not be authenticated — and
so is one the registry answers it does not hold. A marker whose read failed is a
different case: see A read that fails.
Each registry then reports how many markers its index now records, including when that number is zero. Where signature verification is switched off — globally, or for that one registry — the walk reports instead that markers were not examined for it. The two are different facts: the first says the registry published nothing this workspace can act on, the second says this run had no trust basis on which to judge a marker at all. A registry whose markers were not examined contributes no withdrawal to version selection, so an author who attached a marker and sees that line knows why it has no effect.
The publication date each version records
A published manifest’s creation time is pinned, so its digest depends only on what is
published and never on when. The date a version was published is therefore read from beside
the manifest, and aggrega registry update records it for each version with the source it
came from:
transparency-log— where the version’s signature is keyless and verifies against the registry’s trust policy, the time the transparency log recorded that signature, which the log’s signed promise attests. Where several of the version’s signatures verify, it is the earliest of their times, and the signer recorded for the version is that same signature’s — whatever order the registry lists the signatures in — so a version signed again keeps its date and its signer. For a version signed as it was published, that is its publication; for one first signed afterwards withaggrega sign, it is when it was signed. This source wins wherever it exists.publisher— otherwise, the time the publication stated beside what it published: a small published-at attachment thataggrega pushandaggrega push-artifactwrite carrying the publishing machine’s own clock, which nothing attests. It is read from any registry whatever its trust policy, because it is the publisher’s statement rather than a trust decision. Where several are attached, the earliest is taken.
A version with neither records no date. That is a publication that stated none, where its
signature is not a keyless one this policy verifies — for example a keyless publication read
under a policy that trusts no keyless identity, since a keyless publication states no date of
its own. aggrega search -o json reports the date under each version in published.
What a refresh reads again
A refresh compares what the registry serves now with what the index recorded, and reads again everything that changed — the same answer a full re-read gives. For each repository it:
- revalidates the tag listing, so a version published or deleted since is picked up;
- resolves every version’s tag to the manifest it names, so an older version published again under its existing tag is read again;
- revalidates every version’s attachments — its signatures, its publication-date statements and its deprecation markers — so a signature, a date or a marker attached to a version since is read and verified, and does the same for the signatures of a deprecation marker it judged before;
- compares the registry’s trust policy with the one the index was built under, so a change to the policy reads every version again under the new one.
A deprecation marker, a signature and a publication date are each attached to a published
version as a separate object pointing back at it — which is what lets a publisher deprecate
or sign a version without publishing it again — so none of them adds a tag or changes the
version’s own manifest. They change the version’s attachments, and that is what the third
check revalidates. The version exclusion and aggrega inspect both read this index, so a
version retracted since the last refresh is excluded from selection, and shown, once the
next refresh has run.
Each check is a small request — a manifest digest resolve, or a conditional request the registry answers as unchanged without sending anything — so a refresh of an unchanged registry downloads nothing. A version that carries a deprecation marker that was not honored, or whose attachments this run got no way to revalidate, is read again on the next refresh. A registry that cannot say whether a version’s attachments changed has every version read again on every refresh: the answer is the same, and so is the cost of a full re-read.
--upgrade reads every repository in full, comparing nothing with the index already
written. Use it to rebuild an index from the registry alone; it picks up nothing a refresh
misses.
A registry that asks to slow down
The official hub, hub.aggrega.ai, limits how many requests may come from one address in a
short span, so machines sharing an address share that allowance, and any registry may limit
its clients the same way. A registry past its limit answers 429 Too Many Requests, or
503 Service Unavailable with a Retry-After header saying how long to wait. Every request
the command line makes to a registry, whatever the command, meets that answer the same way:
it waits as long as the registry asked, or ten seconds where the answer does not say, plus up
to a second more at random, and then asks again, with no fixed number of attempts. Every
request to that registry waits with it, not only the one refused, and fewer are sent to it at
once — half as many each time it asks, down to one — rising again by one after each run of
requests it serves without failing, back to the command’s usual number. The wait is shown on the same terms as the rest of the
command’s progress, as a line such as hub.aggrega.ai asked to slow down; waiting 11 s:
aggrega build, aggrega pull and aggrega registry update show it beside the step in
flight, the other commands that show what they wait on show it as a step of its own — except
aggrega sign --jobs signing several references at once, which shows them as one step — and
nothing is shown where standard error is not a terminal unless the command’s --progress
asks for it. A registry that answers nothing but “slow down” for five minutes is refused under
E0378, naming the registry,
its last answer and how long it had answered nothing else; the five minutes are fixed, and no
setting changes them. aggrega registry update then names that registry under Not indexed:
in its closing summary, and the registry keeps the index it had before the run.
A read that fails
A walk reads many small objects from a registry, and some reads fail in passing: the registry answers that it failed or is unavailable (a 5xx status, other than a 503 that says how long to wait) or that the request timed out (a 408), the connection is reset or times out, or an answer stops before it is complete. Each such read is asked again a few times, with a growing wait between attempts. A registry asking the walk to slow down is not failing a read: the read waits and is asked again as A registry that asks to slow down describes, and a registry that keeps asking for five minutes ends that registry’s walk rather than one repository’s.
A read that still fails is never taken as an answer. A signature that could not be read is not a version without a signature, and a deprecation marker that could not be read is not a version that was never withdrawn, so the walk records nothing about that repository from this run. The repository keeps the record the index already holds for it, where that record was judged under the registry’s trust policy now in force, and is otherwise left out of the index. Either way the walk names the repository in its running commentary, saying which of the two happened and which read failed, and names it again in its closing summary, on a line of its own under its registry’s row, among the repositories that could not be read:
Indexed 1 registry. registry.example.com: 41 entities, 1 repository could not be read, 4 reads retried component/core/web: the registry answered 503 Service Unavailable: …The registry’s row also says how many reads were asked again, each read counted once however
many attempts it took and whether or not it then succeeded, and says 0 reads retried when
none was. A walk whose reads all succeeded in the end shows no repository on its row, so this
count is what says how close it came to leaving one out.
Each such line opens with the kind of the read’s last failure — the status the registry
answered with, a read that timed out, a connection that was reset, or an answer cut short —
followed by the failure itself, which says which read it was. A failure of none of those
kinds, such as a trust root that could not be obtained to verify a signature against, is
given as the failure alone. The aggrega/registryUpdate method of
aggrega serve answers with the same repositories under each host’s
skipped, each with the same reason, and with the count of reads asked again as
readsRetried. The same holds for a refresh and for --upgrade, and the next walk
starts from whatever the index then holds, as it does for any repository.
The public key a keyed policy pins
A keyed trust policy pins the registry’s public key inline, as the entry’s public_key:
aggrega registry add --key <file> copies the file’s contents there, and so does pinning a
policy the registry advertises with a key in it. The value is a PEM public-key block — the
text from a -----BEGIN PUBLIC KEY----- line, or -----BEGIN RSA PUBLIC KEY-----, to its
matching -----END line — and any text above the block is ignored.
A value carrying no -----BEGIN … PUBLIC KEY----- line is refused when the configuration
file loads, naming the file and the entry. registry add makes the same check before it
writes, so a --key file holding anything else — a private key, a certificate, or a key in
another encoding — is refused and the configuration file is left as it was. Only that line
is checked: whether the block decodes to a usable key is found when a signature from the
registry is verified against it.
Offline
aggrega registry update is the one command in this group whose whole work is a walk of
the registries, and under the offline posture — the top-level offline key in a
configuration file, AGGREGA_OFFLINE, or --offline — it
refuses before it walks anything. The refusal names which of the three set the posture.
There is no partial form to fall back on, because the index records what each registry
currently serves and that cannot be learned without asking one. What an offline workspace
can do is read the index it already has: aggrega search and the deprecation notice on
aggrega inspect both read the local snapshot and need no network at all, so a refresh is
the only thing the posture takes away. To refresh for one run from an offline workspace,
pass --offline=false.
aggrega registry add reaches the network once, for the trust policy the registry
advertises, unless --fetch-trust=false, --identity or --key says not to fetch. Under
the offline posture that fetch is refused before anything is dialled, so the registry is
never asked. Adding a registry other than the official hub is then refused — adding a
registry is the one moment its trust is pinned, and an entry written without the policy
would trust nothing while every later pull held the registry to it. The refusal carries the
short code E0310 and names both ways forward: register it once while online, which
--offline=false allows for one run, or pin the policy by hand with --identity or --key,
which registers exactly what you supply and makes no fetch at all. The official hub is added on its built-in
baseline, with a notice saying the hub was not asked for its trust policy because the
workspace is offline and the baseline is used instead, and --fetch-trust=false registers
the entry from its flags exactly as it does online. The
same registration made through aggrega serve or
aggrega mcp behaves the same way: the same refusal in the same words,
and otherwise the same entry. A registry is added offline with no trust policy to
pin
quotes the refusal.
list and remove change or read local configuration and are unaffected.