Configuration

Configure nexus-agents with YAML files, environment variables, and programmatic options.

Configuration Precedence

The loader selects one config file — the first match wins, it does NOT merge multiple files:

1. NEXUS_CONFIG_PATH (explicit path), else
2. Project config — ./.nexus-agents/nexus-agents.yaml or ./nexus-agents.yaml (current directory), else
3. User config — ~/.nexus-agents/nexus-agents.yaml

Whatever single file is selected is layered over the built-in defaults. Then environment variables (NEXUS_*) overlay the result per-setting at consumption time — so an env var overrides just that one key, and env vars (not a second config file) are the right tool for machine-local overrides. See Configuration for Reusable Pipelines for the project-vs-local split.

Quick Setup

Generate a starter configuration file:

nexus-agents config init

This creates nexus-agents.yaml with sensible defaults.

Configuration File

The main configuration file is nexus-agents.yaml:

Note: Model IDs below come from the in-tree ModelRegistry — they are what nexus-agents recognises out of the box. The full list lives in packages/nexus-agents/src/config/in-tree-data.ts; supported IDs include claude-opus / claude-sonnet / claude-haiku, gemini-3-pro / gemini-3-flash, codex-5.3 / codex-5.2 / codex-5.1-mini, plus opencode-* and openrouter-* variants. To use a model outside this set (e.g. an OpenAI-compatible gateway), see the NEXUS_CUSTOM_MODEL env var below.

# nexus-agents.yaml

# Model configuration — use latest models from each provider
models:
  # Default model for general tasks
  default: claude-sonnet

  # Model tiers for routing
  tiers:
    fast:
      - claude-haiku
      - codex-5.1-mini
      - gemini-3-flash
    balanced:
      - claude-sonnet
      - codex-5.2
      - gemini-3-pro
    powerful:
      - claude-opus
      - codex-5.3
      - gemini-3-pro

# Expert configuration
experts:
  # Enable built-in experts (code, architecture, security, performance, research)
  builtin: true

  # Custom expert definitions
  custom:
    rust_expert:
      prompt: |
        You are a Rust expert specializing in systems programming,
        memory safety, and performance optimization. You follow the
        Rust API Guidelines and prefer idiomatic solutions.
      tier: powerful
      tools:
        - read_file
        - write_file
        - execute_command

    react_expert:
      prompt: |
        You are a React expert specializing in modern React patterns,
        hooks, and performance optimization. You follow React best
        practices and prefer functional components.
      tier: balanced

# Routing configuration
routing:
  # Enable three-stage routing pipeline
  enableBudgetFilter: true
  enableTopsisRanking: true
  enableLinUCBSelection: true

  # Budget constraints
  budget:
    tokenBudget: 1000000 # Session token limit
    costBudgetUsd: 10.0 # Session cost limit
    resetIntervalMs: 3600000 # 1 hour reset

  # TOPSIS multi-criteria ranking
  topsis:
    minQualityThreshold: 5 # 0-10; candidates below this are not ranked
    criteria: # weights must sum to 1.0
      - { name: quality, weight: 0.5, beneficial: true }
      - { name: cost, weight: 0.3, beneficial: false }
      - { name: latency, weight: 0.2, beneficial: false }

  # LinUCB bandit configuration
  linucb:
    alpha: 1.0 # Exploration parameter

# Memory configuration
memory:
  # Session memory
  session:
    maxEntries: 1000
    ttlMs: 86400000 # 24 hours

  # Graph memory
  graph:
    enabled: true
    maxNodes: 10000
    maxEdges: 50000

  # Typed memory (MIRIX six-type system)
  typed:
    enabled: true
    pruneThreshold: 0.3

  # Coordinated decay across belief / agentic / adaptive / MobiMem (#5097)
  decay:
    enabled: true
    decayIntervalMs: 3600000 # 1 hour
    agenticMaxEntries: 10000

# Security configuration
security:
  # Allowed paths for file operations
  allowedPaths:
    - ./
    - /tmp

  # Sandbox execution mode: none, policy, container
  sandbox:
    mode: policy
    fallbackMode: none
    resourceLimits:
      memory: 512m
      cpu: 2
      timeout: 300s
      maxProcesses: 10

  # Rate limiting
  rateLimit:
    enabled: true
    requestsPerMinute: 60

# Workflow configuration
workflows:
  # Directory containing workflow templates
  templateDir: ./workflows

  # Maximum parallel steps
  maxParallelSteps: 5

  # Step timeout
  stepTimeoutMs: 300000 # 5 minutes

# Logging configuration
logging:
  level: info # debug, info, warn, error
  format: json # json, pretty
  file: null # Optional log file path

Environment Variables

All configuration can be overridden with environment variables:

Every NEXUS_* variable is validated at startup against packages/nexus-agents/src/config/env-schema.ts. A name the schema does not recognize is reported as unknown, with a typo suggestion — including a name that is correct and documented here but absent from the schema, which is how NEXUS_DATA_DIR came to be flagged (#4722). A variable added to this document must be added to the schema in the same change, and a test now cross-checks the two lists so they cannot drift apart again.

Core Variables

Model Provider Keys

Security Variables

NEXUS_DRIFT_ADVISORY is script-scoped: it is read by scripts/check-model-string-drift.ts and never by the server, so it is deliberately absent from the runtime env-schema, which validates the server’s own process env. Setting it affects the CI gate, not a running server (#5159).

Orchestration Variables

NEXUS_ALLOW_SIMULATE scope notes (#4170). Test-runner detection trusts VITEST=true / NODE_ENV=test — a server started with an inherited test environment therefore disables the ban. The gate covers the MCP tool surface (consensus_vote, run_pipeline, run_dev_pipeline, pr_review, supply_chain_tradeoff_panel); programmatic library consumers (e.g. createAgentStages / executeVoting via the package exports) sit below the gate by design.

Scheduled improvement_review (#3229). Periodically runs improvement_review server-side so its signal.fitness_declined fires without manual invocation, feeding the self-tuning loop:

The scheduled run is analysis-only by default (emits signals, files no issues); NEXUS_IMPROVEMENT_REVIEW_FILE_ISSUES=true is a deliberate, separate opt-in (the tool’s 5-issues/run rate-limit + open-issue dedup are backstops, not the primary guard).

Learning & Memory Variables

Outcomes and distilled routing rules persist to ~/.nexus-agents/learning/ — this is cross-repo state (shared across all your projects) and is not affected by the per-repo data dir (epic #2872). When persistence is enabled, routingMemory, strategyDistillation, and preferenceRouting also auto-enable (no separate config needed). Opt out with NEXUS_PERSIST_LEARNING=false.

NEXUS_STRATEGY_DISTILLATION — distilled routing rules (#6512). When it is on (the default), the first route in each process distills rules from the persisted outcome store if at least 50 eligible outcomes are newer than the last rules.json snapshot. Only delegate outcomes marked cliSource: 'executed', with a positive duration and a real CLI name, are eligible. false/0 turns distillation off without touching outcome persistence: the router builds no distiller, and it reads or applies no distilled rule. It overrides a config that enables routing.stages.strategyDistillation. nexus-agents doctor reports Distilled rules: N (A active; trained on E eligible outcomes; last distill: …).

NEXUS_TUNE_ENFORCE — the self-tuning routing loop (epic #3143 / #3147). The loop reacts to health signals (signal.swarm_unhealthy from SwarmObserver bottlenecks and adapter circuit-breaker failovers) by demoting an unhealthy CLI in routing. The same flag gates both the write (the TuneStage applies the demotion) and the read (the CompositeRouter folds it into candidate scoring), so the loop is either fully live or fully shadow — never half-wired.

• true (enforce, default since v2.96) — a signal.swarm_unhealthy applies a bounded routing demotion via the provenance-tagged TuneAdjustmentStore. Every demotion is recorded to the tamper-evident append-only audit chain as a tune.demote event (verify with verify_audit_chain; tamper-evident, not tamper-proof — see the audit hash-chain threat model).
• false (shadow, opt-out) — the loop logs the demotion it would apply and records it to the intended counter, but routing is untouched. Use this to disable auto-tuning fleet-wide, or to observe the would-be behavior first: nexus-agents health shows applied vs intended per CLI under “Self-Tuning Demotions”.

The demotion is bounded by hard safety invariants so the loop is self-correcting, never a ratchet: demotion-only (a CLI is slowed, never boosted), floored at 0.5 (never zeroed out of routing — a sole-viable CLI is always still selectable), capped at 0.2 per step, and time-decaying linearly back to neutral over 30 minutes (a transient health blip auto-reverses). The channel is separate from the LinUCB real-outcome bandit. Opt out with NEXUS_TUNE_ENFORCE=false. See Self-Tuning Loop.

Files stored:

• outcomes.jsonl — Append-only JSONL of task outcomes
• rules.json — Atomic JSON snapshot of distilled routing rules

Security & Governance Variables

NEXUS_REPUTATION_GATING graduation path: off bypasses entirely; audit logs every violation and blocks nothing; enforce blocks. Author-reputation tier demotion in issue_triage (epic #3118). (The NEXUS_ACCESS_POLICY_MODE ladder that used to sit here — audit → confirm_risky → enforce — was retired with the ClawGuard deriver in #5108; the secret-path control it fronted is the PolicyFirewall secret-paths rule, whose enforce rollout is #4988.)

• off — reputation never affects the enforced trust tier
• audit — reputation is computed and the would-be demotion is logged + surfaced (trustAssessment.effectiveTrustTier/gatingMode), but the classifier tier is enforced. Collects telemetry on the demotion rate before enforcing
• enforce (default) — apply the reputation demotion at the policy gate (a suspicious author’s tier-gated actions are blocked)

Escape hatch: in every mode the maintainer allowlist (Tier 1) is authoritative — reputation can never demote an allowlisted/owner author. To clear a false-positive demotion for a specific user, add them to the allowlist; to disable gating fleet-wide, set off.

Timeout Variables

Central timeout authority (#3734)

Timeouts are runaway-guards, not SLAs — each MCP tool maps to an operation class with a generous upper bound (the historical 60s MCP default was accidental + punitive). The class an unclassified tool falls back to is single-llm (300s).

Resolution, one order for every class (#6162): max(envClassOverride ?? base, 1000) × multiplier, clamped once to the class ceiling — MCP_TIMEOUTS.maxMs (3600000) for every class that runs inside an MCP request, 7200000 for async-job-body, which runs outside any MCP request (#5995). The ceiling is applied to the product, so an override above it is reported as reduced rather than trimmed before the multiplier sees it; an override above 7200000 with a multiplier below 1 on a request-bound class resolves to min(override × multiplier, 3600000) and is attributed to the override. A value clamped away is reported at startup (Environment variable … had no effect). The near-timeout WARN for a backgrounded job fires at 0.5 of whatever guard it runs under, and the effective guard is logged once at job start; get_job_result and list_jobs expose a pending job’s lastProgressAt (its last heartbeat, absent when it never sent one) so a poller can tell slow from stuck. Explicit per-call and security.perToolTimeout overrides still win over the class guard.

Rate limiting, retries and circuit breakers are configured in the config file, not by environment variable. NEXUS_RATE_LIMIT_*, NEXUS_RETRY_* and NEXUS_CIRCUIT_BREAKER_* were removed in #5903 — they were registered and documented but read by nothing that runs, so setting one changed nothing while config get reported it as Source: (env). Use security.rateLimit (see the config-file example above); retry and circuit-breaker behaviour is currently code-level, not operator-configurable.

Infrastructure Variables

Gateway behind a corporate network (#6608)

These apply to the in-process OpenAI-compatible gateway path (model discovery and the per-model adapters behind NEXUS_OPENAI_COMPAT_URL) and to the single-model custom-openai SDK path, which applies the same auth header, extra headers and proxy (#6629). CLI subprocesses get the proxy variables through their own environment (subprocess-env.ts).

• Auth header. NEXUS_OPENAI_COMPAT_AUTH_HEADER and NEXUS_OPENAI_COMPAT_EXTRA_HEADERS, above.
• Proxy. Gateway calls honour HTTPS_PROXY (for an https:// gateway) or HTTP_PROXY (for http://), lowercase spellings first, and skip the proxy when the gateway host matches NO_PROXY / no_proxy (*, a host, a domain suffix with or without a leading ., optionally :port). The proxy must be an http:// or https:// URL; any other scheme is warned and gateway calls go direct. The proxy URL is never logged, since it can carry credentials. Measured on Node 22.22.3: the global fetch, and so the openai SDK, does not read these variables unless the process was started with NODE_USE_ENV_PROXY=1 (a loopback proxy saw no traffic without it). The gateway therefore gets an explicit proxy agent (undici ProxyAgent), so the variables apply without NODE_USE_ENV_PROXY; this was measured on Node 22.22.3 only.
• Corporate CA. NODE_EXTRA_CA_CERTS reaches gateway calls: measured on Node 22.22.3 against a self-signed loopback gateway, the global fetch, the openai SDK, and the SDK through the proxy agent’s tunnel all failed with DEPTH_ZERO_SELF_SIGNED_CERT without it and succeeded with it. Node reads it once at startup, so set it in the server’s launch environment.
• Private addresses. A gateway host that resolves to a private, loopback or link-local address is refused unless NEXUS_CUSTOM_API_ALLOW_PRIVATE=1. The startup warning names that variable and says the gateway is not in use; under sandbox mode the server exits instead.
• Gateway down at boot. When discovery fails at startup because the gateway is unreachable, returns an error or lists no models, the server starts on CLI subprocesses and retries discovery on a later model call, at most once every 60 s (the boot attempt starts the clock). Retries run only on a call, never on a timer, and stop once the gateway is wired. Since #6659 every adapter the registry hands out triggers the retry, not only voting and pr_review, and each re-detects once after a late discovery, so the default adapter and the family slots move onto the gateway. A DNS lookup that takes over 5 s fails the attempt closed and is retried; a DNS error fails open. A private-address refusal is not retried: fixing it is an environment change, which needs a restart.

Runtime internals, record paths and nesting guards (#5142)

These are read by production code and are registered in config/env-schema.ts. They were previously unregistered, so setting one produced an “unknown variable” warning at startup with a typo suggestion, even though the value was honoured.

Dynamic families. Two variable names are constructed at runtime, so they are matched by prefix rather than listed individually:

A <ROLE> that is not a real voter role is still reported as an unknown variable — the prefix match is checked against the canonical role list, not accepted blindly.

Code-PR adapter activation (#3670) — ARMED but DORMANT

The autonomous code-PR adapter (#3670) is built and owner-approved (2026-06-19) but DORMANT. It is “armed”, not “active”: the owner approval satisfies the human-authorization gate, but it does not activate the push path. Activation is earned through conjunctive, falsifiable, evidence-based gates — every one must hold, and each is an independently checkable operational fact (never model output, never “the owner said so”).

A push is impossible unless ALL of the following conjunctive gates hold:

• Enable flag — the explicit OFF→on flag. There is no enable env var yet: the flag is passed in as the flagEnabled boolean on the readiness evidence (CodePrEnableReadinessEvidence / CodePrPushReadiness.flagEnabled), supplied by the operator wiring point that constructs the push input. The gate stays pure and reads no env for the flag.
• Enable-vote ref — a recorded enable-vote ref (enableVoteRef, non-empty), supplied on the readiness evidence alongside the named owner acknowledgement.
• NEXUS_CODEPR_TOKEN — a least-privilege scoped credential that may open a feature-branch PR ONLY. It cannot merge, push to main/master, force-push, or alter branch protections. It is an operator-provisioned env var read directly by the push seam (CODEPR_TOKEN_ENV), not part of the validated validateNexusEnv set; absent or empty ⇒ a hard no_credentials refusal.
• guardsGreenSoak ≥ 50 — at least 50 consecutive clean (zero guard-denial) dry-run plans, accrued automatically by the NEXUS_AUTO_REMEDIATE=audit soak consumer. The streak is read from the durable soak store at push time, not from caller input — it cannot be forged.

Warning — setting the flag alone does NOT activate the adapter. Flipping flagEnabled true (or recording the enable-vote, or provisioning the token) is necessary but never sufficient: every evidence gate above still applies, and any unmet gate fails closed. This is deliberate (per the DevX vote condition) so there is no “enabled but does nothing” confusion — the adapter is dormant until the soak is earned AND the scoped token is present AND the flag/vote/owner-ack are all recorded. Owner approval authorizes activation; it does not perform it.

See #3670 for the staged rollout (the push path is the gated capability; nothing here wires it to a live runtime trigger).

Audit-mode remediation soak: the operator store is the evidence path (#4224, #4279)

The enforce-readiness soak (learning/remediation-soak.jsonl, read by remediation-readiness-collector.ts) only accrues when someone runs nexus-agents auto-remediate. It is not a byproduct of normal work, so without a scheduler the evidence the enforce gate depends on cannot accumulate — it flatlined on 2026-06-17 despite heavy repo activity, and again at one record for the five weeks before #4279 was re-verified. There is ONE evidence path (the local operator cycle below) and one CI job that is deliberately not one:

1. The CI job is a smoke test, not evidence (.github/workflows/remediation-audit-soak.yml, display name “Remediation Audit Smoke (no readiness evidence)”). It runs the build then nexus-agents auto-remediate in audit mode daily (cron: '17 7 * * *') plus workflow_dispatch, and proves the audit path — collect → research → vote → append — runs end to end on the built CLI. It exports NEXUS_AUTO_REMEDIATE=audit and asserts it before running, and the cycle entry point structurally withholds repoRoot, so enforce cannot engage from CI. It keeps permissions: contents: read.

A green run is not progress toward #3769. The #4279 panel (5–2, Option B) declared the CI soak non-evidence, for three reasons that hold independently:

• Disjoint store. The job appends under a workspace NEXUS_DATA_DIR that lives only in actions/cache (evicted after 7 idle days). The readiness gate reads the operator store (~/.nexus-agents/learning/remediation-soak.jsonl); nothing bridges the two, and 43 green runs moved the gate by zero records.
• Un-judged by construction. Readiness requires a NAMED evaluator and owner (remediation-review mark / sign-off) — human acts. A bridged CI corpus would arrive with judgedSelections: 0 and fail judged-coverage, named-evaluator and named-owner regardless of its volume.
• Self-authorship. Letting the job commit its records would widen the cron-triggered token to contents: write so the automation seeking enforce authority could author the evidence that grants it.

The job also wires no model/gateway secrets, so its per-signal vote degrades to no_quorum at zero LLM cost and its records carry no voteOutcome — thin even as smoke coverage. Treat it as an alarm that the audit path still runs, nothing more.

2. LOCAL cron / systemd timer — the evidence path. Readiness evidence comes from your real ~/.nexus-agents telemetry, not a clean CI runner: a fresh checkout has little of your outcome/decision-cost telemetry, so the improvement_review signals it collects are thin and near-identical day to day. If you operate nexus-agents day-to-day, schedule the audit cycle locally where that telemetry lives. Audit mode is the default, so a bare invocation is soak-only with zero writes:

# crontab -e — daily audit-mode soak against your real ~/.nexus-agents telemetry
17 7 * * * cd /path/to/your/repo && NEXUS_AUTO_REMEDIATE=audit nexus-agents auto-remediate >/dev/null 2>&1

Or as a systemd timer (~/.config/systemd/user/nexus-soak.service + nexus-soak.timer with OnCalendar=daily) running the same command.

After a soak window, judge a batch with nexus-agents remediation-review and the readiness gate reflects genuine soundness over real, plan-bearing selections. Every tier’s record is judgeable — mark keys on the soak ref, never on whether a dry-run was captured (#4279 Gap 2).

Watch the store, not the CI job. nexus-agents remediation-review readiness prints a Soak store: line beside the verdict (#4279): UNMEASURED when the store is empty, ALARM when it holds ≤1 record or has had no new record for 14 days (each cause named), fresh otherwise; --format json carries the same signal as soakStore. A flatlined operator store is a stalled evidence path and this is the only place it is reported — the CI smoke job cannot see it.

Known limitation — dryRunResult (plan content) is not captured in the scheduled/local audit cycle. The p0 dry-run audit event that populates a soak record’s dryRunResult only fires when a dryRun capability is wired into the deps — buildAutoRemediationDeps does not wire one, and there is no config/flag/env to enable it from the CLI. So accrued records carry the real signalKey, category, priority, planStepCount, and reason (plus voteOutcome only where LLM credentials are present — i.e. the local path, not credential-less CI, per the note above), a large improvement over the prior synthetic, uniform volume — but not the full dry-run plan text. This limits what an evaluator has to read; it does not limit what they can mark. Wiring a dryRun adapter into the audit cycle so the accrued selections are fully plan-bearing is tracked as follow-up to #4224 (and would also need the dry-run audit detail to carry plan content rather than just ok/error).

On-demand MetaOrchestrator shadow-training soak (#4310)

The shadow-training MECHANISM has worked since #3593: with NEXUS_META_SHADOW_TRAIN=1, executeGoal (the run{execute:true} engine) feeds every live dispatch outcome into the MetaOrchestrator shadow selector and appends a sanitized record — bandit feature values + a success flag only, never task text — to learning/meta-outcomes.jsonl. But nothing ever TRIGGERED it: training only fires on a live run call, and no CI/cron/CLI ever made one, so the shadow-agreement evidence the #3552 shadow→route flip decision depends on could not accumulate. .github/workflows/meta-shadow-soak.yml and scripts/meta-shadow-soak.ts give it an organic feed, mirroring the #4224 remediation-audit-soak precedent above.

This is a FEEDER, not a router. NEXUS_META_SHADOW_TRAIN=1 is the only lever this soak pulls. It never alters which strategy run actually dispatches, and it never feeds the enforce/routing path — the #3552 shadow→route flip stays a separate, human-gated change. The workflow asserts this invariant explicitly before running.

Goal sourcing (ratified for #4310): REAL backlog issues, not synthetic. The script fetches open issues from the repo via gh issue list, formats each as #<number>: <title> plus its first body paragraph, and deterministically selects a bounded set (default 12, most-recent-first by issue number — a reproducible proxy for recency). Synthetic goals would exercise the router on a distribution that doesn’t resemble what run actually sees in production, undermining the shadow-agreement evidence the flip decision depends on. The selection/formatting logic is pure and unit-tested (scripts/meta-shadow-soak-core.ts); the gh fetch and the live executeGoal dispatch are the thin, untested-by-unit I/O edge (scripts/meta-shadow-soak.ts), mirroring the curate-pr-review-harvest.ts / mine-pr-review-candidates-core.ts split (#3847).

1. workflow_dispatch only — deliberately NO schedule: trigger. The #4224 audit-mode cycle costs zero LLM spend without credentials (createAutoAdapter throws before any network call), but this soak dispatches REAL strategies (dev-pipeline / pipeline / research / consensus) through real model gateways when credentials are present, so a recurring cron would recur real API cost with no CI-cost mandate to justify it. An owner triggers it manually from the Actions tab as the evidence window needs topping up.

Secret-gated — skips cleanly, never fails, when no model-gateway credential is configured. A check-secrets step inspects ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_AI_API_KEY / OPENROUTER_API_KEY (the same set pr-review.yml checks) and every downstream step is conditioned on at least one being present. Without one, the job reports “skipped” in the step summary and exits green — this workflow is safe to leave present even before model credentials are configured as repo secrets.

2. LOCAL on-demand run (no CI cost, uses your own credentials/telemetry):

NEXUS_META_SHADOW_TRAIN=1 pnpm exec tsx scripts/meta-shadow-soak.ts --count 12 --repo nexus-substrate/nexus-agents

Requires gh authenticated against the target repo (gh auth status) and model-gateway credentials for whichever strategies the router selects. A goal that routes to an unwired strategy (graph-workflow / spec / orchestrate / single-shot) still accrues a failure shadow-training record — the dispatcher records an outcome even for a no_executor dispatch — so even those goals are not wasted soak volume. The script prints a summary: goals run, meta-outcomes.jsonl record count before/after, and file size.

Stub vs. live: goal selection/formatting (meta-shadow-soak-core.ts) is pure and fully unit-tested against fixtures — no network, no live models. The gh fetch and the executeGoal dispatch are real I/O with no stub or mock path; there is no simulateVotes/synthetic-outcome mode by design (a mocked evidence trail would be worse than no evidence trail for a decision #3552 depends on).

Removed in 2.82.0 (#2977)

These 8 env vars were declared but never read by any production code (silent no-ops). They have been removed from the env-schema; setting them is now an error from validateNexusEnv. If you had any of them set, just unset them:

NEXUS_WORKERS_MAX, NEXUS_WORKERS_POOL_SIZE, NEXUS_WORKERS_IDLE_TIMEOUT, NEXUS_WORKFLOW_MAX_PARALLEL, NEXUS_TEST_PARALLELISM, NEXUS_EVALUATION_MAX_WORKERS, NEXUS_EVENTBUS_MAX_HISTORY, NEXUS_SWARM_OBSERVER_MAX_EVENTS.

The matching WORKER_DEFAULTS.* config-set keys are also gone; config set WORKER_DEFAULTS.foo X now returns “key not found” instead of a false success.

Removed (#4180)

Three more env vars from the same silent-no-op class, missed by the #2977 sweep, were declared in the env-schema but never read by any production code. They have been removed; validateNexusEnv now flags them as unknown. If you had any of them set, just unset them:

NEXUS_TEST_TIMEOUT_MS, NEXUS_TIMEOUT_CLISIMPLE, NEXUS_TIMEOUT_CLICOMPLEX.

The matching (equally unread) TIMEOUT_DEFAULTS.cliSimpleMs / TIMEOUT_DEFAULTS.cliComplexMs defaults keys are also gone. Per-complexity CLI timeouts were never driven by these knobs — they flow through the internal per-CLI TIMEOUT_PROFILES (getTimeoutForCli).

Removed (#4939)

The last four variables of the getTimeout() family — NEXUS_TIMEOUT_CLI, NEXUS_TIMEOUT_API, NEXUS_TIMEOUT_WORKFLOW, NEXUS_TIMEOUT_MCP — were registered in the env-schema and read by nothing that runs: getTimeout() had zero production callers, and the only observable effect of setting one was config get TIMEOUT_DEFAULTS.cliMs answering Source: (env) for a value no code consumed (the same false-positive #5903 removed for the rate-limit, retry and circuit-breaker families). They are gone from the schema; validateNexusEnv now reports them as unknown. If you had any of them set, just unset them. The timeout knobs that ARE read are NEXUS_VOTE_TIMEOUT_MS, NEXUS_EXPERT_TIMEOUT_MS, NEXUS_WORKER_TIMEOUT_MS, NEXUS_TIMEOUT_MULTIPLIER and the NEXUS_TIMEOUT_CLASS_*_MS family documented above.

Deprecated (#4392 increment 3)

NEXUS_CUSTOM_API_BASE_URL and NEXUS_CUSTOM_API_KEY are deprecated aliases of NEXUS_OPENAI_COMPAT_URL and NEXUS_OPENAI_COMPAT_KEY. Each is resolved new ?? old per variable (the GEMINI_API_KEY → GOOGLE_AI_API_KEY precedent), trimmed, with an empty value meaning unset. Both stay registered in the env-schema — setting one is not reported as a typo — and both are dropped in the next major (#6291). NEXUS_CUSTOM_MODEL is not deprecated.

What the legacy names still do, and what they do not (panel decision, option C):

• They configure only the single-model custom-openai path — the SdkAdapter behind createAutoAdapter and the api:custom-openai routing arm under NEXUS_BILLING_MODE=api, pinned to NEXUS_CUSTOM_MODEL.
• They do not configure the gateway path. Model discovery (GET /v1/models), in-process voter transport and the api:<endpoint> arm are reached through NEXUS_OPENAI_COMPAT_URL / NEXUS_OPENAI_COMPAT_KEY only. Renaming is what opts you in — an operator who keeps the legacy names gets exactly the behaviour they had before.

How you find out: one startup warning names each deprecated variable that is set, whether it is honoured or ignored because the replacement is also set, and the replacement — never a value. nexus-agents doctor prints the same per variable under Voter transport (⚠ … is deprecated — use … (alias until the next major, #6291)); it is a warning, not a failure. validateNexusEnv returns them in deprecatedVars without logging (the resolver already did). nexus-agents setup --custom-api writes the new names.

Removed (#5665)

NEXUS_AUTH_METHOD was registered and documented (default token) but never reached enforcement: initializeAuth reads security.auth.method from the config file only, and the variable’s sole reader was the startup log line (#5663). It has been removed from the env-schema by panel decision (3/3, remove rather than wire — same reasoning as #2977 / #4180); validateNexusEnv now reports it as unknown. Set security.auth.method in the config file instead.

Model Configuration

Default Model

The default model is used when no specific model is requested:

models:
  default: claude-sonnet

Model Tiers

Models are organized into tiers for automatic routing:

models:
  tiers:
    fast:
      - claude-haiku # Quick, simple tasks
      - codex-5.1-mini
    balanced:
      - claude-sonnet # Most tasks
      - codex-5.2
    powerful:
      - claude-opus # Complex reasoning
      - codex-5.3

The router selects the appropriate tier based on task complexity.

Model-Specific Settings

Override settings for specific models:

models:
  settings:
    claude-opus:
      temperature: 0.7
      maxTokens: 8192
    codex-5.3:
      temperature: 0.5
      maxTokens: 4096

Expert Configuration

Built-in Experts

Enable or disable built-in experts:

experts:
  builtin: true # Enable code, architecture, security, performance, research

Custom Experts

Define domain-specific experts:

experts:
  custom:
    database_expert:
      prompt: |
        You are a database expert specializing in PostgreSQL,
        query optimization, and schema design. You follow
        database normalization principles and prefer
        efficient, maintainable solutions.
      tier: balanced
      tools:
        - read_file
        - execute_command
      capabilities:
        - sql_analysis
        - schema_design
        - query_optimization

Expert Prompt Templates

Planned feature: Variable interpolation in expert prompts ({{variable}} syntax) is not yet implemented. The variables key shown below is not currently processed by the runtime. This section describes the intended configuration shape.

experts:
  custom:
    project_expert:
      prompt: |
        You are an expert for the {{project_name}} project.
        The project uses {{language}} and follows {{style_guide}}.
      variables:
        project_name: nexus-agents
        language: TypeScript
        style_guide: Google TypeScript Style Guide

Routing Configuration

Budget Constraints

Control cost and resource usage:

routing:
  budget:
    tokenBudget: 1000000 # Max tokens per session
    costBudgetUsd: 10.0 # Max cost per session
    resetIntervalMs: 3600000 # Reset every hour

Per-Task-Class Cost Ceilings

Cap the per-task USD cost by task class (#4196, #4214). Each key is a TaskCategory (architecture, code_generation, code_review, research, security_review, planning, documentation, testing, devops, exploration); a typo’d key fails config validation instead of silently configuring nothing:

routing:
  budget:
    taskClassMaxCostUsd:
      code_generation: 0.25 # Max $0.25 per code-generation task
      research: 1.00 # Research tasks may spend more

Two things to know before relying on ceilings:

• NEXUS_BILLING_MODE=api is required. Ceilings are only enforced in cost-aware (api) billing mode. Under the default plan mode they are an annotated no-op — the routing decision reason carries cost weighting disabled: plan mode and no candidate is ever filtered.
• Unpriced candidates fail closed. When a ceiling is configured for the task’s detected class, any candidate whose model has no registry pricing is excluded — an unknown cost is never allowed to slip under a configured ceiling. If every candidate exceeds the ceiling (or is unpriced), routing fails at the budget-filter stage rather than falling back to all-candidates.

Omit taskClassMaxCostUsd (or leave it empty) to disable ceilings entirely (the default).

TOPSIS Weights

Adjust multi-criteria optimization:

routing:
  topsis:
    criteria: # weights must sum to 1.0
      - { name: quality, weight: 0.5, beneficial: true } # prioritise quality
      - { name: cost, weight: 0.3, beneficial: false } # consider cost
      - { name: latency, weight: 0.2, beneficial: false } # some latency tolerance

For cost-sensitive deployments:

routing:
  topsis:
    criteria:
      - { name: quality, weight: 0.3, beneficial: true }
      - { name: cost, weight: 0.5, beneficial: false }
      - { name: latency, weight: 0.2, beneficial: false }

LinUCB Bandit

Control exploration vs exploitation:

routing:
  linucb:
    alpha: 1.0 # Higher = more exploration

• alpha: 0.5 - Conservative, prefer known-good models
• alpha: 1.0 - Balanced exploration (default)
• alpha: 2.0 - Aggressive exploration, try new combinations

Advanced Routing Stages (Optional)

Enable optional routing stages for specialized use cases:

routing:
  stages:
    # Confidence-based cascade routing (SATER-style escalation)
    confidenceCascade: false

    # Task capability matching (matches task requirements to model capabilities)
    capabilityMatch: false

    # Quality-constrained routing (RouteLLM-style cost/quality tradeoff)
    qualityConstraint: false

These stages are disabled by default for backward compatibility. Enable them to add additional routing intelligence:

Memory Configuration

Session Memory

Configure conversation context:

memory:
  session:
    maxEntries: 1000 # Max memories per session
    ttlMs: 86400000 # 24 hour TTL
    pruneStrategy: lru # Least recently used

Graph Memory

Configure relationship tracking:

memory:
  graph:
    enabled: true
    maxNodes: 10000
    maxEdges: 50000
    similarityThreshold: 0.6

Typed Memory (MIRIX)

Configure six-type memory system:

memory:
  typed:
    enabled: true
    types:
      core: true # Agent identity
      episodic: true # Task experiences
      semantic: true # Domain knowledge
      procedural: true # Learned workflows
      resource: true # External references
      vault: true # Persistent storage
    pruneThreshold: 0.3

Coordinated Decay

Configure the FADE-style decay sweep that MemoryDecayManager runs across the belief, agentic, adaptive and MobiMem stores. Every key is optional; an unset key falls through to the default in DEFAULT_DECAY_CONFIG (packages/nexus-agents/src/mcp/tools/memory-decay.ts) — the schema carries no second copy of the defaults. Before #5097 this manager was constructed with a hardcoded {}, so none of these keys could reach it.

memory:
  decay:
    enabled: true # false disables the sweep entirely
    decayIntervalMs: 3600000 # ms between automatic runs (default: 1 hour; minimum 1000)
    beliefMaxAgeDays: 30 # prune superseded beliefs older than this
    agenticMaxEntries: 10000 # importance-based eviction starts above this
    agenticImportanceThreshold: 0.3 # 0-1; agentic entries below are evicted
    adaptivePriorityThreshold: 0.2 # 0-1; adaptive entries below are evicted
    mobimemEvictOnDecay: true # run MobiMem TTL eviction on each sweep
    checkCrossReferences: true # keep cross-referenced items past the sweep
    crossReferenceGracePeriodMs: 604800000 # 7 days

Validation happens at config load: counts and durations must be positive safe integers (crossReferenceGracePeriodMs may be 0; decayIntervalMs has a 1000 ms floor because sweeps are not re-entrant and a sub-second cadence would let them overlap), thresholds must lie in [0, 1], and a bad value fails startup with the offending path named (memory.decay.decayIntervalMs, for example). The server logs one line at activation — MemoryDecayManager activated (Phase 5 #746) — carrying the effective value of every key, read back from the manager, plus a source field: config when the MCP server applied nexus-agents.yaml, or defaults (configureToolMemory never called) on CLI paths (composite-router, dev-pipeline, graph-executor) that build the memory singleton without loading the file. Defaults on those paths are therefore labelled as such rather than passing for a file that happened to say the default.

Security Configuration

Sandbox Mode

Choose execution isolation level:

security:
  sandbox:
    mode: policy # none, policy, container
    fallbackMode: none

Resource Limits

For container mode:

security:
  sandbox:
    resourceLimits:
      memory: 512m
      cpu: 2
      timeout: 300s
      maxProcesses: 10

Policy Firewall

Every locally registered MCP tool call is evaluated by the PolicyFirewall (src/mcp/middleware/policy.ts) under an execution mode:

security:
  policy:
    defaultMode: read-write # default; read-only is the operator's lock (see below)
    policyMode: enforce # default, but NOT the effective mode — see NEXUS_MCP_POLICY_ENFORCE

The startup Security configuration line reports both: policyMode (effective mode and its reason) and defaultExecutionMode.

Rate Limiting

Protect against abuse:

security:
  rateLimit:
    enabled: true
    requestsPerMinute: 60
    burstLimit: 10

Authentication (Network Transport)

Configure authentication for network-exposed MCP transports:

security:
  auth:
    enabled: true # Enable authentication
    method: token # 'token' is the only implemented method; 'oauth2' is accepted but behaves as 'token' and warns (#5678)
    tokenHeader: Authorization # Header name for bearer token
    tokenFile: ~/.nexus-agents/auth/server-token # Token file path (auth/ is cross-repo)

Generate and manage auth tokens with CLI commands:

# Generate initial token
nexus-agents auth init

# Show token status
nexus-agents auth show

# Rotate token (invalidate old, generate new)
nexus-agents auth rotate

Note: Authentication is for network-exposed transports (HTTP, WebSocket). Stdio transport is inherently secure as it only communicates with the parent process.

Workflow Configuration

Template Directory

Specify where workflows are stored:

workflows:
  templateDir: ./workflows

Execution Limits

Control workflow behavior:

workflows:
  maxParallelSteps: 5
  stepTimeoutMs: 300000
  maxRetries: 3
  retryDelayMs: 1000

Programmatic Configuration

When using nexus-agents as a library:

import { createServer, startStdioServer } from 'nexus-agents';

const result = await startStdioServer({
  name: 'my-server',
  version: '1.0.0',
  config: {
    models: {
      default: 'claude-sonnet',
    },
    routing: {
      enableLinUCBSelection: true,
      budget: {
        tokenBudget: 500000,
      },
    },
    security: {
      sandbox: {
        mode: 'policy',
      },
    },
  },
});

Inspecting Configuration

View the resolved configuration (merging defaults, file, and environment variables):

nexus-agents config show

Read a specific key:

nexus-agents config get models.default

Set a key in the config file:

nexus-agents config set models.default claude-haiku

Note: nexus-agents config validate does not exist. The valid subcommands are: init, show, get, set, import.

Configuration Examples

Cost-Optimized

Minimize API costs:

models:
  default: claude-haiku

routing:
  budget:
    costBudgetUsd: 1.0
  topsis:
    criteria:
      - { name: quality, weight: 0.3, beneficial: true }
      - { name: cost, weight: 0.6, beneficial: false }
      - { name: latency, weight: 0.1, beneficial: false }

Quality-Focused

Maximize output quality:

models:
  default: claude-opus

routing:
  budget:
    costBudgetUsd: 50.0
  topsis:
    criteria:
      - { name: quality, weight: 0.7, beneficial: true }
      - { name: cost, weight: 0.1, beneficial: false }
      - { name: latency, weight: 0.2, beneficial: false }

CI/CD Pipeline

Fast, secure, cost-aware:

models:
  default: claude-sonnet

security:
  sandbox:
    mode: container
  rateLimit:
    enabled: true
    requestsPerMinute: 100

routing:
  budget:
    tokenBudget: 500000
    costBudgetUsd: 5.0

logging:
  level: warn
  format: json

Configuration for Reusable Pipelines

A composed pipeline (research → vote → plan → run → review) inherits the same resolved config at every stage, so a single knob changes behavior fleet-wide. Three high-impact knobs and what they do across stages:

• NEXUS_BILLING_MODE — plan (default) zeroes model cost in scoring, so routing’s ZeroRouter/TOPSIS stages pick the strongest model regardless of price; every voter, planner, and worker in the pipeline trends toward claude-opus-tier. api keeps cost-aware routing, so the same pipeline shifts toward cheaper tiers under the session budget. Verified in decision-cost-recording.ts (default 'plan') and defaults.ts:298.
• NEXUS_DATA_DIR / NEXUS_REPO_PREFERRED — per-repo state (sessions, checkpoints, traces, runs, audit, pipeline, tasks, jobs, ci-health, governance) lands in <repo>/.nexus-agents/ when NEXUS_REPO_PREFERRED=1 (default), so two checkouts keep independent run/audit history. NEXUS_DATA_DIR overrides the split entirely. Cross-repo state — learning/, memory, voting, research, auth — always resolves to ~/.nexus-agents/, so the routing-feedback loop is shared across projects regardless (nexus-data-dir.ts). Under the MCP server the “repo” is the workspace the client declares via the MCP roots capability (no env var needed): a globally-installed server learns the active workspace root from the connected editor/agent at handshake time, so per-repo state still lands in <repo>/.nexus-agents/ even though the server’s own working directory is the npm global bin. Clients that don’t advertise roots fall back to the server’s working directory, then ~/.nexus-agents/ (mcp/workspace-roots.ts, #3991).
• Model tiers + sandbox — models.tiers (fast/balanced/powerful) and models.default feed the router at every stage; security.sandbox.mode (none/policy/container) bounds every execute_command the pipeline issues.

Project-level vs user-level

The loader selects one config file (first match wins): NEXUS_CONFIG_PATH, then ./.nexus-agents/nexus-agents.yaml or ./nexus-agents.yaml, then ~/.nexus-agents/nexus-agents.yaml. It does not merge a project file with a user file. Per-setting environment variables overlay the loaded file at consumption time, so use them — not a second file — for local overrides.

Commit the project file for shared, reproducible choices: models.tiers/default, routing weights, gate modes (NEXUS_POLICY_GATE_MODE, NEXUS_FIREWALL_POLICY), and security.sandbox.mode. Keep machine-specific settings out of the repo and set them per-user via env: API keys (ANTHROPIC_API_KEY, …), NEXUS_DATA_DIR, NEXUS_SANDBOX_ROOT, and NEXUS_BILLING_MODE. Committed config defines the team’s pipeline; each env var wins over it locally.

# nexus-agents.yaml (committed)
models:
  default: claude-sonnet
  tiers:
    powerful: [claude-opus, codex-5.3]
security:
  sandbox: { mode: policy }

# each teammate, locally (not committed)
export ANTHROPIC_API_KEY=...
export NEXUS_BILLING_MODE=api   # cost-aware on a personal key
export NEXUS_DATA_DIR=/scratch/nexus

Related Documentation

• CLI Usage - Use configuration in CLI commands
• Workflow Templates - Create custom workflows
• Architecture Overview - Understand system design