Configuration

Nestor reads its configuration from a JSON file under $NESTOR_HOME (default ~/.nestor) and from environment variables. This page documents every supported field plus the precedence rules between sources.

Config file

Location: $NESTOR_HOME/config.json. Created interactively by npx nestor-sh install. The full schema:

{
  "version": "3.5.0",
  "server": {
    "studioPort": 3100,
    "apiPort": 3101,
    "dataDir": "~/.nestor",
    "host": "127.0.0.1"
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "defaultModel": "claude-sonnet-4-6",
      "baseURL": null
    },
    "openai": {
      "apiKey": "sk-...",
      "defaultModel": "gpt-4o",
      "projectId": null,
      "baseURL": null
    },
    "google": {
      "apiKey": "...",
      "defaultModel": "gemini-2.0-pro"
    },
    "grok": {
      "apiKey": "xai-...",
      "defaultModel": "grok-3"
    },
    "mistral": {
      "apiKey": "...",
      "defaultModel": "mistral-large-latest"
    },
    "ollama": {
      "baseURL": "http://localhost:11434",
      "defaultModel": "llama3.2"
    },
    "openrouter": {
      "apiKey": "sk-or-...",
      "defaultModel": "anthropic/claude-sonnet-4-6"
    }
  },
  "approval": {
    "mode": "smart",
    "allowlist": ["file_read", "file_list", "web_fetch"],
    "manualForRiskAtLeast": "high"
  },
  "budgets": {
    "perRunUsd": 5.00,
    "perDayUsd": 50.00,
    "warningPct": 80,
    "hardCap": true
  },
  "telemetry": {
    "enabled": true,
    "otelEndpoint": null,
    "retainDays": 30
  },
  "memory": {
    "governance": false,
    "decayRate": 0.05,
    "maxAgentMemoryMb": 100
  },
  "personaV2": false,
  "feedback": {
    "promptAfterRun": true
  }
}

Quick edits

You can edit the file directly, or use the CLI helpers (which preserve formatting and validate the schema):

npx nestor-sh config show              # dump current config
npx nestor-sh config set approval.mode manual
npx nestor-sh config get budgets.perRunUsd

Environment variables

Environment variables override file values for the lifetime of the process. They're useful for CI, sandboxed installs, and running multiple Nestor instances against different homes.

Variable	Effect	Default
`NESTOR_HOME`	Data directory (DB, logs, skills)	`~/.nestor`
`NESTOR_STUDIO_PORT`	Studio dashboard port	`3100`
`NESTOR_API_PORT`	Underlying API server port	`3101`
`NESTOR_PERSONA_V2`	Enable BMAD+ persona stack (Atlas, Forge, Sentinel, Nexus, Shadow)	`0`
`NESTOR_NATIVE`	Set to `disabled` to force JS fallback for the Rust security core	auto
`NESTOR_LOG_LEVEL`	`error` \| `warn` \| `info` \| `debug` \| `trace`	`info`
`NESTOR_TELEMETRY`	Set to `0` to disable all telemetry collection	`1`
`ANTHROPIC_API_KEY`	Override config file Anthropic key	—
`OPENAI_API_KEY`	Override config file OpenAI key	—
`OPENAI_PROJECT_ID`	For OpenAI project-scoped keys	—
`GEMINI_API_KEY`	Google AI Studio key	—
`GROK_API_KEY`	xAI key	—
`MISTRAL_API_KEY`	Mistral key	—
`OLLAMA_BASE_URL`	Custom Ollama endpoint	`http://localhost:11434`
`OPENROUTER_API_KEY`	OpenRouter key	—

LLM providers

Each provider section in config.json follows the same shape:

"providers": {
  "<provider>": {
    "apiKey": "<your key>",
    "defaultModel": "<model id>",
    "baseURL": null,                // optional override for self-hosted gateways
    "extraHeaders": {}              // optional, e.g. for HTTP proxies
  }
}

Provider switching mid-mission is supported via the HotSwapAdapter. Use /model <name> in the shell or call runtime.getHotSwap().swap(adapter, reason) programmatically.

Default model selection

If an agent doesn't specify a model, the runtime picks the first provider with a configured key in this order:

Anthropic Claude (cheapest reliable tool-use)
OpenAI GPT-4o
Google Gemini 2.0 Pro
Grok 3
Mistral Large
OpenRouter (300+ models)
Ollama (local fallback, no key required)

Approval modes

Three modes control when Nestor pauses to ask the user before executing a tool:

Mode	Behavior	When to use
`off`	Never ask. All tools execute autonomously.	CI, fully-trusted environments
`smart` (default)	Ask only for high/critical-risk tools (`shell_exec`, `file_write`, destructive HTTP)	Daily use
`manual`	Ask for every tool except those in `allowlist`	First runs, paranoid mode

Toggle at runtime in the shell with /approve off|smart|manual.

Budgets

Two cost ceilings guard against runaway spend:

"budgets": {
  "perRunUsd": 5.00,    // per agent run
  "perDayUsd": 50.00,   // total across all agents
  "warningPct": 80,     // emit budget_warning event at this %
  "hardCap": true       // abort run when reached (false = warn only)
}

Per-agent overrides:

npx nestor-sh agent config <agent-name> --budget-per-run-usd 1.00

Telemetry

Local-only by default. Stores OTel-style traces in SQLite for the Studio dashboard. Nothing is sent off-machine unless you set otelEndpoint:

"telemetry": {
  "enabled": true,
  "otelEndpoint": "http://otel-collector:4318",  // optional
  "retainDays": 30,                              // auto-prune older traces
  "samplingRate": 1.0                            // 1.0 = 100% sampled
}

Disable globally with NESTOR_TELEMETRY=0.

Memory governance

Off by default. When enabled, agent memory entries are subject to:

Decay — relevance scores age over time at decayRate per day.
Quota — per-agent cap at maxAgentMemoryMb.
PII redaction — entries are passed through the secret-redaction layer before storage.

Recommended for multi-tenant deployments and long-running daemons. See Security for the full memory governance model.

Precedence rules

When multiple sources define the same value, the highest priority wins:

CLI flags — --port, --data-dir, etc. (per command)
Environment variables — NESTOR_*, provider keys
Config file — $NESTOR_HOME/config.json
Built-in defaults — defined in packages/cli/src/utils/config.ts

Sensitive values (API keys) are never logged. The Rust security core's secret-redaction layer applies to all outbound logs and tool results.

✎ Edit this page on GitHub · Last updated 2026-04-26