Configuration Schema

Nous uses JSON5 for configuration. The config file is validated at load time with Zod schemas.

Location: {dataDir}/config.json5 (or path from NOUS_CONFIG_PATH)

Top-Level Sections

Profile

{
  "profile": {
    "name": "hybrid_controlled",  // see Profile names below
    "description": "Local preferred with explicit remote fallback",
    "defaultProviderType": "local",
    "allowLocalProviders": true,
    "allowRemoteProviders": true,
    "allowSilentLocalToRemoteFailover": false
  }
}

Profile names (Phase 2.3):

Legacy names are normalized at runtime. allowSilentLocalToRemoteFailover — when false (default), remote is allowed only as explicit fallback in hybrid_controlled.

When Anthropic or OpenAI credentials are restored at startup and the active profile is local-only or local_strict, Nous promotes the runtime into a hybrid-compatible profile so remote providers can actually be routed. Removing the last cloud provider returns the runtime to local-only posture.

Cortex Tier

pfcTier is a number 0–5. Higher tiers enable more capabilities (reflection, memory gating, tool authorization, planning, escalation detection). See Cortex Mode Capability Matrix.

Model Role Assignments

{
  "modelRoleAssignments": [
    {
      "role": "reasoner",
      "providerId": "550e8400-e29b-41d4-a716-446655440002",
      "fallbackProviderId": "550e8400-e29b-41d4-a716-446655440001"
    }
  ]
}

providerId and optional fallbackProviderId must be valid UUIDs matching provider id values in the providers array. Roles: orchestrator, reasoner, tool-advisor, summarizer, embedder, reranker, vision.

Saved Principal and System model selections are restored into this structure at startup. When both saved selections are available, Nous uses the primary selection as providerId and the secondary selection as fallbackProviderId for the active reasoner assignment.

Providers

{
  "providers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Ollama",
      "type": "text",
      "modelId": "llama3.2:3b",
      "isLocal": true,
      "capabilities": ["chat", "streaming"],
      "providerClass": "local_text",
      "vendor": "ollama",
      "meetsProfiles": ["review-standard", "prompt-generation"]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "openai",
      "type": "text",
      "endpoint": "https://api.openai.com",
      "modelId": "gpt-4o",
      "isLocal": false,
      "capabilities": ["chat", "streaming"],
      "providerClass": "remote_text",
      "vendor": "openai",
      "meetsProfiles": ["review-standard", "review-implementation"]
    }
  ]
}

• providerClass (optional): local_text | remote_text — used for credential segregation and profile boundary.
• vendor (optional): Provider vendor key for adapter selection. Known values: anthropic, openai, ollama, text. Auto-detected from provider configuration if omitted. Unknown values fall back to the text adapter.
• meetsProfiles (optional): Array of capability profiles (e.g. review-standard, review-implementation). Router enforces that the selected provider meets the required profile unless Principal override evidence is present.
• endpoint (optional): Use the provider base URL (for example https://api.openai.com or https://api.anthropic.com), not the full /v1/chat/completions path.

Provider types: text, image, video, vision, embedding, external-api.

Storage

{
  "storage": {
    "dataDir": "/path/to/data",
    "documentBackend": "sqlite",
    "vectorBackend": "stub",
    "graphBackend": "stub",
    "storageEncryption": false
  }
}

• storageEncryption — When true, user is responsible for filesystem-level encryption (LUKS, BitLocker, FileVault). Phase 1: option validated; runbook in Security Baseline.

Security

{
  "security": {
    "traceSensitiveData": false
  }
}

• traceSensitiveData — When false (default), user input, model output, and memory candidate content are redacted from traces. Structure (traceId, projectId, Cortex decisions) is preserved.

Defaults

{
  "defaults": {
    "projectType": "hybrid",
    "governance": "should",
    "memoryAccessPolicy": {
      "canReadFrom": "all",
      "canBeReadBy": "all",
      "inheritsGlobal": true
    },
    "retrievalBudgetTokens": 500,
    "stmCompactionPolicy": {
      "maxContextTokens": 1024,
      "targetContextTokens": 640,
      "minEntriesBeforeCompaction": 8,
      "retainedRecentEntries": 4
    },
    "escalationChannels": ["in-app"]
  }
}

These apply to newly created projects.

• retrievalBudgetTokens — Default token budget for retrieval result assembly in new projects.
• stmCompactionPolicy — Default short-term-memory pressure policy for new projects.
  • maxContextTokens — Threshold where STM should compact.
  • targetContextTokens — Post-compaction token budget.
  • minEntriesBeforeCompaction — Minimum recent turns required before compaction is allowed.
  • retainedRecentEntries — Number of newest turns kept verbatim when older context is summarized.

targetContextTokens must be lower than maxContextTokens, and retainedRecentEntries must be lower than minEntriesBeforeCompaction.

Environment Variables

When OPENAI_API_KEY or ANTHROPIC_API_KEY is present at startup, Nous registers the matching remote provider, updates available cloud models, restores saved model selections against stable provider IDs, and enables hybrid-compatible routing. These variables can be supplied directly or populated from stored vault credentials during bootstrap.

Phase 13.5 config audit result: public MCP deployment routing adds two operator-facing seed variables for hosted and local-tunnel routing. NOUS_PUBLIC_BASE_URL remains the public MCP edge override for OAuth metadata and discovery URLs.

NOUS_PUBLIC_MCP_HOSTED_BINDINGS_JSON

Use this variable to seed hosted tenant routing records during web bootstrap. Each record must match the hosted-binding schema used by the public gateway:

[
  {
    "bindingId": "binding-1",
    "tenantId": "tenant-1",
    "userHandle": "andre",
    "host": "andre.nous.run",
    "storePrefix": "tenant-andre",
    "serverName": "Andre Hosted Nous",
    "phase": "phase-13.5",
    "status": "active",
    "createdAt": "2026-03-14T00:00:00.000Z",
    "updatedAt": "2026-03-14T00:00:00.000Z"
  }
]

• bindingId — stable binding record identifier
• tenantId — tenant-scoped runtime identity
• userHandle — public handle used for hosted routing
• host — public host that resolves to the hosted tenant runtime
• storePrefix — tenant-local storage prefix used for document/vector/task/audit isolation
• serverName — public-safe ortho.system.v1.info server name override
• phase — public-safe phase label surfaced in ortho.system.v1.info
• status — current binding state (active or disabled)

NOUS_PUBLIC_MCP_TUNNEL_SESSIONS_JSON

Use this variable to seed local-tunnel routing records during web bootstrap. Each record must match the tunnel-session schema used by the public gateway:

[
  {
    "sessionId": "session-1",
    "userHandle": "casey",
    "host": "casey.tunnel.nous.run",
    "sharedSecret": "0123456789abcdef0123456789abcdef",
    "status": "active",
    "createdAt": "2026-03-14T00:00:00.000Z",
    "updatedAt": "2026-03-14T00:00:00.000Z"
  }
]

• sessionId — stable tunnel session identifier
• userHandle — public handle associated with the tunnel session
• host — public host that resolves to the tunnel backend
• sharedSecret — shared secret used to validate edge-issued tunnel envelopes
• status — current session state (active or disabled)

These variables affect deployment routing only. They do not change the public MCP tool catalog, OAuth posture, or JSON-RPC request and response shapes seen by external clients.