@package-system

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 whose default falls outside them, or whose min exceeds its max, is rejected at load; an admin's save is checked against them too.
  • editable: false shows 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 ignore envFallback.

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.config feature, 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 envFallback names.

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.

On this page