Aggrega Workspace Config schema
Generated reference. Do not edit by hand — regenerate from the published JSON Schema.
Schema id: https://aggrega.ai/schemas/aggrega-config-v1beta1.schema.json
Per-workspace configuration file consumed by the aggrega CLI. Lives at .aggrega-config.yaml. The workspace block is the root marker: its presence marks the workspace root, and it holds only catalog directories. Every other key is a setting and lives at the top level, in these classes — where content is fetched from, pinned and cached (registry selection, offline, auto-pull and pinning behaviour, artifact and compiled-module cache locations and size caps), how content is trusted (signing, and signature-verification behaviour), how strictly authoring is judged (per-rule lint dials, deprecation strictness, and the authoring-release hint), which Wasm plugins are attached workspace-wide (governance, linter, importer, and per-target provider-rendering bindings), and how the CLI runs (concurrency, serving, and daemon parse-cache eviction caps). The properties below are the complete and authoritative list; this summary names the classes rather than the keys, so adding a key cannot falsify it. Flat top-level shape, no apiVersion/kind envelope, distinct from catalog content. Schema evolution discipline: adding a new top-level key is a SemVer-MINOR bump (additive); removing or relocating a key, or tightening a constraint, is a SemVer-MAJOR break.
Top-level type: object
Properties
| Property | Type | Required | Description |
|---|---|---|---|
workspace | object | no | Workspace root marker. Its presence alone marks the directory as the workspace root; it carries only the root-defining catalog directories — the workspace’s own, and any a Release is given of its own. Every setting that is not root-defining lives at the top level rather than here. Write workspace: {} to mark a root with no vendored catalog directories. |
default_registry | string | no | Default OCI registry entities are published to and dependencies are resolved from when an entity does not name a registry explicitly: aggrega push publishes there and aggrega pull fetches from there. Defaults to hub.aggrega.ai. Write the name of an entry under registries, which then stands for that entry’s host; the host itself; or the host followed by / and a repository path, such as ghcr.io/acme or harbor.example.com/platform. A name is matched first: a value that is the name of one entry is that entry’s host, even where it is also spelled like a host, so publishing, pulling, signature verification and every per-registry trust setting use that one host; a value two entries are named after is refused as ambiguous, and a name followed by a path is refused, because a name stands for an entry’s host and not for a location under it. Any other value must be a host, written in the spelling its trust policy is kept under: a lowercase host name containing a dot (registry.example.com), localhost, a single name followed by a port (registry:5000), an IPv4 address, or an IPv6 address in brackets ([::1]), each with an optional :port and with no scheme, credentials, whitespace or capital letter — optionally followed by a repository path: one or more segments of lowercase letters and digits joined by /, which may be separated inside a segment by ., _, __ or dashes, with no tag, digest or trailing /. The path is where things are published and fetched: every entity published through the default registry is published under <host>/<path>/, and every entity resolved through it is fetched from there, so what one publishes the other finds. It is never part of how a registry is trusted: the registries entry whose policy applies, a login, a signing requirement and the trusted identities are all found by the host alone. Port 443 on a host reached over HTTPS is that host’s default port, and writing it is refused, naming the spelling to write without it; localhost and the other loopback addresses are reached over plain HTTP, so 443 is an ordinary port there and is kept. An empty value names no default registry. The value is judged when the configuration loads rather than by this schema, because the entry a name refers to may be declared in another configuration file: it is read after every configuration file and the AGGREGA_DEFAULT_REGISTRY environment variable, and refused in the same words whichever of them set it, naming that file or the variable. The --registry flag that names a publication’s destination for one invocation is matched against the entries’ names the same way; any other value it carries may be a reference, and the host that reference names is held to the same spelling and is where the publication lands, with no repository path. The host is judged by its spelling alone: whether the name resolves, or a registry answers there, is not checked. Default: "hub.aggrega.ai" |
offline | boolean | no | When true, the build does not contact any registry; only cached artifacts and vendored catalog content are consulted. Defaults to false. Default: false |
auto_pull | boolean | no | When false (default), aggrega build is read-only: it never writes source pins, and a missing or incomplete per-release lockfile halts the build loudly with a diagnostic to run aggrega pull --release <release> first. When true, aggrega build runs a pull step in-process before building — resolving the Release’s dependencies into the lockfile and cache — so a first-time build against a Release does not require an explicit pull step. The same single-build opt-in is available on the command line as aggrega build --auto-pull; pull remains the sole writer of the lockfile. offline: true does not switch the pull step off: it runs over what the machine already holds — the cache and the local catalog directories — without reaching a registry, and a reference neither holds halts the build with the pull’s own refusal naming that reference. Default: false |
pin_sources_at_pull | boolean | no | When false (default), a pull records no pin beside an entity: over a Recipe or FeatureRecipe in one of this workspace’s catalog directories that the Release builds, it halts when the entity.lock beside the entity does not record a pin for each input the entity reads — a remote source: whose coordinates are written out in full, a file an artifacts entry imports, or each file of a local source: beside the entity — naming the entity, each input and its class, and aggrega pin as the step that records them. Pinning is the entity author’s step, so an entity nobody pinned is not yet ready to consume. When true, every pull in this workspace runs that step instead, over the same entities, writing the same entity.lock bytes aggrega pin writes; this is how a workspace that consumes entities someone else has not pinned records their pins once rather than halting. A build that fills its own lockfile is a pull and follows this setting. aggrega pull --pin-sources pins for one invocation and --pin-sources=false halts for one invocation, whatever this setting says. An entity resolved from the cache rather than from a catalog directory has nowhere to write a lock and is never pinned or held by a pull. Default: false |
pin_sources_at_push | boolean | no | When true, every aggrega push in this workspace runs the entity author’s pin step on the entity it publishes before bundling it, so the entity.lock the step writes beside the entity is part of what is published; when false (default), push runs no pin step and refuses a Recipe or FeatureRecipe whose entity.lock does not record every pin that step would record, naming aggrega pin. The step writes beside the entity, so it runs only where the entity has a writable home, which a push always has: it publishes an entity named by its document. aggrega push --pin-sources pins for one invocation and --pin-sources=false does not, whatever this setting says. The same step aggrega pin runs, writing the same bytes. Default: false |
artifact_cache_dir | string | no | Local artifact/content cache directory (registry pulls, OCI manifests, compiled fixtures). Defaults to .aggrega/cache. Should be gitignored by convention. The path is interpreted relative to the workspace root, wherever the command is run from; an absolute value is refused when the configuration loads, because every reader of this setting resolves it against that root and an absolute path would name a location they never reach. The cache may sit inside a catalog directory — the default does, since a catalog directory commonly is the workspace root — but it must not BE one: a catalog scan steps over the cache, so a value naming a catalog directory leaves that directory’s entire contents out of the scan. A value naming the workspace root itself (., or any spelling that reduces to it) is refused when the configuration loads, for exactly that reason. A value naming any other catalog directory is not refused: it loads cleanly and the scan then finds nothing in that directory, so keeping the cache out of the directories listed in workspace.catalog_dirs is yours to check. Distinct from parse_cache, which caps the daemon’s in-memory parse cache, and from compiled_module_cache, which caps the machine-wide compiled-module store. Default: ".aggrega/cache" |
skip_signature_verification | boolean | no | Global, loud opt-out from signature verification. When true, signature verification is disabled across every registry, including the mandatory hub baseline. Intended for break-glass and development scenarios; it is never silent — wherever a pull would have checked a signature, it warns that verification was globally disabled. Defaults to false. Default: false |
build | object | no | Build-time strictness dials and authoring hints. authoring_release provides the LSP a current Release hint for inline diagnostics; halt_on_deprecated_severity controls how the build reacts to deprecated-entity consumption; yaml_indent sets the indentation width of every rendered YAML artifact. |
plugins | object | no | Workspace-level Wasm plugin attachments. Each socket (governance, linter, importer) takes an array of plugin references; the build invokes each plugin’s documented entry function per its socket contract. The providers list binds capabilities to the provider-rendering plugins that serve them. |
lint | object | no | Per-rule strictness dials. |
parse_cache | object | no | Daemon parse-cache eviction caps. Both caps apply simultaneously — the LRU eviction loop runs after every cache insertion and removes least-recently-used entries until both the entry count and the byte total are within bounds. Either-zero means unbounded on that axis, useful for CI scenarios where the cache lives only for one invocation. Distinct from artifact_cache_dir, which is the on-disk content cache. |
compiled_module_cache | object | no | Size cap for the on-disk compiled-module cache, the machine-code store the compiler reuses so a Wasm plugin is compiled once per machine instead of once per build. It is shared across every workspace on the machine, so this key belongs in the global config file when you want one answer for the whole machine. The cap is applied once per invocation, before any plugin is loaded, by removing whole entries oldest-compiled first until the remainder fits — never while a build is compiling. Removing an entry costs a later recompile and nothing else, so the cap is safe to lower. aggrega cache status reports the store’s current size, and aggrega cache evict --max-size trims it on demand to a cap given on the command line. Distinct from artifact_cache_dir (pulled registry content) and from parse_cache (the daemon’s in-memory parse cache). |
concurrency | object | no | Daemon request-dispatch concurrency settings. The daemon reads requests off a single stdin stream and runs each through a worker pool that drains a bounded request queue; responses are emitted in request arrival order regardless of completion order. |
serve | object | no | Daemon (aggrega serve) behavior settings for the compiler-as-service consumed by IDE integrations. |
mcp | object | no | Settings for the Model Context Protocol server (aggrega mcp). transport chooses how the server is reached — over the process’s standard input and output, or over HTTP — and is read whichever one it chooses. announce_tools is read on both transports too, because which tools a client is offered is a property of the server rather than of how a client reached it. Every other key configures the listener the HTTP transport starts and is not used while the server speaks over standard input and output — listen included, which is read there only so the server can say, in one line on its error stream, that the address is not used. Each key below says which it is. Distinct from serve, which configures the editor-backend daemon. |
registries | RegistryConfig[] | no | Per-registry settings and signature trust policy, keyed by registry host. A registry not listed here uses the defaults: a present signature is verified and an absent signature is tolerated, except for hub.aggrega.ai, whose embedded baseline mandates a verified signature even with no explicit entry. An explicit entry for a host overrides that host’s baseline. Default: [] |
signing | SigningConfig | no | Top-level signing block, applying to all registries: the keyless service URLs, an optional keyed-key path, and the all-registries trust stance (required and kinds). A per-registry signing block overrides the endpoint defaults for that host and carries the same required/kinds stance scoped to that host — one name, one job, scope from placement. The top-level required/kinds policy composes monotonically across the config cascade. Security: this block holds no secret material — the OIDC identity token is never a config field (it is supplied at runtime via flag or the ambient OIDC environment) and key_path is a path to a key file, never inline key bytes. |
Additional properties are not permitted.
aggrega-config.workspace
Workspace root marker. Its presence alone marks the directory as the workspace root; it carries only the root-defining catalog directories — the workspace’s own, and any a Release is given of its own. Every setting that is not root-defining lives at the top level rather than here. Write workspace: {} to mark a root with no vendored catalog directories.
| Property | Type | Required | Description |
|---|---|---|---|
catalog_dirs | string[] | no | Optional catalog directories this workspace reads local entities from, consulted before falling back to the registry. Each entry is a filesystem path, resolved relative to the file that declares it. The list is an ordered first-win search stack: the earliest-listed directory to declare an identity owns it, and the same identity in a later directory is shadowed. The catalog directory at the workspace root is read as well, after every listed entry and only when it exists — unless a listed entry already contains it, in which case it is read as part of that entry — so listing a directory adds to what the workspace already read rather than replacing it. Omitting this key and writing it as an empty list are different statements: omitted, the workspace still reads catalog; written as [], it reads no local catalog at all, which is how a workspace says it has none. A Release given catalog directories of its own under releases reads those in place of this list. Root-scoped: local catalog directories belong to this workspace root, so they live on the root marker rather than at the top level. |
catalog_dirs_append | string[] | no | Optional append-only addition to the effective catalog_dirs list. At each precedence layer the entries here are concatenated onto the resolved base list, letting workspace and global configs compose catalog directories rather than shadow them. Same-layer interaction: when both catalog_dirs and catalog_dirs_append are specified at one layer, the resolved value at that layer is the base list followed by the append list. Default: [] |
releases | map of ReleaseCatalogConfig | no | Optional catalog directories of a Release’s own, for a workspace that keeps several catalog variants side by side and builds each Release against one of them. Each key is a Release file, written as a path relative to the file that declares it; each value carries catalog_dirs and catalog_dirs_append with the meaning they have on this block, scoped to that one Release. A Release named here reads its own catalog_dirs in place of this block’s list, followed by its own catalog_dirs_append; an entry that omits catalog_dirs keeps this block’s list and adds its catalog_dirs_append after it. The search order, the catalog directory at the workspace root, and what an empty list means are the same as for this block’s own list, and a Release this map does not name reads this block’s list exactly as before. The Release reads these directories however it is built — at a terminal, from an editor through aggrega serve, or through aggrega mcp — and a --catalog directory is still searched ahead of them for one invocation. An entry naming a file that does not exist is refused when the configuration loads, naming the entry and the file, so renaming a Release cannot quietly change the catalog it builds against. Across configuration files each Release’s entry composes the way this block’s own keys do: a nearer file’s catalog_dirs for that Release replaces a farther file’s, and every file’s catalog_dirs_append for it is added in cascade order. AGGREGA_CATALOG_DIRS sets this block’s list and reaches no entry here. An operation that concerns no single Release — a lint or validation of the whole catalog, a lookup of an entity by name, or an editor’s listing of the workspace’s entities — reads this block’s list and not these. |
Additional properties are not permitted.
aggrega-config.build
Build-time strictness dials and authoring hints. authoring_release provides the LSP a current Release hint for inline diagnostics; halt_on_deprecated_severity controls how the build reacts to deprecated-entity consumption; yaml_indent sets the indentation width of every rendered YAML artifact.
| Property | Type | Required | Description |
|---|---|---|---|
authoring_release | string | no | Path to a Release YAML file the LSP treats as the current Release context for inline diagnostics. Optional. |
yaml_indent | integer | no | Indentation width (in spaces) for every rendered YAML artifact — docker-compose files, Helm chart templates and values, and Kubernetes manifests. Defaults to 2, the conventional width for those formats. Minimum: 2. Maximum: 9. Default: 2 |
halt_on_deprecated_severity | string (enum) | no | Severity, in the ordered set warning < error < retracted, at or above which a recorded deprecation marker halts the build. It governs both places a marker is recorded: the lockfile, for everything a build reproduces byte-for-byte, and the plugin trust record beside it, for a plugin attached in a role that returns an accept-or-reject verdict — a plugins.governance attachment at ir-verdict or render-verdict, and every plugins.linter attachment. One dial, one rule, both stores. Unset by default, and unset means no recorded marker halts: a marker is recorded against a version you already pinned, so a build that succeeded once keeps succeeding. Notification and resolution are two separate axes and neither is this dial. Every surface that reads either record reports every deprecated reference it pins and every trusted plugin carrying a marker — at every severity — naming it, its severity and its message: aggrega build, aggrega validate --release, aggrega lint --release, the editor-facing daemon, and the AI-native build, describe and validate tools. So raising this threshold never reduces what you are told. This dial governs the build alone: it stops aggrega build (and the AI-native build tool, which is the same operation), while the reporting surfaces name the marker and carry on. Only a retracted marker affects which version a reference resolves to, and it does so when aggrega pull chooses a version, not at build. Allowed values: "warning", "error", "retracted" |
Additional properties are not permitted.
aggrega-config.plugins
Workspace-level Wasm plugin attachments. Each socket (governance, linter, importer) takes an array of plugin references; the build invokes each plugin’s documented entry function per its socket contract. The providers list binds capabilities to the provider-rendering plugins that serve them.
| Property | Type | Required | Description |
|---|---|---|---|
governance | PluginRef[] | no | Governance-socket plugins. Each entry names the pipeline role it is attached at (annotation-transform, label-transform, ir-verdict, or render-verdict); the role fixes both what the plugin may emit and its default entry function (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Default: [] |
governance_append | PluginRef[] | no | Append-only addition to the effective governance list. Entries here are concatenated onto the resolved base list at each precedence layer, letting workspace and global configs compose governance attachments rather than shadow them. Default: [] |
linter | PluginRef[] | no | Linter-socket plugins. Default entry function: lint_rules. A linter plugin’s exports are required to begin with lint_, so function: on one of these entries names an export with that prefix. Default: [] |
linter_append | PluginRef[] | no | Append-only addition to the effective linter list. Same compose-don’t-shadow semantic as governance_append. Default: [] |
importer | FixedEntryPluginRef[] | no | Importer-socket plugins. The socket calls the import entry function; an attachment does not name one. Default: [] |
importer_append | FixedEntryPluginRef[] | no | Append-only addition to the effective importer list. Same compose-don’t-shadow semantic as governance_append. Default: [] |
providers | FixedEntryPluginRef[] | no | Per-capability provider selections. Each entry binds one provider capability (the bare capability name a Recipe binds through spec.capability, e.g. helm or compose) to the bare identity of the provider-rendering plugin that serves it (the Plugin entity’s identity, its metadata.pluginType and metadata.name joined by a slash, e.g. provider/helm), with an optional trailing :version in the same three forms as a version pin (bare, exact :1.0.0, or major-compatible range :^1.0.0). This is the disambiguation and override surface for a federated catalog where more than one provider plugin serves the same capability: the binding selects which publisher’s plugin renders that capability. When a capability is served by exactly one provider plugin no entry is needed. Exactly one entry per capability is permitted across the composed list; a duplicate capability halts resolution loudly. Resolution is at pull: the pull records the resolved binding into the per-Release lockfile, and the build reads the lockfile — a change here after a pull is not adopted until the next pull, so build output is invariant to it (deterministic output). Every build and every validation of a Release also checks each entry here, whether or not a Recipe asks for its capability: an entry naming a plugin the build holds that does not serve the entry’s capability halts, naming what that plugin serves and a spelling one edit away when there is one; an entry naming a capability and no plugin, where no provider plugin the build reads serves that capability, is reported as a warning rather than halting, because the plugin serving it may be one only another Release reads; and an entry for a capability a plugin serves but this Release never asks for is legal and reported as nothing, since entries are written for the whole workspace and a build is of one Release. A capability containing a colon is refused when the configuration loads: a Recipe’s spec.capability is read as the capability up to its last colon and a version pin after it, so no Recipe could reach such an entry. A missing entry for an unambiguously-served capability is not an error; a missing entry for an ambiguously-served capability halts the pull loudly, listing the candidate plugins. Version coexistence is preserved: the binding selects the plugin repository per capability, and each Recipe’s own spec.capability version pin selects the version within that repository, so two Recipes pinning different versions of one provider still coexist. Default: [] |
providers_append | FixedEntryPluginRef[] | no | Append-only addition to the effective providers list. Entries here are concatenated onto the resolved base list at each precedence layer, letting workspace and global configs compose provider bindings rather than shadow them. Same compose-don’t-shadow semantic as governance_append. The one-entry-per-capability rule applies to the composed list, so an appended entry naming a capability already bound by a lower layer halts resolution loudly. Default: [] |
cli | CLIPluginRef[] | no | CLI-extension plugins installed as top-level aggrega commands. Each entry pins one CLI plugin by its resolved, version-pinned artifact reference and the content digest of the guest bytes that reference resolved to at install time. Unlike the four cross-cutting socket lists, whose base list whole-replaces across the config cascade, the CLI list composes: a CLI plugin in the global config registers its command(s) in every workspace, one in a workspace config registers only in that project, and both register together — so it needs no _append companion. The command names and help each plugin contributes come from the plugin’s own self-description, read from the on-disk describe cache keyed by digest (a load of the guest is the fallback on a cold cache); the list carries only the pin. At command invocation the resolved bytes are re-hashed and compared to digest; a mismatch halts the command loudly and instructs a re-pin, so a plugin whose bytes changed since it was pinned never runs unnoticed. Default: [] |
Additional properties are not permitted.
aggrega-config.lint
Per-rule strictness dials.
| Property | Type | Required | Description |
|---|---|---|---|
publishing_discipline | object | no | Workspace-wide gates for the publishing-linter’s rule set. The allow_* flags relax individual discouragement checks. Artifact immutability is not configurable here: aggrega push refuses to overwrite a published version unconditionally. |
Additional properties are not permitted.
aggrega-config.lint.publishing_discipline
Workspace-wide gates for the publishing-linter’s rule set. The allow_* flags relax individual discouragement checks. Artifact immutability is not configurable here: aggrega push refuses to overwrite a published version unconditionally.
| Property | Type | Required | Description |
|---|---|---|---|
allow_dynamic_refs | boolean | no | When true, the publishing-linter accepts $dynamicRef / $dynamicAnchor JSON Schema constructs in catalog content. Default false; these constructs are discouraged because they make compile-time schema composition non-local. Default: false |
allow_id_overrides | boolean | no | When true, the publishing-linter accepts $id overrides on subschemas within an entity’s schema content. Default false; $id overrides break the canonical-identifier-per-schema convention the resolver and the JSON Schema validator both rely on. Default: false |
allow_direct_x_aggrega_extensions | boolean | no | When true, the build-time discouragement check accepts x-aggrega-selector and x-aggrega-inject keywords authored directly in schema content. Default false; the recommended authoring path is usesSchema (for dependency sockets) or featuresSchema (for credential bindings), which the compiler composes into those keywords. Default: false |
allow_aggrega_ai_prefix | boolean | no | When true, the publishing-linter accepts annotation keys using the reserved aggrega.ai/ and feature.aggrega.ai/ namespaces outside their canonical contexts. The reserved-prefix rule polices catalog-entity metadata.annotations: the bare aggrega.ai/ prefix is platform-native (well-known annotation keys are exempt regardless of this flag); the feature.aggrega.ai/ prefix is canonical on Feature kind only. Default false. Operators set this when enterprise tooling legitimately needs to use a reserved prefix; it relaxes both prefixes together. Default: false |
allow_nonstandard_names | boolean | no | When true, the publishing-linter accepts catalog entity names that do not follow the project’s documented naming conventions. Default false; consistent naming is load-bearing for the resolver, label selection, and reviewer ergonomics. Default: false |
allow_category_mismatches | boolean | no | When true, the publishing-linter suppresses the category-matches-directory rule. The standard-catalog convention requires Components under core/false |
allow_undeclared_recipe_provides | boolean | no | When true, the publishing-linter suppresses the provides-declared-by-component rule. That rule reports each key a Recipe publishes in spec.provides that the Component named by its spec.implements does not declare in the provides pillar of its spec.schema. The two are separate surfaces: what a Recipe publishes is the value a consumer receives, while what the Component declares is the output contract an inject from: reference is checked against — so a key that is published without being declared makes such a reference halt. A Recipe publishing more than its Component declares is otherwise accepted at build time, which is why the finding is advisory rather than a refusal to publish. Default false. Default: false |
allow_connection_credential_mismatches | boolean | no | When true, the publishing-linter suppresses the connection-credential-matches-target-key rule, which aggrega lint --release runs over the Release it names: the Release, the Aggregate it deploys and the Components that Aggregate’s instances use. For each connection whose target declares the key it requires of its callers, the rule compares what the two ends reference: the credential the connection presents and the key the target holds in its own slot. It reports two ends naming different secrets, and a key declared at one end only, and it never quotes either. Neither end can see the other’s attachments, so the two agree only by authoring discipline — usually one parameter feeding both — and a build accepts them either way, which is why the finding is advisory. A workspace whose two ends deliberately differ opts out here. Default false. Default: false |
Additional properties are not permitted.
aggrega-config.parse_cache
Daemon parse-cache eviction caps. Both caps apply simultaneously — the LRU eviction loop runs after every cache insertion and removes least-recently-used entries until both the entry count and the byte total are within bounds. Either-zero means unbounded on that axis, useful for CI scenarios where the cache lives only for one invocation. Distinct from artifact_cache_dir, which is the on-disk content cache.
| Property | Type | Required | Description |
|---|---|---|---|
max_entries | integer | no | Cap on the number of cached parses. Default 1000. 0 disables the entry-count axis (no eviction triggered by entry count). Minimum: 0. Default: 1000 |
max_bytes | integer | no | Cap on the cumulative size, in bytes, of the documents the cache holds. Default 100000000 (100 MB). 0 disables the byte axis (no eviction triggered by byte total). Minimum: 0. Default: 100000000 |
Additional properties are not permitted.
aggrega-config.compiled_module_cache
Size cap for the on-disk compiled-module cache, the machine-code store the compiler reuses so a Wasm plugin is compiled once per machine instead of once per build. It is shared across every workspace on the machine, so this key belongs in the global config file when you want one answer for the whole machine. The cap is applied once per invocation, before any plugin is loaded, by removing whole entries oldest-compiled first until the remainder fits — never while a build is compiling. Removing an entry costs a later recompile and nothing else, so the cap is safe to lower. aggrega cache status reports the store’s current size, and aggrega cache evict --max-size trims it on demand to a cap given on the command line. Distinct from artifact_cache_dir (pulled registry content) and from parse_cache (the daemon’s in-memory parse cache).
| Property | Type | Required | Description |
|---|---|---|---|
max_bytes | integer | no | Cap on the bytes the compiled-module cache holds on disk. Default 53687091200 (50 GiB), a ceiling that stops unbounded growth rather than a budget meant to be felt — a single compiled plugin reaches hundreds of megabytes, so a machine that builds many plugin versions accumulates gigabytes. Set it above what one build compiles: the cap is applied before a build compiles anything, so a cap below a single build’s own working set makes every build discard and recompile the same modules, and the store stops saving anything. Because the cap is applied first and the build then writes what it compiles, the store can sit above the cap between builds; it is trimmed again at the start of the next one. 0 disables the cap (the store grows without bound and nothing is ever removed automatically). Because the store is one directory every workspace shares, this cap is not per-project even when a project’s own file carries it: the value resolves the same way every other key does, with the nearer file winning, but the store still has only one size. The cap in force is the one from the most recent build, so two projects capping it differently both take effect in turn, and a low cap in one discards machine code the other compiled. Setting it once in the global config file is what gives the whole machine one answer. aggrega config show --origin names the file each setting’s effective value came from. Minimum: 0. Default: 53687091200 |
Additional properties are not permitted.
aggrega-config.concurrency
Daemon request-dispatch concurrency settings. The daemon reads requests off a single stdin stream and runs each through a worker pool that drains a bounded request queue; responses are emitted in request arrival order regardless of completion order.
| Property | Type | Required | Description |
|---|---|---|---|
pool_size | integer | no | Number of workers servicing the request queue. Default 4, which dispatches up to four requests concurrently; set it to 1 to run requests serially in arrival order. A value below 1 is raised to 1 when the daemon starts. Minimum: 1. Default: 4 |
Additional properties are not permitted.
aggrega-config.serve
Daemon (aggrega serve) behavior settings for the compiler-as-service consumed by IDE integrations.
| Property | Type | Required | Description |
|---|---|---|---|
build_on_inspect | boolean | no | Whether the daemon runs the artifact-rendering stage while inspecting an IR graph, so the advisories aggrega build raises while rendering also appear as editor problems. It adds none of the checks a build halts on. Nothing is written to disk either way — no rendered artifacts, no output directory, no lockfile — and the rendering stage never mutates the graph, so where the inspection answers with one it is the same graph either way. Default false, matching aggrega inspect: the terminal command does not reach the rendering stage while inspecting a graph, so it raises no such advisory either, and an editor inspection that raises none shows you the same thing the terminal does. Set true to ask the editor for that additional layer. Default: false |
lint_on_validate | boolean | no | Whether the daemon runs the publishing-conventions check while validating a catalog entity, so the findings aggrega lint reports on that entity also appear as editor problems. The findings are advisory: a document that draws them still validates, and its Release still resolves and renders. Only the check that reads local content runs — no registry is consulted, nothing is fetched and nothing is written — and it is evaluated against the buffer the editor holds rather than the file on disk, so a name you correct stops being reported before you save. Default false: an editor session reports whether a document is correct, and says nothing about whether an entity is publishable, until you ask for that second layer. Set true to ask for it. Independent of this key, an editor can always ask for the check outright, which is also how the pre-publication comparison against the previously published version is reached. Default: false |
Additional properties are not permitted.
aggrega-config.mcp
Settings for the Model Context Protocol server (aggrega mcp). transport chooses how the server is reached — over the process’s standard input and output, or over HTTP — and is read whichever one it chooses. announce_tools is read on both transports too, because which tools a client is offered is a property of the server rather than of how a client reached it. Every other key configures the listener the HTTP transport starts and is not used while the server speaks over standard input and output — listen included, which is read there only so the server can say, in one line on its error stream, that the address is not used. Each key below says which it is. Distinct from serve, which configures the editor-backend daemon.
| Property | Type | Required | Description |
|---|---|---|---|
transport | string (enum) | no | How the server is reached: stdio speaks the protocol over the process’s standard input and output, which is how a client that launches the command as a subprocess reaches it; http serves it over HTTP on the address listen names, and over HTTPS where tls names a certificate and key. aggrega mcp --transport stdio|http overrides this key for one invocation. Default stdio, so a workspace that never names a transport is served over standard input and output whatever else this block carries — a listener starts only where http is chosen, here or on the command line. Any other value is refused when the configuration loads. Set http in the configuration of a server that callers reach over the network, and leave it unset where a client launches the server itself: with stdio chosen, an address in listen is not used, and the server says so in one line on its error stream. Allowed values: "stdio", "http" Default: "stdio" |
listen | string | no | Address the listener binds when the HTTP transport is chosen. It names where to listen and chooses nothing: the transport is transport’s to choose, and with stdio chosen this key is not used. Two forms are accepted: host:port for a TCP address, and unix: followed by a filesystem path for a Unix-domain socket. aggrega mcp --listen <address> overrides this key for one invocation. Default empty, and the HTTP transport needs an address from one or the other: with neither, a launch choosing it is refused before anything binds. A plaintext address — one reached with no certificate and key under tls — is accepted only on loopback (127.0.0.1, ::1, or localhost resolving to one of those) or on a Unix socket, which is the shape a server uses when a proxy in front terminates TLS; any other address is refused before anything binds, naming mcp.tls.cert_file and mcp.tls.key_file. The same two forms are the only ones accepted, certificate or not, where authorization.trusted_proxy is set, because a header can be trusted as a credential only where nothing but the proxy can set it. Default: "" |
tls | object | no | Certificate and key for terminating TLS inside the serving process. Set both to serve HTTPS directly from the listener listen names. Leave both unset to serve plaintext, which confines listen to loopback or a Unix socket — the shape to use when a proxy in front holds the certificate. Both keys are paths to files on disk; neither holds key material inline. |
allowed_origins | string[] | no | Origins accepted on a request’s Origin header. A request whose Origin header names an origin this list does not carry is refused with 403; a request naming a listed origin, or carrying no Origin header at all, is served. An entry is compared to the header exactly, so each one is written the way a browser sends an origin: a lowercase scheme, ://, a lowercase host — a name, an IPv4 address, or an IPv6 address in brackets — and : with the port where it is not the scheme’s default, with nothing after it. For example https://app.example.com or http://localhost:3000. An entry in any other shape could never equal what a browser sends, so it is refused when the configuration file loads, naming the file and the entry: one with a trailing / or a path (https://app.example.com/), one with no scheme (app.example.com), and one carrying a capital letter or a space. Default empty, so no origin is accepted and only a caller that sends no Origin header is served. A browser-based client therefore needs its origin listed here; a client that is not a browser sends no such header and needs no entry. Each entry matches the pattern ^[a-z][a-z0-9+.-]*://(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$. Default: [] |
limits | object | no | Caps the HTTP listener applies to the traffic it accepts, so one caller cannot exhaust the serving process. They bound how large a single request may be, how many requests run at once, and how fast one caller may send. None of them can be turned off. |
authorization | object | no | What this server declares about the bearer tokens its callers present: which authorization server issues them, the address this server publishes for itself as the resource they are issued for, optionally a file to read that server’s verification keys from, and optionally the headers a proxy in front sets when that proxy validates the tokens instead. issuer and resource are required whenever the HTTP transport is chosen, and a listener is refused before anything binds without them; a server speaking over standard input and output reads none of these. Both are published in the OAuth protected-resource metadata document the listener serves, which is the one answer an HTTP caller receives with no credential asked for, because a client reads it in order to find out where to obtain a token. This block holds no secret material: a token is presented by a caller on the request it makes and is never a configuration field, and jwks_file names public verification keys rather than anything that signs. |
deny_reach | string (enum)[] | no | Kinds of reach this server does not carry, whatever a caller’s token says. Every operation declares how far its own effects travel — none for one that reads or renders and leaves nothing behind, workspace for one that writes inside the workspace this process serves, registry for one that publishes, signs or withdraws, and machine for one that changes what every workspace on the host shares — and naming a kind here withdraws every tool of that kind from this server. A withdrawn tool is absent from the tool list and from what describe-capabilities answers, for every caller, and calling it anyway is refused naming this setting, because no scope could admit it. Default empty, so the server carries whatever its callers’ scopes admit. This is a bound the server sets on itself, on top of the per-caller bound scopes set: a server that serves reads and nothing else names the three writing kinds here and then cannot publish even to a caller whose token carries every scope. Naming machine is accepted and changes nothing — no tool of that kind is offered over HTTP at all, which is a property of the transport rather than a setting. Read while the listener starts: a value outside the four is refused when the configuration loads, and changing it takes a restart. Not read at all while the server speaks over standard input and output, where the caller is the person who launched the process. Allowed values for each entry: "none", "workspace", "registry", "machine". Default: [] |
announce_tools | string[] | no | Tools this server announces, named exactly as the tool list reports them. Omit the key and every tool this server carries is announced, which is what a client following the protocol expects: it fetches the whole tool list and decides for itself how much of it to put in front of a model. Write a list and exactly those tools are announced — one left out is absent from the tool list, absent from what describe-capabilities answers, and refused when called by name, naming this setting. Write an empty list and nothing is announced. Set it where the client at the other end caps how many tools it will register — some clients apply that cap across every server they are connected to at once — and name the tools that client needs. It narrows what is announced and nothing more: it cannot widen deny_reach, which withdraws a capability outright, nor the scopes a caller’s token carries. A tool named here of a kind deny_reach withdraws stays out of the tool list and is refused when called, naming that setting; one named here that the caller’s scopes do not admit is still listed, and a call to it is refused naming the scope that would admit it. Every name must be one this binary carries: a name no tool answers to is refused when the server starts, because whoever asked for a narrower surface would otherwise be served a different one with nothing saying so. A name in the cli- family, which runs an aggrega command in a separate process, is accepted on both transports and announces nothing over HTTP, where no such tool is offered to any caller. Read on both transports while the server starts, so the announced set is fixed for the life of the process and changing it takes a restart. |
health | object | no | Where a supervisor asks whether this process is alive and whether it is ready to answer a call. The two checks are answered on an address of their own and never on the address listen names: every request to the endpoint carries a bearer token, so a probe answered there would hand anything that can reach the endpoint an unauthenticated reading of the process together with a free way to make it work. The endpoint answers /healthz and /readyz with the same 404 it gives every path it does not serve, with a token and without one alike. |
Additional properties are not permitted.
aggrega-config.mcp.tls
Certificate and key for terminating TLS inside the serving process. Set both to serve HTTPS directly from the listener listen names. Leave both unset to serve plaintext, which confines listen to loopback or a Unix socket — the shape to use when a proxy in front holds the certificate. Both keys are paths to files on disk; neither holds key material inline.
| Property | Type | Required | Description |
|---|---|---|---|
cert_file | string | no | Path to the PEM certificate chain the listener presents, read when the process starts. Set together with key_file. Default empty, so the listener serves plaintext and listen is confined to loopback or a Unix socket. Default: "" |
key_file | string | no | Path to the PEM private key for the certificate in cert_file, read when the process starts. Set together with it. A path to a file, never inline key material. Default empty, so the listener serves plaintext and listen is confined to loopback or a Unix socket. Default: "" |
Additional properties are not permitted.
aggrega-config.mcp.limits
Caps the HTTP listener applies to the traffic it accepts, so one caller cannot exhaust the serving process. They bound how large a single request may be, how many requests run at once, and how fast one caller may send. None of them can be turned off.
| Property | Type | Required | Description |
|---|---|---|---|
max_body_bytes | integer | no | Largest request body the listener accepts, in bytes. A request whose body exceeds it is refused with 413, and the body is not read past the cap. Default 4194304 (4 MiB), which sits well above a tool call carrying a whole authoring document and well below what would let one caller hold a significant share of the process’s memory. The minimum is 1, so there is no value that turns the cap off; raise it where callers legitimately send larger documents. Minimum: 1. Default: 4194304 |
max_concurrent_requests | integer | no | How many requests the listener runs at once. A request arriving while that many are already in flight is refused with 503 rather than queued, so a caller is told to retry instead of waiting behind work it cannot see. Default 16, which leaves room for several concurrent tool calls while keeping a small host responsive; raise it on a larger host. The minimum is 1, so there is no value that turns the cap off. Minimum: 1. Default: 16 |
requests_per_minute | integer | no | How many requests one caller may send in a minute. It is counted per caller rather than per server — against the subject the caller’s token names, or against the identity a trusted proxy asserted — so one busy caller cannot spend another’s allowance. A caller may send this many in a burst; the allowance then refills steadily, at one more request every 60 / requests_per_minute seconds, and a request arriving with none left is refused with 429. Default 120, which is two a second sustained: far above what an assistant driving a workspace sends, and still a bound on a client that has gone into a loop. The minimum is 1, so there is no value that turns the cap off. Minimum: 1. Default: 120 |
Additional properties are not permitted.
aggrega-config.mcp.authorization
What this server declares about the bearer tokens its callers present: which authorization server issues them, the address this server publishes for itself as the resource they are issued for, optionally a file to read that server’s verification keys from, and optionally the headers a proxy in front sets when that proxy validates the tokens instead. issuer and resource are required whenever the HTTP transport is chosen, and a listener is refused before anything binds without them; a server speaking over standard input and output reads none of these. Both are published in the OAuth protected-resource metadata document the listener serves, which is the one answer an HTTP caller receives with no credential asked for, because a client reads it in order to find out where to obtain a token. This block holds no secret material: a token is presented by a caller on the request it makes and is never a configuration field, and jwks_file names public verification keys rather than anything that signs.
| Property | Type | Required | Description |
|---|---|---|---|
issuer | string | no | Address of the authorization server that issues the tokens this listener accepts, written as that server states its own issuer identifier — for example https://login.example.com. It is published in the authorization_servers list of the protected-resource metadata document, which is how a client learns where to obtain a token for this listener. Default empty, which is not a usable value: a listener is refused before anything binds unless this carries a whole address, scheme and host included. It is an https address unless the authorization server runs on this machine: plain http is accepted only for a loopback host, such as localhost, 127.0.0.1 or ::1, and a plain http issuer on any other host is refused before anything binds, naming this key and asking for an https address. That holds whether the keys are read from the issuer, from jwks_file, or a trusted_proxy in front checks the tokens, because every client is sent to the issuer to obtain its token. Default: "" |
resource | string | no | Address this server publishes for itself, as a caller reaches it — for example https://mcp.example.com/mcp. Write the address callers actually use, including the host a proxy in front presents, because this is the identifier a client hands the authorization server when it asks for a token for this server, and it is published unchanged as the resource field of the protected-resource metadata document. Where that document is served is derived from it, by inserting /.well-known/oauth-protected-resource between the host and the path: a server published as https://mcp.example.com/mcp serves it at https://mcp.example.com/.well-known/oauth-protected-resource/mcp, and also at that well-known path with nothing after it, which is where a client looks second. A token is accepted only where this address is among the audiences it names. Default empty, which is not a usable value: a listener is refused before anything binds unless this carries a whole address, scheme and host included. Default: "" |
jwks_file | string | no | Path to a file holding the JSON Web Key Set the tokens this server accepts are verified against, read when the process starts. Default empty, which is the usual case: the keys are read from the authorization server itself, by asking issuer where it publishes them and fetching them from the address it names, and they are re-read once when a token arrives signed by a key identifier the held set does not carry. Set this where the workspace is offline, in which case a listener is refused before anything binds without it, because an offline workspace makes no network request and there is no other way to obtain the keys; the file then holds the only keys accepted, and the authorization server is never contacted. The file holds public verification keys and never anything that signs. A relative path resolves against the directory of the config file that declared it. Default: "" |
trusted_proxy | object | no | Read who a caller is from headers a proxy in front sets, instead of validating a bearer token here. Set this only where both hold: a proxy in front validates tokens itself, and nothing but that proxy can reach the listener: with it set, listen must be loopback or a Unix socket, and any other address is refused before anything binds, naming both settings. A header is trustworthy exactly as far as the set of callers that can set it, and on an address the network reaches every caller can set any header it likes, so a listener in this mode on such an address would let every caller claim to be anyone. With this set no token is read at all — not from the Authorization header, not from anywhere else, and no key set is fetched — the caller’s identity is the value of principal_header, a request that does not carry that header is answered 401, and the two headers named here are the only ones read. Leave it out, which is the default, and this server validates bearer tokens itself. |
Additional properties are not permitted.
aggrega-config.mcp.authorization.trusted_proxy
Read who a caller is from headers a proxy in front sets, instead of validating a bearer token here. Set this only where both hold: a proxy in front validates tokens itself, and nothing but that proxy can reach the listener: with it set, listen must be loopback or a Unix socket, and any other address is refused before anything binds, naming both settings. A header is trustworthy exactly as far as the set of callers that can set it, and on an address the network reaches every caller can set any header it likes, so a listener in this mode on such an address would let every caller claim to be anyone. With this set no token is read at all — not from the Authorization header, not from anywhere else, and no key set is fetched — the caller’s identity is the value of principal_header, a request that does not carry that header is answered 401, and the two headers named here are the only ones read. Leave it out, which is the default, and this server validates bearer tokens itself.
| Property | Type | Required | Description |
|---|---|---|---|
principal_header | string | yes | Header the proxy in front puts the caller’s identity in — for example X-Forwarded-User. It is written as an HTTP header name: letters, digits and hyphens, and the other characters a header name may carry (!#$%&'*+.^_|~ and the backtick), with no space, colon or other separator. A name in any other shape is refused when the configuration file loads, naming the file and the key, because no request can carry such a header. An empty one is refused too: it would leave this server checking tokens itself while the block says a proxy in front does. To leave this mode off, leave trusted_proxy out. The header’s value is taken exactly as written and compared to nothing, in the same way the subject of a token this server validates itself is recorded and compared to nothing. It is the whole credential in this mode, so it is required whenever trusted_proxy is set, and a request arriving without it is answered 401. Pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$. |
scopes_header | string | no | Header the proxy in front puts the caller’s granted scopes in, separated by spaces — for example X-Forwarded-Scopes. It is written as an HTTP header name, in the same shape as principal_header, or left empty. A name in any other shape is refused when the configuration file loads, naming the file and the key, because no request can carry such a header and no caller would ever be granted a scope. Default empty, which asserts no scopes for any caller. Whatever it is called, no header other than this one and principal_header is read. Pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]*$. Default: "" |
Additional properties are not permitted.
aggrega-config.mcp.health
Where a supervisor asks whether this process is alive and whether it is ready to answer a call. The two checks are answered on an address of their own and never on the address listen names: every request to the endpoint carries a bearer token, so a probe answered there would hand anything that can reach the endpoint an unauthenticated reading of the process together with a free way to make it work. The endpoint answers /healthz and /readyz with the same 404 it gives every path it does not serve, with a token and without one alike.
| Property | Type | Required | Description |
|---|---|---|---|
listen | string | no | Address the liveness and readiness checks are answered on, in the same two forms listen takes: host:port, or unix: followed by a filesystem path. Default empty, so no second listener is started and neither check is answered anywhere. With an address set, GET /healthz is answered 200 from the moment the process is running, and GET /readyz is answered 503 until the workspace has resolved and the endpoint has bound and 200 from then on — which is the distinction a supervisor needs, since a process that is up is not yet a process that can answer a call. Every answer is a status code with an empty body, no token is asked for and no header is read; any other path on this address is 404, and any other method on these two is 405. Unlike listen this address is not confined to loopback or a Unix socket and no address is refused for it: point it at one of those, which is what it is for, and note that whatever can reach the address you choose can read those two answers. Default: "" |
Additional properties are not permitted.
Definitions
ReleaseCatalogConfig
One Release’s own catalog directories: the same two keys the workspace block carries, scoped to that Release.
| Property | Type | Required | Description |
|---|---|---|---|
catalog_dirs | string[] | no | Catalog directories this Release reads local entities from in place of the workspace’s catalog_dirs, each resolved relative to the file that declares it. The same ordered first-win search stack as the workspace’s list, with the catalog directory at the workspace root read after it when that directory exists and no listed entry already contains it. Omitted, the Release keeps the workspace’s list; written as [], it reads no local catalog at all. |
catalog_dirs_append | string[] | no | Catalog directories added after this Release’s list — its own catalog_dirs where the entry writes one, the workspace’s otherwise — each resolved relative to the file that declares it. Default: [] |
Additional properties are not permitted.
RegistryConfig
Settings and signature trust policy scoped to one OCI registry host.
| Property | Type | Required | Description |
|---|---|---|---|
host | string | yes | The registry host these settings apply to (e.g. hub.aggrega.ai). Matched against the registry host of the push/pull target, so it is written in the spelling that match is made in: a lowercase host name containing a dot, localhost, a single name followed by a port (registry:5000), an IPv4 address, or an IPv6 address in brackets, each with an optional :port — with no scheme, path, credentials, whitespace or capital letter. Port 443 on a host reached over HTTPS is that host’s default port, and writing it is refused when the configuration loads, naming the host to write without it, because an entry spelled that way would never be the one found; localhost and the other loopback addresses are reached over plain HTTP, so 443 is an ordinary port there and is kept. aggrega registry add and aggrega config init --registry key the entry under the host their argument names and refuse one not spelled this way. The host is judged by its spelling alone: whether the name resolves, or a registry answers there, is not checked. Pattern: ^(?:(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?|localhost|(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|\[(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:|(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}|(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}|(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}|(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}|:(?:(?::[0-9a-f]{1,4}){1,7}|:))\])(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))$. |
name | string | no | Optional friendly alias for this registry. The host is the identity; name is a convenience selector that resolves to this entry’s host wherever a registry is named (for example --registry, or default_registry). An alias must be unique across entries. |
trusted_identities | TrustedIdentity[] | no | OR-set of keyless signing identities accepted for artifacts pulled from this registry. A signature verifies when its certificate matches any one entry. Used by the keyless verification path. Default: [] |
trusted_deprecation_identities | TrustedIdentity[] | no | OR-set of keyless identities additionally accepted to sign a retroactive deprecation marker for an artifact pulled from this registry. A deprecation marker is honored when its signature matches the original artifact’s signer OR any entry here — so a registry owner or a security team can retract an artifact the original publisher can no longer reach, without being trusted to sign the artifacts themselves. Used only by the deprecation discovery path; it never widens the trust set for artifact signatures. Default: [] |
public_key | string | no | Pinned cosign-compatible public key for a keyed-mode registry, written inline as a PEM block: the text from a -----BEGIN PUBLIC KEY----- line (or -----BEGIN RSA PUBLIC KEY-----) to its matching -----END line, as aggrega registry add --key copies it from a key file. When set, signatures from this registry are verified offline against this key rather than against keyless identities. A value carrying no -----BEGIN … PUBLIC KEY----- line is refused when the configuration file loads, naming the file and the entry, and so is a private key pasted here by mistake. The line may sit anywhere in the value, because the key is read from the PEM block the value carries and any text before that block is ignored. Only that line is checked here: whether the block holds a key that decodes is found when a signature from this registry is verified against it. The value is declared sensitive (x-aggrega-sensitive), so a refused value — a private key picked by mistake above all — is never quoted: the refusal names the file, the entry and the constraint the value failed — the pattern above, or the string type — and shows <redacted> where the value would be. A public key that loads is read and shown as written. Pattern: -----BEGIN [A-Z ]*PUBLIC KEY-----. |
trusted_root | string | no | Optional path to a pinned Sigstore trust-root bundle for air-gapped keyless verification. When set, the keyless trust anchor is loaded from this file with no network; when empty, the public-good trust root is fetched and cached. |
advisory | boolean | no | When true, a signature verification failure for this registry is downgraded to a warning rather than halting the pull. Verification still runs and the failure is reported; the pull proceeds. Defaults to false. Default: false |
skip_signature_verification | boolean | no | Per-host break-glass opt-out from signature verification — the same skip_signature_verification switch as the global one, scoped by placement to this host. It does not defeat the top-level signing.required policy: an org-required signature is still verified on this host regardless of this switch; only the global switch can disable that. Setting this together with a per-registry signing.required on the same host is allowed, and combines a signature required on push with verification skipped on pull: the skip wins on the verify side, since a per-host required stance (unlike the top-level one) is not immune to the per-host skip. Defaults to false. Default: false |
signing | SigningConfig | no | This registry’s signing block: the keyless service URLs, an optional keyed-key path, and the per-host trust stance. The endpoint fields override the global signing block for pushes to this host; a CLI flag overrides both. required and kinds read from placement — under a registry entry they scope the one trust stance to this host (publishing an in-scope unsigned artifact is refused, and consuming an unsigned one is refused), the same concept the top-level signing block carries for all registries. |
Additional properties are not permitted.
SigningConfig
A signing block: the keyless service URLs, an optional pointer to a keyed-key file, and the trust stance (required and kinds). Placed at the top level it applies to all registries; placed under a registries[] entry it applies to that host — every field reads its scope from placement. required is one trust stance covering both directions (an unsigned in-scope push is refused and an unsigned in-scope pull is refused). Security: it holds no secret material — the OIDC identity token is never a config field (short-lived, supplied at runtime), and key_path is a path to a key file, never inline key bytes. This mirrors the verify side’s asymmetry: an inline public_key is allowed there, but the sign side carries only a key path. An aggrega mcp server reached over HTTP consults no key_path at either placement, so keyed signing is unreachable through such a listener: a call it answers signs only with an identity token that call carries.
| Property | Type | Required | Description |
|---|---|---|---|
fulcio_url | string | no | Fulcio certificate-authority URL for keyless signing. When unset, the public-good Fulcio instance is used. It is written as an absolute https URL: https://, a host, and optionally a port and a path, with no whitespace — for example https://fulcio.sigstore.dev. A value in any other shape, such as one with no scheme (fulcio.example.com) or one beginning http://, is refused when the configuration file loads, naming the file and the key. The file is checked before anything else is applied on top of it, so the same endpoint supplied by AGGREGA_SIGNING_FULCIO_URL, by the --fulcio-url flag, or in a publishing request from an editor or an assistant is not held to this shape. Pattern: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
rekor_url | string | no | Rekor transparency-log URL for keyless signing. When unset, the public-good Rekor instance is used. It is written as an absolute https URL: https://, a host, and optionally a port and a path, with no whitespace — for example https://rekor.sigstore.dev. A value in any other shape, such as one with no scheme (rekor.example.com) or one beginning http://, is refused when the configuration file loads, naming the file and the key. The file is checked before anything else is applied on top of it, so the same endpoint supplied by AGGREGA_SIGNING_REKOR_URL, by the --rekor-url flag, or in a publishing request from an editor or an assistant is not held to this shape. Pattern: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
timestamp_url | string | no | RFC3161 timestamp-authority URL for keyless signing. It has no default: when unset, no timestamp authority is contacted, and a keyless signature’s trusted time comes from its transparency-log entry. It is written as an absolute https URL: https://, a host, and optionally a port and a path, with no whitespace — for example https://tsa.example.com/api/v1/timestamp. A value in any other shape, such as one with no scheme (tsa.example.com) or one beginning http://, is refused when the configuration file loads, naming the file and the key. The file is checked before anything else is applied on top of it, so the same endpoint supplied by AGGREGA_SIGNING_TIMESTAMP_URL, by the --timestamp-url flag, or in a publishing request from an editor or an assistant is not held to this shape. Pattern: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
key_path | string | no | Path to a held ECDSA P-256 private-key PEM file for offline keyed signing. A path to a file, never inline key material. When unset, the keyless path is used. An aggrega mcp server reached over HTTP never consults this key, wherever it is set — in the top-level signing block, in a registry entry’s, or by AGGREGA_SIGNING_KEY_PATH: a call such a listener answers signs only with an identity token the call itself carries, or is refused. A server reached over standard input and output signs with it as a terminal does. |
required | boolean | no | The one trust stance for this block’s scope: when true, publishing an in-scope artifact kind requires a signature (an unsigned in-scope push is refused), and consuming one requires a signature (an unsigned in-scope pull is refused). Scope reads from placement — on the top-level signing block it covers every registry; under a registries[] entry’s signing block it covers that one host. One name, one job, both scopes. The top-level policy composes monotonically across the config cascade — any layer that sets it true makes it effective true, and no lower-precedence layer can turn it back off — so it cannot be removed by an ordinary config edit. Defaults to false. Default: false |
kinds | string[] | no | Scopes required to specific artifact kinds. Empty or a single all entry means every signable kind; otherwise the stance applies to exactly the listed kinds, matching the entity kind: value (e.g. Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate, Plugin). On the top-level signing block it composes as a union across the cascade — a layer can widen the scope but never shrink it. Scope reads from placement, the same as required. Default: [] |
Additional properties are not permitted.
TrustedIdentity
One acceptable keyless signing identity: a certificate subject (the OIDC identity) paired with the OIDC issuer that vouched for it.
| Property | Type | Required | Description |
|---|---|---|---|
identity | string | no | Exact certificate subject alternative name — the OIDC identity bound into the short-lived signing certificate (e.g. a maintainer email or a CI workflow URI). |
identity_regexp | string | no | Regular expression matched against the certificate subject, used instead of an exact identity (e.g. to accept any workflow under an organization). |
issuer | string | yes | OIDC issuer URL that issued the identity token (e.g. https://accounts.google.com or https://token.actions.githubusercontent.com). |
Additional properties are not permitted.
PluginRef
Reference to a Wasm plugin attached at a socket whose entry function the attachment may name — the governance and linter lists. The sockets whose entry point is fixed instead use FixedEntryPluginRef, which carries these same fields without function. uri and capability together select the plugin: uri only is a direct attach (the plugin at that identity is attached verbatim — the cross-cutting sockets’ path, since their plugins declare no served capabilities); capability only resolves the plugin serving that capability (the bare capability name a Recipe binds through spec.capability, e.g. helm); both together disambiguate — capability names what to resolve and uri selects which publisher’s plugin serves it, by that plugin’s bare identity, in a federated catalog where more than one plugin serves the capability. function overrides the socket’s default entry function; when omitted, the socket’s documented default applies — on a governance entry that default follows from role. role names the governance attachment role and is read on a governance entry only. with carries optional attachment-time inputs the plugin reads.
| Property | Type | Required | Description |
|---|---|---|---|
uri | string | no | Plugin identifier: a Plugin entity’s bare identity — the <pluginType>/<name> path, e.g. governance/redact or provider/helm — a local filesystem path, or a registry alias. Optional: an entry may instead select the plugin by capability. An optional trailing :version pins the version in the same three forms as any version pin (bare, exact :1.0.0, or major-compatible range :^1.0.0). |
role | string (enum) | no | The pipeline role a governance attachment is bound to, read on a governance entry only: annotation-transform injects annotations onto resolved components before annotation expansion, so bound injections become Feature attachments; label-transform auto-tags topology-graph node labels at topology construction; ir-verdict renders an accept/reject verdict over the IR graph at static analysis; render-verdict renders a verdict over the rendered artifacts at rendering. The role — not the plugin’s declared kind — fixes what the plugin may emit: a verdict role’s output can only be read as a verdict, never applied as a change; a transform role’s output is host-confined to its facet (annotations or labels). It also selects the default entry function (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Allowed values: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | no | The provider capability this entry selects a plugin for — the bare capability name a Recipe binds through spec.capability (e.g. helm, compose). Optional: an entry may instead attach a plugin directly by uri. The provider bindings use this to select which publisher’s plugin serves a capability in a federated catalog; the cross-cutting sockets leave it empty and attach by uri. |
function | string | no | Optional override for the socket’s default entry function. When omitted, the socket’s documented default applies (governance annotation-transform → transform_annotations, governance label-transform → mutate, governance ir-verdict → verdict_ir, governance render-verdict → verdict_render, linter → lint_rules). The override may name any export the plugin declares, and the export it names must return the output shape that socket reads: the build halts when that output carries a top-level field the shape does not declare, naming the export called and the unexpected field. The check reads which top-level field names are present, not which are absent or what nests beneath them, so it is not a full validation of the output. |
with | PluginRefWith | no | Optional attachment-time inputs the plugin reads. Both members are optional and socket-agnostic, so any socket may reuse this surface. |
Additional properties are not permitted.
FixedEntryPluginRef
Reference to a Wasm plugin attached at a socket whose entry point is fixed rather than named by the attachment — the importer list and the providers bindings. It carries the same fields as PluginRef without function: the importer socket calls the one entry function its socket contract names, and a provider drives a fixed set of phase-keyed exports rather than one selectable entry, so on neither list is there an entry for function to name and the key is not accepted there. uri and capability together select the plugin: uri only is a direct attach (the plugin at that identity is attached verbatim — the importer socket’s path, since its plugins declare no served capabilities); capability only resolves the plugin serving that capability (the bare capability name a Recipe binds through spec.capability, e.g. helm); both together disambiguate — capability names what to resolve and uri selects which publisher’s plugin serves it, by that plugin’s bare identity, in a federated catalog where more than one plugin serves the capability. role is accepted here but read on neither list this shape serves: the governance attachment role it names is read on a governance entry, which uses PluginRef, so a role set on one of these entries has no effect. with carries optional attachment-time inputs the plugin reads; a provider binding takes its render configuration from the Recipe instead, so with: on one is refused at load.
| Property | Type | Required | Description |
|---|---|---|---|
uri | string | no | Plugin identifier: a Plugin entity’s bare identity — the <pluginType>/<name> path, e.g. governance/redact or provider/helm — a local filesystem path, or a registry alias. Optional: an entry may instead select the plugin by capability. An optional trailing :version pins the version in the same three forms as any version pin (bare, exact :1.0.0, or major-compatible range :^1.0.0). |
role | string (enum) | no | The governance attachment role. Neither list that uses this shape reads it — the role is read on a governance entry, and those entries use PluginRef — so a role set here is accepted and has no effect. The permitted values are the four governance roles, and what each one means is described on PluginRef. Allowed values: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | no | The provider capability this entry selects a plugin for — the bare capability name a Recipe binds through spec.capability (e.g. helm, compose). Optional: an entry may instead attach a plugin directly by uri. The provider bindings use this to select which publisher’s plugin serves a capability in a federated catalog; the cross-cutting sockets leave it empty and attach by uri. |
with | PluginRefWith | no | Optional attachment-time inputs the plugin reads. Both members are optional and socket-agnostic, so any socket may reuse this surface. |
Additional properties are not permitted.
CLIPluginRef
A pinned CLI-extension plugin installed as a top-level aggrega command: the resolved, version-pinned artifact reference the command resolves and runs, and the content digest of the guest bytes that reference resolved to at install time. Together they pin exactly which bytes the command executes; the digest also keys the describe cache that supplies the command’s names and help without loading the guest.
| Property | Type | Required | Description |
|---|---|---|---|
uri | string | yes | The resolved, version-pinned artifact reference the command resolves and runs, e.g. oci://hub.aggrega.ai/plugin/cli/<name>:1.2.0, pinned at install. |
digest | string | yes | The content digest of the guest .wasm bytes the reference resolved to at install, written as sha256: followed by the 64 lowercase hexadecimal digits of the bytes’ SHA-256 — the spelling aggrega plugin add cli records, and the spelling the resolved bytes are compared in. A digest in any other spelling — bare hexadecimal without the sha256: prefix, capital letters, or a different length — could never equal it, so it is refused when the configuration file loads, naming the file and the entry. It pins the exact bytes the command runs — a later resolution whose bytes hash differently halts the command — and is the key into the describe cache that renders the command’s help without loading the guest. Pattern: ^sha256:[0-9a-f]{64}$. |
Additional properties are not permitted.
PluginRefWith
Optional attachment-time inputs a plugin reads. Both members are optional and the surface is general, so any socket may reuse it.
| Property | Type | Required | Description |
|---|---|---|---|
sources | string[] | no | Definition file paths the host reads at compile time and hands to the plugin. Each entry is a filesystem path resolved against the declaring config file’s directory. |
settings | object | no | Free-form settings object handed to the plugin verbatim. The host does not interpret its shape; the plugin defines the keys it reads. |
Additional properties are not permitted.