Skip to content
AggregaAggrega
Select language: English

Configuration

Where aggrega reads its settings from, and which file to put a setting in.

The simple case

Two files, and most projects need nothing else.

One file in your project, named .aggrega-config.yaml, sitting at the project root. It holds how this project builds: which directories hold vendored catalog content, which plugins render which targets, which lint rules are relaxed, where the local cache goes. It is committed, so a teammate who clones the project builds it the same way.

Its workspace: block is what marks the directory as the project root:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs:
- ./catalog
auto_pull: true

The block carries only the root-defining catalog directories; every other setting sits at the top level beside it. A project that vendors no catalog content still writes the block, empty — workspace: {} — because the block’s presence is the marker.

One global file on your machine, at ~/.config/aggrega/config.yaml — on Windows, at aggrega\config.yaml inside the directory the APPDATA environment variable names. Every workspace on that machine resolves through it, and it holds settings that belong to the machine rather than to any one project — the registries you pull from and the signature trust policy for each, how large the compiled-module store may grow, and any command-extension plugin you have installed. Those are the same wherever you are working, so declaring them once is the point. It loads automatically when it is there, and nothing breaks when it is not.

~/.config/aggrega/config.yaml
registries:
- host: hub.aggrega.ai
signing:
required: true

aggrega config init writes that global file for you, registering a registry together with the signature trust policy it advertises, and says where the file is on your machine and where the machine-wide caches are kept. aggrega config show prints what applies right now, and aggrega config show --origin says which file — or which environment variable — decided each setting.

Secrets are not configuration. A registry password and a signing identity token are never fields in either file; they are supplied by environment variable or flag at the moment they are needed. See environment-variables.md.

Where local entities are read from

A project that keeps catalog content of its own — a Component, a Feature, a Recipe, one of the library kinds — has two ways to say where that content lives, and the first needs no configuration at all.

A catalog directory at the project root is read whether or not anything names it. Put an entity under <project>/catalog/ and every command that loads a catalog reads it, including in a project whose workspace: block is empty. A catalog directory is read recursively, so how you arrange subdirectories inside one is yours.

Directories listed under workspace.catalog_dirs are read as well, and they are read first. The list is an ordered search stack: the first directory to declare an identity owns it, and the same identity in a later directory is shadowed. catalog is read after everything listed — unless a listed directory already contains it, in which case it is read as part of that directory — so listing a directory adds to what you had rather than replacing it. A repeatable --catalog <dir> on the command line is read ahead of both, and a relative path given there resolves against the directory you ran the command from, since no configuration file declared it. A directory named more than once — on the command line and in the list, or twice in the list — is read once, at the place it was first named, so nothing in it is reported as shadowed by itself: a shadow is always two different files declaring one identity. Two spellings of one directory, a path to it through a link, and — on a file system that ignores case — a spelling in another case all name that one directory. A directory inside another listed directory is still read as its own entry. A project that keeps a catalog variant per Release can give each Release a list of its own instead — see Giving a Release its own catalog directories.

Listing a directory is how a project reads entities kept outside it. A listed directory may lie anywhere — a sibling checkout, a directory shared with other projects — and is read where it is, even when it is itself a symbolic link. Nothing else reaches that far: a link inside the project leading elsewhere is not read through, and a document naming a file outside the project by a path is refused, so an entity kept elsewhere is reached by listing the directory that holds it and naming the entity by its name. A listed directory outside the project is a root of its own, so a link beneath it leading out of it is not read either. The workspace boundary states the whole rule.

A listed directory must be a directory. A listed path where nothing exists, or where a file or a link leading nowhere stands, is refused before anything is read or written by every command that reads the catalog — a pull, a build, a validation, an inspection, a lint, and the same operations driven from the editor through aggrega serve or from an assistant through aggrega mcp — so a build never runs against fewer catalogs than you listed. The refusal names the entry as written, the path it resolved to, the configuration file and line listing it, and the list it sits in:

<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalid

Create the directory, or remove the entry: a copy of a project taken without a sibling checkout it lists removes that entry, and resolves from a registry what the checkout would have supplied. The same holds for a directory a Release’s own entry lists, for one a configuration file your pipeline owns or the global file adds, and for one AGGREGA_CATALOG_DIRS carries, which the refusal names in place of a file. The configuration itself still loads, so a command that reads no catalog still runs. A --catalog directory that does not exist was typed for one command, and aggrega build refuses it, naming the directory. A listed directory that is there and cannot be read is refused by the commands that load the whole catalog, naming it.

Writing the list as empty says this project has no local catalog at all, and it is the one spelling that stops catalog being read too:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs: []

Leaving the key out is a different statement: an omitted list is the ordinary case, and catalog is still read.

A build, a pull, a validation or an aggrega inspect that finds no entity under a name you used says where this project reads local entities from and what to change so the one you named is read. It says nothing of the kind where you wrote the empty list — reading no local catalog is what you declared there, and a suggestion to change it would be arguing with you. Nor does it say it where the document declaring that name was read and refused: that document already sits where the catalog reads, so the report names what the document violates instead, the line and the constraint, and moving it would fix nothing. A document too malformed for the name it declares to be read at all cannot be matched to the name you used, so the account is still given — and where that document declares an Aggrega apiVersion, a build, a pull or a validation of a Release names it beside the account, with the parser’s own reason, since it may be the file to open. A failure that found the entity and could not accept it — a registry now serving other bytes under a version your lockfile pins, a file the entity carries that cannot be read — is not a missing entity either, and it reports its own remedy alone.

Whether a pull or a push pins an entity

A Recipe or FeatureRecipe carries the pins for the inputs it reads — a remote source: written out in full, a file an artifacts entry imports, the files of a source: beside it — in the entity.lock beside it, and recording them is the entity author’s step, aggrega pin. By default neither pull nor push runs that step: a pull halts on an entity its lock does not pin, and a push refuses to publish it. Two keys, one per command, make running it that command’s default:

# <project>/.aggrega-config.yaml
workspace: {}
pin_sources_at_pull: true
pin_sources_at_push: true

Each key governs its own command and nothing else, and each command’s --pin-sources overrides its own key in both directions — --pin-sources=false turns the step off for one run in a project configured to pin. A build that fills its own lockfile is a pull and follows pin_sources_at_pull. They belong in the project file rather than the global one: whether a project’s pulls record pins is that project’s policy, and a teammate who clones it should get the same answer. pin_sources_at_pull is also how a project consuming someone else’s unpinned catalog records those pins once rather than halting on every pull.

Which plugin renders a capability

A Recipe names the capability it renders through — capability: helm — and a plugin serving that capability renders it. Where exactly one plugin serves a capability nothing needs configuring. Where more than one does, a plugins.providers entry says which, by the plugin’s identity:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
providers:
- capability: helm
uri: provider/helm

A pull resolves the entry and records the plugin it chose in the Release’s lockfile, and a build renders through what the lockfile records, so an edit here takes effect at the next pull.

The uri names the plugin by its identity, provider/<name>, never by where it is published. aggrega plugin add provider <query> --capability <capability> writes the entry in that form, without a version: the entry selects which plugin serves the capability, the version is the one the Recipe pins or else the highest available, and the lockfile records the one the pull chose. A plugin the compiler carries inside it is served at the compiler’s own version, so a version written on an entry for one of those resolves only when it is that version. An entry whose uri is a registry location — oci://hub.aggrega.ai/plugin/provider/helm — names no plugin’s identity, and it is refused when the file loads, naming the entry and the form to write.

The entries are written once for the whole project, while a build is of one Release, so an entry for a capability this Release never asks for is legal — another Release in the project reads it — and is reported as nothing. What each build and each aggrega validate --release does check is every entry, whether or not a Recipe asks for its capability, by what the entry names:

  • An entry naming a plugin whose plugin does not serve its capability stops the build and fails validation. A pull resolves every entry that names a plugin, and refuses one it cannot resolve, so once an entry has been through a pull the build holds its plugin and knows what it serves; an entry naming a plugin the build does not yet hold is judged once a pull has fetched it. The message names the entry, the plugin, what that plugin does serve, and a spelling one edit away when there is one — the shape a typo such as hlem for helm takes.
  • An entry naming only a capability that no plugin the build reads serves is a warning, and the build carries on. The plugin serving it may be one only another Release reads, which this build cannot see, and an entry naming no plugin selects nothing the capability’s resolution would not select without it.

A capability here never contains a colon, and one that does is refused when the file loads. A Recipe’s capability: is read as the capability up to its last colon and a version pin after it, so an entry keyed helm:1.0.0 could never be looked up. Pin the version on the plugin instead — uri: provider/helm:1.0.0 — or in the Recipe.

Which importer turns a source into drafts

aggrega import hands a source to the importer that advertises the source’s format — one in your catalog or one of the compiler’s core importers, import:langflow for a Langflow flow. Where exactly one importer advertises it, nothing needs configuring. A plugins.importer entry attaches an importer by naming it in its uri, by its identity and version, and hands it what it carries under with:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
importer:
- uri: importer/agent-flows:1.2.0
with:
settings:
target_namespace: payments

aggrega plugin add importer writes the uri in exactly that form. The version is exact — :1.2.0 — or a range — :^1.2.0 for the highest version at or above it within the same major. Write one or the other: on this list a uri with no colon is read as a filesystem path, as Where a relative path points describes, and names no importer.

What an entry does depends on whether the importer it names advertises the format an import asks for:

  • It does: that importer is the one that runs, at the version the uri names, however many other importers in the catalog advertise the format too, and it is handed the entry’s with.sources and with.settings. An entry is how a workspace whose catalog federates two publishers’ importers for one format says which of them it uses.
  • It does not — it names an importer of another format, a plugin of another kind, or nothing your catalog holds or the compiler carries: the entry plays no part in that import. It chooses nothing, and its with is handed to no importer. An entry’s settings reach only the importer it names, so a workspace attaching one importer per format configures each without the settings of one reaching the other.

Where more than one importer advertises the format and no single one of them is attached — none is, or entries name two of them — the import is refused, naming the importers it could not choose between. An entry naming an importer that advertises the format, at a version no version of it in the catalog satisfies — an exact version the catalog does not hold, or a range none of its versions falls in — is refused too, naming the version, rather than running another version in its place; a version that is not one at all, such as :latest, is refused as malformed. A Plugin entity of one of the compiler’s core importers with no module beside it in its catalog folder is no candidate: at the compiler’s own version the core importer runs in its place, and at any other version the entity stays a candidate only where an entry names exactly that version or no importer of its name that can run advertises the format, as Which one runs beside your own importers describes.

Each importer is attached by one entry. Two entries naming one importer — the same identity, at one version or at two — are refused when the configuration loads, whichever command reads it, naming both entries and the files they were written in. The rule spans every file that contributes to the list: an entry in the global file, one in a project’s file, one under importer_append, and one in a pipeline’s .aggrega-config-append-ci.yaml all count, so moving an importer to a new version means changing the version on its one entry. aggrega plugin add importer does exactly that when the plugins.importer list of the file it writes already names the importer: it moves that entry to the version it resolved, keeping the entry’s place and its with, rather than adding a second one. It reads no other list, so an importer attached under importer_append, or in a pipeline’s .aggrega-config-append-ci.yaml, is attached a second time by the command and the pair is refused when the configuration loads; change the version on such an entry where it is written. An entry whose uri is a filesystem path names no importer and is not compared, and the plugins.governance and plugins.linter lists are not held to the rule: one plugin may be attached to them more than once, each time with its own with.

The parsers an import reads through need no entry. An importer reads its source — and an import naming no format recognises it — through a parser for the source’s syntax: the one your catalog serves for that syntax, and, for a syntax your catalog serves no parser for, the one the compiler itself carries, JSON among them. So a workspace whose catalog holds no parser imports a Langflow or Flowise flow with nothing configured. No list attaches a parser: a parser your catalog serves for a syntax is the one used, and two of different names serving one syntax are refused, as A parse or import format is advertised by more than one plugin describes.

Starting from nothing

A freshly installed aggrega has neither file, and that is a working state rather than a broken one: every setting falls back to its built-in default and commands run. What is missing is a registry to pull catalog content from, together with the trust policy that says which signatures to accept — which is exactly what aggrega config init writes.

You do not have to know that in advance. A command that reads its configuration and finds no file anywhere says so once, on standard error, and names aggrega config init as the way to create one. It is advice rather than a failure: standard output is untouched, nothing is asked of you, and the exit status is whatever the command would have reported anyway. It is written only when standard error is a terminal, so it reaches you at the keyboard and never accumulates in a pipeline’s log. Once either file exists — your project’s or the global one — it stops appearing.

To seed the global file with the official hub and the trust policy that hub advertises:

Terminal window
aggrega config init

Pass --registry <host> to seed a different one, --workspace to write the entry into this project’s file instead of the global one, and --dry-run to see the content it would write without creating anything. aggrega-config.md covers the command in full.

How a registry host is written

Each registries[].host names a registry host. So does default_registry — optionally followed by a repository path — unless it names one of those entries instead (see below). A host is written as the host itself, in the one spelling the registry’s trust policy is kept under:

  • a lowercase host name containing a dot, such as registry.example.com;
  • localhost, or a single name followed by a port, such as registry:5000;
  • an IPv4 address such as 127.0.0.1, or an IPv6 address in brackets such as [::1];

each with an optional :port, and nothing else — no scheme, no path, no credentials, no whitespace and no capital letters. A single name with no port is not a registry host, because that is the shape of the first segment of a catalog entity’s name — the core in core/web-api — and the two must never be read as each other.

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: registry.example.com
registries:
- host: registry.example.com
signing:
required: true

The spelling is part of the policy. A registries entry applies to the host its host: names, and the official hub’s built-in signature requirement applies to hub.aggrega.ai, so a host written any other way would reach the right registry and miss the policy written for it. It is refused when the configuration loads instead, and the refusal names the spelling to write: HUB.AGGREGA.AI and https://registry.example.com are refused naming hub.aggrega.ai and registry.example.com, and so is registry.example.com/charts as a registries[].host, which carries no path. Port 443 is the default port of a host reached over HTTPS, so hub.aggrega.ai:443 is refused the same way, naming hub.aggrega.ai. localhost and the other loopback addresses are reached over plain HTTP instead, where 443 is an ordinary port, so localhost:443 is accepted as written. An empty default_registry names no default registry.

default_registry may carry a repository path. Many registries keep every repository under an owner or a project — ghcr.io/<owner>, <host>/<project> on Harbor — and a default registry on one of them is written as the host followed by that path:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: ghcr.io/acme
registries:
- host: ghcr.io
signing:
required: true

The path is where things are published and fetched. Through this default, aggrega push publishes core/api-server version 1.0.0 at ghcr.io/acme/component/core/api-server:1.0.0, and a pull resolving core/api-server fetches it from the same place, so a signature attached when it was published is found there too. The path is a repository path in the OCI distribution grammar: 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 never part of how the registry is trusted. The registries entry whose policy applies, the credential aggrega login stores, the signing requirement and the trusted identities are all found by the host alone, so the entry for ghcr.io above governs ghcr.io/acme and every other path on that host, and no spelling of a path can reach past it; an entry’s host: itself carries no path. A host written in another spelling before a path is refused naming the location to write — GHCR.io/acme and https://ghcr.io/acme name ghcr.io/acme — and what follows the host when it is not a repository path is refused naming the host it follows.

default_registry may name an entry instead. Written as the name: of an entry under registries, it stands for that entry’s host:. Publishing, pulling, signature verification and every per-registry trust setting then use that host, and no content is fetched from a host spelled like the name:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: local
registries:
- name: local
host: 127.0.0.1:5000

A name is matched before a host spelling, as the --registry flag matches one, so a value that is an entry’s name: stands for that entry even where it is also spelled like a host. A name two entries carry is refused as ambiguous, naming both hosts. The entry may sit in either file — a project’s default_registry can name an entry the global file declares — because the name is read once, against the entries in force after every file and the environment have been read. A value that is neither an entry’s name nor a registry host — alone or followed by a repository path — is refused, and the refusal says either one fixes it. A name followed by a path, such as local/acme, is refused too: a name stands for its entry’s host and not for a location under it, so the refusal names the two spellings to write instead — local, or the entry’s host followed by the path, 127.0.0.1:5000/acme. Removing an entry with aggrega registry remove leaves default_registry as it is written, so a default that named the removed entry names nothing afterwards and is refused until it is rewritten.

Every layer is held to the same spelling. A value is refused in the same words whether it comes from a configuration file, from AGGREGA_DEFAULT_REGISTRY, or from the --registry flag that names the destination of one aggrega push or aggrega push-artifact. That flag names a host, and the publication it directs lands at that host with no repository path: a path belongs to default_registry. aggrega registry add and aggrega config init --registry hold the host they are given to it too; they also accept a reference in its place, and key the entry under the host the reference names. A refusal from a file names the file and the key; one from the environment names the variable. The schema states the host shape as a pattern on registries[].host and states none on default_registry, whose value may be any entry’s name — so an editor reading the schema alone does not flag a mistyped default, and the configuration load is what refuses it.

A host is judged by its spelling alone, and so is a path. Whether the name resolves, whether a registry answers there, or whether the path exists on it, is not checked when the configuration loads.

What overrides what

CLI flag > environment variable > configuration file > built-in default

A flag is the most explicit signal there is and wins outright. An environment variable overrides the committed file, which is what lets a pipeline change a setting without editing a tracked file. A variable that is unset — or set to an empty string — falls through to the layer below rather than blanking a configured value. Between the two files, your project’s file wins over the global one.

A flag wins by having been typed, not by the value it carries, and for a true-or-false setting that is the difference between a usable top layer and none. --offline turns the posture on for one run; --offline=false turns it off for one run where a committed file or an exported variable has turned it on. A layer that read the value alone could not tell “off” from “not mentioned”, so every command would look as though it had asked for the flag’s default and there would be no way to countermand a configured setting at all.

That is the whole model for a single project on a single machine. Everything below exists for projects that outgrow it.

Beyond the two files

These mechanisms are built for larger shapes — a monorepo of related projects, a pipeline that contributes settings of its own, a shared catalog that several projects extend. Reach for one when you have the problem it solves.

More than one configuration file inside a project

Every .aggrega-config.yaml from the project root down to the directory the command runs in contributes, and a nearer file overrides a farther one. So a subproject can carry its own file that adjusts what the root declared, without repeating it.

Only a file carrying a workspace: block marks a root. A file without one still contributes its settings — it simply does not turn its directory into a project root, which is what keeps a subproject’s settings file from redefining where the project begins.

Passing --workspace-root changes this as well as skipping discovery: the named root’s own configuration file is the only one collected, so files in directories below it do not contribute. That keeps a pinned root’s configuration the same wherever the command is run from.

Every file collected this way is read from inside the project. One that is a symbolic link leading out of the project — or that sits in a directory reached through such a link — is not read, and every command that reads the configuration stops on it, naming the link, rather than configuring the project from the files that remain; the same holds for a pipeline’s file, below. The few commands that never read it, such as aggrega version and aggrega help, run with a warning naming the link. The editor’s language server and an assistant’s tools read the configuration the same way, and still start over such a project so that it can be listed: their Release and entity listings answer, read with nothing configured, and name the file among the links not read, while every other request the configuration decides halts on it, naming the link. A configuration kept outside the project is read by naming it as the global file, as Naming the global file explicitly describes. See The workspace boundary.

Extending a list instead of replacing it

A list-valued setting behaves like every other setting: the nearer file’s value replaces the farther one’s. When you want to add to what an outer file declared rather than restate it, use the append companion beside it:

list settingits append companion
workspace.catalog_dirscatalog_dirs_append
plugins.governancegovernance_append
plugins.linterlinter_append
plugins.importerimporter_append
plugins.providersproviders_append

Entries under a companion are concatenated onto the resolved list at each layer instead of shadowing it, so a subproject adds a linter to whatever the root already declared:

# <project>/services/api/.aggrega-config.yaml
plugins:
linter_append:
- uri: ./lint/api-rules.wasm

Where one file sets both the base list and its companion, that file’s value is the base list followed by the appended entries.

The workspace: block is the exception to where a companion can be written. A file carrying that block marks its own directory as the project root, so a subproject’s file that wrote workspace.catalog_dirs_append would start a project of its own rather than add to the enclosing one. The catalog-directory companion composes between your global file and the project’s root file.

The plugins.cli list composes across files on its own and has no companion: a command extension declared in the global file registers its command in every project, one declared in a project registers only there, and both register together. Each entry pins one plugin: the uri it resolves and the digest of the bytes aggrega plugin add cli verified, written sha256: followed by 64 lowercase hexadecimal digits. A digest in any other spelling could never equal the digest the resolved bytes hash to, so it is refused when the file loads, naming the file and the entry.

Giving a Release its own catalog directories

A project can keep several catalog variants side by side — one per target, each holding the Recipes that render the same Components for a different provider — and build each Release against one of them. Name each Release under workspace.releases and give it its own catalog_dirs:

# <project>/.aggrega-config.yaml
workspace:
releases:
release-compose.yaml:
catalog_dirs:
- ./catalog-compose
release-helm.yaml:
catalog_dirs:
- ./catalog-helm

Each key is a Release file, written relative to the configuration file that names it. A key — like build.authoring_release — may name a Release kept outside the project, and naming it here is how a project reaches one: a link inside the project leading to it is read rather than passed over, as The workspace boundary describes. The two keys under it mean what they mean on the workspace: block, scoped to that one Release:

  • catalog_dirs replaces the workspace’s list for that Release. The search order, the catalog directory read after it, and what an empty list says are the same as for the workspace’s own list.
  • catalog_dirs_append is read after the Release’s list. An entry that writes only catalog_dirs_append keeps the workspace’s list and adds to it.

A Release the map does not name reads the workspace’s own workspace.catalog_dirs. A Release the map does name reads its own directories however it is built — aggrega build or aggrega pull at a terminal, the editor through aggrega serve, an assistant through aggrega mcp — so none of them needs a flag to find its catalog. A --catalog <dir> on the command line is still searched ahead of the Release’s directories, for that one invocation. And a lookup that finds no entity under a name you used names that Release’s entry as the place to list the directory holding it.

An entry naming a file that does not exist is refused when the configuration loads, naming the entry and the file. Renaming a Release therefore stops every command until the entry is renamed with it, rather than letting the Release build against the workspace’s list with nothing to say so. A directory an entry lists must be a directory, as one the workspace’s list names must be: one that is not is refused by every command reading that Release’s catalog, naming the entry and its line.

What concerns no single Release still reads the workspace’s list: a lint or a validation of the whole catalog, a lookup of an entity by name, an Aggregate inspected on its own, and an editor’s listing of the workspace’s entities. AGGREGA_CATALOG_DIRS sets the workspace’s list and reaches no entry here, and a configuration file your pipeline owns does not read the map at all.

A configuration file your pipeline owns

A file named .aggrega-config-append-ci.yaml may sit beside the hand-authored file in any directory the walk visits. It is a separate file so an automated pipeline can own and overwrite it wholesale without ever touching what a person wrote.

It is additive only. Its entries for the five list settings above are concatenated onto the resolved lists; it cannot remove anything or override a scalar. A scalar or map key written in it has no additive meaning, so it is ignored and named in a warning rather than quietly applied. It never marks a project root either, so dropping one into a directory adds attachments without moving where the project begins.

Where a relative path points

A relative filesystem path is resolved against the directory of the file that declared it — not against the project root, and not against the directory you ran the command from. This is the rule worth reading twice, because a path that looks project-relative resolves elsewhere and the build still succeeds, against content you did not intend.

It applies to workspace.catalog_dirs, to the Release files keyed under workspace.releases and the directories each entry lists, to the local filesystem paths on a plugins.governance or plugins.linter attachment — a uri naming a .wasm file on disk, and each entry under that attachment’s with.sources — and to each entry under a plugins.importer attachment’s with.sources. On all three lists a uri with no colon that names no registry — importer/agent-flows as much as ./lint/api-rules.wasm — is such a path, while a uri naming a plugin by its identity carries the version after a colon, importer/agent-flows:1.2.0, and is left exactly as written. An importer attachment’s uri names the importer it attaches, as Which importer turns a source into drafts describes; an import reads no module from a path written there. The rule applies to the entries under the append companions too, and each of those anchors to its own declaring file rather than to the file the merge happens to end at. And it applies to mcp.tls.cert_file, mcp.tls.key_file and mcp.authorization.jwks_file, so a file beside the one naming it is found wherever the server is launched.

So given this layout:

myproject/
├── .aggrega-config.yaml
└── services/
├── .aggrega-config.yaml
└── catalog/

and ./catalog written in the root file, the path names myproject/catalog. Written in services/.aggrega-config.yaml, the identical text names myproject/services/catalog. An absolute path is left exactly as written, and so is a registry reference such as oci://hub.aggrega.ai/plugins/helm:1.0.0.

These settings deliberately do not follow this rule, because they have no declaring file to anchor to or because every reader of them resolves them elsewhere:

  • artifact_cache_dir is interpreted relative to the project root, wherever the command runs from, so the cache is one directory rather than one per invocation location. An absolute value is refused when the configuration loads.
  • AGGREGA_CATALOG_DIRS comes from the environment and has no declaring file at all, so supply absolute paths in it.
  • mcp.listen is taken exactly as written, and that includes the filesystem path in its unix:<path> form. The same address also arrives from aggrega mcp --listen, which has no declaring file, so anchoring the configured spelling alone would make one string name two different places depending on where it came from. Give the socket an absolute path.

One setting whose store is shared

Almost every setting governs something that belongs to the project you are working in — which directories it resolves catalog content through, which plugins render its targets, how strictly its content is judged, how large the daemon’s in-memory caches may grow. A value in a project’s file governs that project’s own thing, and there is nothing to watch for.

compiled_module_cache.max_bytes is the one exception, because what it caps is not per-project. Compiled plugin code is kept in a single directory that every project on your machine reuses, so a given plugin is compiled once rather than once per project. The cap itself resolves like any other setting — write it in a project’s file and that value wins for that project — but the store still has only one size, and the size in force is the one from the most recent build. Two projects that cap it differently both take effect in turn, and the lower cap discards compiled code the other project paid for.

So put it in the global file when you want one answer for everything you build, and keep it above what a single build compiles. aggrega cache status reports what the store currently holds, and aggrega config show --origin tells you which file the cap you are running under actually came from.

Settings for a server other people reach

aggrega mcp speaks the Model Context Protocol. On your own machine a client launches it as a subprocess and talks to it over standard input and output, which is the default, and the only settings that shape reads are mcp.transport, left at that default, and mcp.announce_tools. The rest of the mcp block is for the other shape, which mcp.transport: http chooses: one long-running process on a host, reached over HTTP by callers who are not at its keyboard.

# <project>/.aggrega-config.yaml
mcp:
transport: http
listen: 127.0.0.1:7777
authorization:
issuer: https://login.example.com
resource: https://mcp.example.com/mcp
allowed_origins:
- https://studio.example.com
limits:
max_concurrent_requests: 32
deny_reach:
- registry
announce_tools:
- list-entities
- get-schema
- validate
- build
health:
listen: 127.0.0.1:7778

mcp.transport is what chooses the transport. http starts a listener; stdio, the default, speaks over standard input and output, which is what a subprocess client expects. Any other value is refused when this file loads. aggrega mcp --transport <stdio|http> does the same for one invocation and wins over the key, the way every flag wins over every file.

mcp.listen names where that listener binds, and chooses nothing. Give it a host:port address or a unix:<path> socket; aggrega mcp --listen <address> wins over it for one invocation. With http chosen and no address from either, the launch is refused before anything binds. With stdio chosen, a typed --listen is refused, and an address only this key names is left unused — the server says so in one line on its error stream, naming this file and mcp.transport: http. So a server other people reach sets both keys, as above, and a client launched from a directory that file covers still reaches the server over its own streams. A unix: path is taken as written rather than anchored — see Where a relative path points.

mcp.tls.cert_file and mcp.tls.key_file put TLS in the process. Set both and the listener serves HTTPS itself. Leave both out and it serves plaintext, which is accepted only on loopback or on a Unix socket — the shape you use when a proxy in front holds the certificate and forwards to the process. A plaintext listener on any other address is refused before anything binds, naming these two keys, and so is one of the two set without the other. Both are filesystem paths and follow the rule above: a relative one resolves against the directory of the file that declared it, so a certificate committed beside that file is found wherever the server is launched from. Write them absolute where the certificate is managed outside the project.

mcp.authorization.issuer and mcp.authorization.resource say who issues the tokens callers present, and what this server is called as the resource they are issued for. Both are required whenever the http transport is chosen, and a listener is refused before anything binds without them, because every request to the endpoint is answered with a bearer-token challenge and a challenge that names nowhere to go is one a client cannot act on. Write whole addresses, scheme and host included: the issuer exactly as that authorization server states its own identifier, and the resource as the address your callers actually reach — the host a proxy in front presents, where there is one, rather than the address this process binds. Both are published, with no credential asked for, in the OAuth protected-resource metadata document the listener serves, which is where a client looks to find out where to obtain a token. Neither holds anything secret: a token arrives on the request that presents it and is never written in a configuration file. The issuer is an https address unless the authorization server runs on this machine — localhost, 127.0.0.1 or ::1 — and a listener naming a plain http issuer on any other host is refused before anything binds, whichever way it reads its keys and its callers: every client is sent to the issuer to obtain its token, so over plain http its authorization code and its token would cross the network unprotected, and where the keys are read from there too, whoever sits on that path could substitute them.

mcp.authorization.jwks_file names a file holding the keys tokens are verified against, instead of reading them from the authorization server. Leave it out and the server reads that server’s metadata at its well-known address and follows the jwks_uri published there, which is what a workspace with network access does. That key address is held to the same rule as the issuer, and so is any address either read is redirected to: one that is plain http on another host is never asked, and a token needing those keys is answered 503 until the authorization server publishes its metadata and keys over https. Set it and the authorization server is never contacted — which is what a workspace declaring offline: true needs, and such a workspace is refused before its listener binds unless this names a file. It is a path and follows the rule above: a relative one resolves against the directory of the file that declared it, so a key set committed beside that file is found wherever the server is launched from. The file holds public verification keys, which are what an authorization server publishes — nothing that signs, and nothing secret.

mcp.allowed_origins is consulted only when a request carries an Origin header, which in practice means a browser sent it. List the origins you serve there; a request naming one that is not listed is refused, and a request carrying no such header is served regardless. A client that is not a browser sends no such header and needs no entry. An entry is compared to the header exactly, so write it the way a browser sends it: a lowercase scheme, ://, a lowercase host, and : with the port only where the port is not the scheme’s default — https://studio.example.com, or http://localhost:3000 for a page served on your own machine — with no path and no trailing /. An entry in any other shape could never match, and is refused when this file loads, naming the entry.

mcp.limits bounds what one caller can ask for — how large a single request body may be, how many requests run at once, and how many one caller may send in a minute. All three are always in force; none has a value that lifts it. The third, requests_per_minute, is counted against each caller separately, so one caller sending hard costs another nothing.

mcp.authorization.trusted_proxy reads the caller from a proxy in front instead of checking a token here. Set principal_header to the header that proxy uses to say who the caller is, and optionally scopes_header to one carrying that caller’s scopes. Both are HTTP header names, such as X-Forwarded-User — letters, digits, hyphens and the few other characters a header name may carry, with no space or colon — and a name in any other shape is refused when this file loads, naming the key, because no request could carry it. In that mode no token is read at all, and a request without the principal header is refused. Because the header is then the whole credential, it is trustworthy only where nothing else can set it: the process is refused before it binds unless mcp.listen is loopback or a Unix socket. Leave the block out and this server checks tokens itself, which is the default; a block whose principal_header is empty is refused rather than read as that default.

mcp.deny_reach withdraws a kind of reach from this deployment. Every operation the server performs 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. Naming a kind here withdraws every tool that reaches it: the tool is absent from every caller’s tool list whatever that caller’s token carries, and a call to it is refused naming this setting. That makes it the deployment’s bound rather than the caller’s, and no credential lifts it — a server meant to serve reads and nothing else lists the three writing kinds here and then cannot publish even for a caller whose token carries every scope. Leave it out, which is the default, and this deployment carries whatever its callers’ scopes admit. A value that is not one of the four is refused when this file loads, rather than passed over. Nothing of the machine kind is offered over HTTP whatever this says, so naming it is accepted and changes nothing; aggrega-mcp.md sets out the kinds and the scopes that admit them.

mcp.announce_tools narrows what the server announces, and it is a different bound from the key above. Name the tools this server announces, spelled as the tool list reports them, and exactly those are announced: one left out is absent from every caller’s tool list and refused if it is called by name anyway, naming this setting. Leave the key out — the default — and every tool the server carries is announced; write an empty list and none is, so those two spellings are different statements and no default is filled in for you. What separates it from deny_reach is what each one takes away. deny_reach takes away a capability: the operations of a withdrawn kind are not carried here at all and no credential brings one back. announce_tools takes away only an announcement — the tools it leaves out are capabilities the server still has — and what it answers is a client that caps how many tools it will register, sometimes across every server it is connected to at once. Where both are set the withdrawal wins, so a tool of a withdrawn kind stays absent however this key names it. A name no tool answers to stops the server before it serves anything, listing the tools it does have, rather than leaving you with a surface narrower than the one you asked for. Unlike the other keys here, which configure the listener the http transport starts, it is read whichever transport the server speaks, because the client a narrowing exists for is usually the one that launched the process over its own standard input and output; aggrega-mcp.md sets out the rest.

mcp.health.listen puts the liveness and readiness checks on an address of their own. Give it an address in either of mcp.listen’s two forms and a second listener answers GET /healthz there — 200 from the moment the process is running — and GET /readyz — 503 until the workspace has resolved and the endpoint has bound, 200 from then on, which is what lets a balancer hold traffic back until the process can actually answer a call. Leave it out and neither check is answered anywhere. They are never answered on the address mcp.listen names, which gives them the 404 it gives every path it does not serve: a probe there would be an unauthenticated reading of a listener that refuses everything else. Unlike mcp.listen this address is not confined and no address is refused for it — point it at loopback or a Unix socket, which is what a supervisor beside this process reaches, and note that whatever can reach the address you pick can read those two answers.

schema/other/aggrega-config.md states each of these keys alongside its default, where it has one.

The other ways a project root is recognised

--workspace-root <path>, or its AGGREGA_WORKSPACE_ROOT counterpart, names the root outright and skips discovery. The folder it names must exist: a path that names nothing, or names a file, is refused before the command does anything else, and the refusal names whichever of the two supplied the value and quotes it as it was given. Otherwise discovery walks upward from the working directory, and the kinds of anchor rank against each other rather than by nearness:

  • A .aggrega-config.yaml carrying a workspace: block wins outright, at whatever depth it sits. The walk keeps climbing to look for one even after it has passed a marker of the kind below, so an explicitly marked root above always beats an incidental marker below it.
  • Failing that, the nearest of these markers anchors the root, and within one directory they rank in this order: an .aggrega/ directory, then an aggregate*.yaml, then a release*.yaml, then a manifest*.yaml.
  • Failing everything, the working directory is used — commands run rather than refusing to start. A command whose result depends on the workspace — one that reads or writes the workspace’s documents, reads or fills its artifact cache, or serves it — warns once on standard error: warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. A command whose result does not depend on which folder is the root says nothing, even where it reads the configuration: aggrega version, aggrega config show, aggrega plugin list, aggrega registry list, aggrega explain and aggrega login among them. aggrega config capture, whose work is writing the workspace’s own configuration file, writes nothing in such a folder and exits with an error saying so.

Nothing is written into an artifact cache in such a folder. An .aggrega/ directory is itself one of the markers above, so a cache written there would make the folder a workspace because something was once fetched in it. A command whose work fills the cache — aggrega pull, a build that resolves its dependencies first, aggrega registry update, adding a command-extension plugin from a registry — is refused before it fetches anything, naming the folder and the two ways out: name the workspace with --workspace-root or AGGREGA_WORKSPACE_ROOT, or give the folder a .aggrega-config.yaml carrying a workspace: block. aggrega pin, and aggrega push of a Recipe or FeatureRecipe, which is held to the pins the entity.lock beside it records, fill the cache only with the remote sources the entity writes out in full, which pinning one or comparing its pin fetches: they are refused the same way where they would fetch such a source, before they fetch it. An entity with no such source — no source at all, a local one, or one whose coordinates each Release fills in — is pinned or published there as anywhere else. A build there is not refused, but an external input its lockfile pins and the cache no longer holds is not fetched again to repair it: the render is told the same sentence in place of that input, the way it is told the offline posture’s, and reports it. Where artifact_cache_dir puts the cache changes nothing here, because the directory is joined to whichever root was found. Commands that only read still answer.

That last fallback has one exception. When nothing named the root and the working directory anchors nothing, a command about one Release or one entity document that names that file by an absolute path discovers the root again, walking upward from the folder the file sits in, and uses whatever it finds: the workspace the file belongs to, or, failing everything, that folder. The file is the one --release names on aggrega build and aggrega pull; the Release aggrega validate, aggrega lint and aggrega inspect are given, or else the file they are given; and the document aggrega pin, aggrega push and aggrega edit-document are given. So a project’s Release built from outside the project reads the project’s own configuration, as it does when the command runs inside it, and the configuration warnings the command prints are that workspace’s. Where the file’s own folder anchors nothing either, that folder is the one the command’s notice names and the one no cache is written in. A relative path is read against the directory you run the command in and changes nothing, and a named root, or a working directory that is itself inside a workspace, is used as it is. The assistant server applies the same rule to a call that names its Release or document by an absolute path.

Marking the root with a workspace: block is the explicit choice and the one to prefer; the file and directory markers let a project that has not declared one still be built.

Naming the global file explicitly

The global layer resolves in this order:

  1. --config <path>, the per-invocation form.
  2. The AGGREGA_CONFIG environment variable.
  3. The default location: on Windows aggrega\config.yaml inside the directory the APPDATA environment variable names, and elsewhere aggrega/config.yaml inside the directory XDG_CONFIG_HOME names, falling back to ~/.config/aggrega/config.yaml.

The first two name an explicit file, so a path that does not exist is a loud error rather than a silent fallback — you asked for a particular file. A command that reads its configuration stops with one sentence that ends with the path, so you can copy it. aggrega config init is the exception, because creating that file is what it is for: it creates the named file and says so. The default location is loaded when the file is there and passes over quietly when it is not. Whichever file resolves, your project’s files still layer on top of it.

When none of these resolves — no file is named, and the variables the default location is read from are not set — a command that writes the global file stops and names what to set. Environment variables lists, per platform, the variables each location is read from.

That choice also selects where a configuration-writing command writes. A command run with --config <path> reads its configuration from that file and applies its change to that same file, so what one command writes is what the next one reads back.

Which of the two files a command writes to by default comes from the nature of the setting: machine-wide tooling such as a registry goes to the global file, while build-participating settings such as a provider binding or a socket attachment go to the project’s committed file, so they travel with the project. Pass --global or --workspace to override, and the command prints the file it wrote.

See also