# Config settings (https://docs.neuralisapp.com/package-system/config-settings)

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.

```json
"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 [#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 [#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 [#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](https://docs.neuralisapp.com/admin/config-settings.md).
- **Never a secret.** Config values are admin-visible plaintext. Anything
  secret-shaped belongs in [credentials](https://docs.neuralisapp.com/package-system/credentials.md); 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](https://docs.neuralisapp.com/agent-core/config-settings.md) and
[brain-core](https://docs.neuralisapp.com/brain-core/config-settings.md).
