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.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueThe 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.
registries: - host: hub.aggrega.ai signing: required: trueaggrega 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 invalidCreate 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.yamlworkspace: 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.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueEach 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.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmA 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
hlemforhelmtakes. - 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.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega 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
urinames, however many other importers in the catalog advertise the format too, and it is handed the entry’swith.sourcesandwith.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
withis 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:
aggrega config initPass --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 asregistry: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.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueThe 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.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: trueThe 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.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000A 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 defaultA 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 setting | its append companion |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_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.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmWhere 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.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmEach 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_dirsreplaces the workspace’s list for that Release. The search order, thecatalogdirectory read after it, and what an empty list says are the same as for the workspace’s own list.catalog_dirs_appendis read after the Release’s list. An entry that writes onlycatalog_dirs_appendkeeps 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_diris 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_DIRScomes from the environment and has no declaring file at all, so supply absolute paths in it.mcp.listenis taken exactly as written, and that includes the filesystem path in itsunix:<path>form. The same address also arrives fromaggrega 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.yamlmcp: 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:7778mcp.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.yamlcarrying aworkspace: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 anaggregate*.yaml, then arelease*.yaml, then amanifest*.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 explainandaggrega loginamong 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:
--config <path>, the per-invocation form.- The
AGGREGA_CONFIGenvironment variable. - The default location: on Windows
aggrega\config.yamlinside the directory theAPPDATAenvironment variable names, and elsewhereaggrega/config.yamlinside the directoryXDG_CONFIG_HOMEnames, 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
- aggrega-config.md — the
aggrega configcommands that seed, inspect, and freeze configuration. - environment-variables.md — every
AGGREGA_-prefixed variable, and where secrets are supplied. - global-flags.md —
--config,--workspace-root, and the other flags every subcommand accepts. - schema/other/aggrega-config.md — every configuration key, its type, and its default.
- aggrega-cache.md — what
artifact_cache_diractually holds. - workspace-boundary.md — which paths stay inside the workspace, and how the directories and files this configuration names reach outside it.
- aggrega-mcp.md — the server the
mcpblock configures.