Configuration

Configuration follows one discipline: the instance should be governable from the admin UI at runtime, with as little reason to touch a server as possible. Neuralis configuration is split into four tiers with a clear ownership rule: .env holds only what the process needs to boot, the platform config store holds runtime settings an admin edits from the UI, long-lived secrets live exclusively in the encrypted credential store, and the Docker topology lives in a setup-generated docker-compose.yml (see deployment). For runtime values the precedence is: stored platform value, then environment fallback, then the built-in default.

Tier 1: .env — boot-critical onlyCopy Anchor Link

The environment file is written by pnpm neuralis:setup and read at process start. It contains nothing a user would reasonably edit at runtime; changing it requires a restart. The important variables:

Tier 2: platform config storeCopy Anchor Link

Runtime platform settings live in a single JSON file in the platform zone (~/.neuralis/app/config/platform.json) behind a schema-validated store, and are edited from the admin widget's Config tab. Every key has a type, a default, and an editable flag; read-only keys surface in the UI as informational rows. Examples of what lives here:

• the target embedding model id and vector dimension (the model the vectors are actually built with stays the active one until an owner rebuilds — see memory and sync),
• custom LLM endpoints (your own hardware, or a keyed remote gateway) (Ollama-native or OpenAI-compatible),
• custom embedding endpoints — any OpenAI-compatible /v1/embeddings server, edited in the admin Vector section; like the LLM endpoints, their keys live in the credential store, never in this file,
• how many data checkpoints to keep (dataCheckpointKeep, see deployment),
• runtime knobs such as the per-stream agent step cap and default temperature,
• the chat composer clipboard caps — the maximum size of a pasted/dropped image and of pasted text (client-side paste guards only; they do not affect how much data a tool like fs_read returns),
• platform limits such as the maximum number of projects.

Every key is declared by the package that consumes it (the manifest configSettings[] array — the host hardcodes no schema of its own), and the Config tab shows each key's declaring package, whether its current value comes from the default, an environment fallback, or an admin-set override, and any number bounds. The list can be filtered by that declaring package — one entry per package that declares keys, plus the host's own settings and the read-only environment rows. Only first-party packages can contribute keys: the host honors 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. Boot-critical environment values (ports, auth URLs, the vector database endpoint) appear in the same list as read-only rows served from an explicit host allowlist — secret values are never listed. Where a boot-critical variable is itself a secret, only its presence is reported: the vector database API key renders as (set) or (unset), never as the key.

Edits are validated against the declared schema (type + bounds), written atomically, and most take effect at runtime — no restart; keys that apply on restart or at client rebuild say so in their description. Many keys keep an environment fallback for first boot, but once a value is stored the stored value wins.

Tier 3: credential storeCopy Anchor Link

Anything secret — provider API keys, OAuth tokens, MCP API keys, skill-declared and custom secrets — belongs in the encrypted credential store, never in .env or platform config. The store is scope-aware (platform, user, project, agent) and managed from the admin Credentials tab. The full model is on the credentials page.

Model provider setupCopy Anchor Link

LLM provider keys are credentials, not environment variables:

1. During first-run setup, the wizard asks for provider keys interactively and writes them straight into the encrypted store. The runtime reads provider keys from the store only — there is no environment fallback, and the compose file carries no key entries (anything in a container's environment is readable via docker inspect).
2. After that, manage keys from the admin Credentials tab. A key set at any scope is honored at stream time through most-specific-wins resolution (agent → project → user → global), so a project can carry its own provider key that overrides the platform default.
3. Custom endpoints carry their own authentication: register an Ollama or OpenAI-compatible server in the admin Credentials tab and say whether it needs a key. One on your own hardware usually does not, and its models appear in the selector alongside the hosted providers. One that DOES — a remote gateway, say — stores its key like any other credential, resolved with the same scope cascade, and its models are offered only to callers for whom that key resolves. A row nobody has a key for is greyed out rather than failing mid-conversation, and the endpoints beside it are unaffected.

ChatGPT/Codex OAuth sign-in is the one special case: there is no key to paste, so it is connected through a sign-in flow from the Credentials tab (or a member's own Connect button in chat). The resulting login is stored like any other credential, at agent, project, user or global scope, and resolves through the same cascade. See providers and models for the provider catalog itself.

Tier 4: the generated docker-compose.ymlCopy Anchor Link

Docker deployments have one more setup-owned artifact: the compose file itself. pnpm neuralis:setup generates it next to .env with concrete machine-specific values (user/group IDs, ports, the Qdrant service or a direct QDRANT_URL depending on the chosen mode, an optional local Ollama service); pnpm neuralis:setup --compose-only regenerates it without re-asking anything. It is never hand-edited, and it never carries secrets — the single .env interpolation is NEXTAUTH_SECRET. Machine-local extra mounts live in a separate docker-compose.override.yml that survives regeneration. Details on the deployment page.

Logs: two planes, and the keys that level themCopy Anchor Link

Neuralis writes logs to two places that are easy to confuse, and one level key (logLevel) behaves differently from all the others.

• packageLogLevel (default info) governs every package's own file log. packageLogLevelOverrides sets exceptions per package as <package>=<level> pairs (brain-core=debug,agent-core=warn), keyed on the pkg field of the log line; a malformed pair is ignored and that package follows the global.
• routeLogLevel (default warn) governs the route log — one structured line per package-route dispatch: matched pattern, method, status, duration, caller, and which gate refused a call. It defaults to warn because several App surfaces poll every few seconds, so at info a single open shell tab writes tens of thousands of lines a day and the file rotates away within hours. Raise it for a debugging window, then put it back. At warn the file holds refusals, faults and every dispatch slower than routeSlowMs (default 1000 ms, marked slow: true whatever its status). The same lines are also written to container stdout through their own gate, routeConsoleLogLevel: empty (the default) follows routeLogLevel, so docker logs shows the same refusals, faults and slow requests; set it to warn with routeLogLevel=info to keep every request in the file and only the problems on stdout.
• logLevel governs only container stdout. It changes nothing on disk.
• The process monitor writes one perf.slow warning to container stdout when, over a sample window (perfSampleIntervalMs, default 30 s, applies on restart), the Neuralis process's CPU exceeds perfProcessCpuWarnPercent (default 80; 100 = one core, the Neuralis process only — not the container) or its longest single event-loop stall reaches perfEventLoopLagWarnMs (default 200 ms). Below the thresholds it writes nothing.

Because the file levels apply live, the working loop is: raise the level, reproduce the problem, read, put it back. Raising a level never recovers lines that were not written at the time.

Retention is what the rotation keys buy, not a time promise. Each plane has its OWN trio so neither is rotated on a budget set for the other: routeLogMaxBytes x routeLogMaxFiles x routeLogMaxAgeDays (25 MB x 5 x 90 days) for the route log, and packageLogMaxBytes / MaxFiles / MaxAgeDays for package logs. The audit log is the exception: auditLogMaxBytes (25 MB) only decides when audit.jsonl is renamed to a new generation — no generation is ever deleted.

What is hot and what needs a restartCopy Anchor Link

The configuration UI and the routes behind it are feature-gated (platform.config — a platform-tier feature with no default role grant); see administration for who can edit what.