Config settings
configSettings[] — the platform tunables a native package owns, how each key resolves, and where an admin edits it.
A package declares the platform-level tunables it OWNS in configSettings[].
Each entry registers a schema row in the platform config store and surfaces on
the admin Config → Platform Settings tab, grouped by category with the
declaring package shown. The host hardcodes no config schema of its own: every
key an admin can adjust is declared by the package that consumes it.
"configSettings": [
{
"key": "maxAgentSteps",
"label": "Max Agent Steps",
"description": "Maximum steps per agent stream run",
"type": "number",
"default": 2000,
"min": 1,
"max": 10000,
"envFallback": "MAX_AGENT_STEPS",
"category": "runtime"
},
{ "key": "searchDebug", "label": "Search Debug", "type": "boolean", "default": false, "category": "debug" }
]The shape
{ key, label, description?, type, default, envFallback?, editable?, category, min?, max? }, where type is exactly one of number, string, boolean or
json.
- Keys are flat camelCase (
^[a-z][a-zA-Z0-9]{0,63}$) in one shared namespace. A key has exactly ONE owning declarer; a collision with another package's key is rejected at load. - Bounds. Number keys may carry inclusive
min/max. A manifest whosedefaultfalls outside them, or whoseminexceeds itsmax, is rejected at load; an admin's save is checked against them too. editable: falseshows the key read-only on the Config tab; omitted, the key is editable.type: "json"keys are edited by dedicated UIs, never the flat settings list, and ignoreenvFallback.
How a value resolves
Each key resolves through a three-step cascade: the admin-set value in the
platform config store, else the optional envFallback environment variable,
else the declared default. Once an admin stores a value, the stored value wins
over the environment. Most edits take effect on the next read, with no
restart; a key that applies on restart (or at a client rebuild) says so in its
own description.
The store is one schema-validated file in the platform zone, and an edit is validated against the declared type and bounds and written atomically. The Config tab shows, for every key, its declaring package, whether the current value comes from the default, an environment fallback or an admin override, and any number bounds. Boot-critical environment values (ports, auth URLs, the vector database endpoint) appear in the same list as read-only rows from an explicit host allowlist; where one is itself a secret, only its presence is shown, never the value.
Who may declare and edit
- Native packages only. The host honours a
configSettings[]declaration from a package it trusts by source — one of its own dependencies, whatever the npm scope — and skips one from a project-dropped or synced package, because an environment fallback would otherwise project an environment variable's value into the dashboard. - Declaration is not a grant. A row only makes the key adjustable on the
admin Config surface; reading and changing values stays behind the
platform.configfeature, which carries no default role grant (an owner holds it through the'*'wildcard). See admin config settings. - Never a secret. Config values are admin-visible plaintext. Anything
secret-shaped belongs in credentials; the
validator warns on secret-looking keys and
envFallbacknames.
Every tunable a package reads is a declared key with a generous default, never a hardcoded constant. The keys the shipped packages declare are listed on each package's own config-settings page, for example agent-core and brain-core.