Configuration: Providers, Models, and Presets

This page is the field-by-field reference for how navin chooses a provider, a model, and a named configuration. Use it together with:

Config file: ~/.navin/config.json (created on first navin webui or CLI run). Prefer environment variables for secrets (${OPENROUTER_API_KEY}, etc.).

Mental Model

Three layers work together:

1. Provider (providers.<name>) - credentials and endpoint (API key, apiBase, OAuth, proxy).
2. Model configuration / preset (modelPresets.<name>) - a named pair of provider + model, plus generation settings.
3. Active selection (agents.defaults.modelPreset) - which preset the agent uses for normal turns.

In the WebUI this maps to:

A configuration name (label) is only a human-readable shortcut in the chat model selector. Prefer names that describe the model or its role, for example Claude Sonnet, GLM 5.2, or Everyday coding - not free-form task titles unrelated to the model.

Quick Start (WebUI)

1. Open Settings → Providers and add an API key (or local apiBase) for the service you use.
2. Open Settings → Models.
3. Click Add model, pick the provider, pick a model ID from the catalog (or type one), give a clear configuration name, then Save.
4. Select that configuration as Current configuration so it shows the Active badge.
5. Optionally open Task routing and assign cheaper or stronger presets to roles (fast, dev, deep, …). Matching workflows (/forge, /blueprint, studios, audits…) pick that model automatically; you can also switch with /pilot <task>.

Verify outside the chat:

navin status
navin agent -m "Hello!"

Providers

Shape

{
  "providers": {
    "openrouter": {
      "apiKey": "${OPENROUTER_API_KEY}"
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "ollama": {
      "apiBase": "http://127.0.0.1:11434/v1"
    },
    "custom": {
      "apiKey": "${CUSTOM_API_KEY}",
      "apiBase": "https://api.example.com/v1"
    }
  }
}

Fields

Common provider names

Use the registry name in presets (provider: "openrouter"), not the display label.

Full matching rules and failure tables: providers.md. Pasteable recipes: provider-cookbook.md. Guided Ollama install: guides/configure-ollama-local.md.

Bedrock notes

AWS Bedrock uses the native Converse API. Prefer AWS_BEARER_TOKEN_BEDROCK or your usual AWS credential chain, set provider: "bedrock", and use Bedrock model IDs (for example anthropic.claude-sonnet-4-5-v1:0). Do not mix OpenRouter-style IDs with the Bedrock provider.

Model Configurations (Presets)

Shape

{
  "modelPresets": {
    "primary": {
      "label": "Claude Sonnet",
      "provider": "openrouter",
      "model": "anthropic/claude-sonnet-4.5",
      "maxTokens": 8192,
      "contextWindowTokens": 65536,
      "temperature": 0.1,
      "reasoningEffort": "medium"
    },
    "economy": {
      "label": "GLM 5.2",
      "provider": "openrouter",
      "model": "z-ai/glm-5.2",
      "maxTokens": 4096,
      "contextWindowTokens": 65536,
      "temperature": 0.1
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "economy"
    }
  }
}

Fields

Implicit default preset

If you do not create named presets, navin builds an implicit configuration named default from agents.defaults.model, provider, maxTokens, and related fields. Named presets are clearer for switching and fallbacks.

Selecting the active configuration

{
  "agents": {
    "defaults": {
      "modelPreset": "economy",
      "provider": "auto",
      "model": "…"
    }
  }
}

• Prefer modelPreset pointing at a key under modelPresets.
• Direct provider + model on agents.defaults still work for older configs and for the reserved default preset.
• In chat, switch models from the model selector or with commands such as /model / /pilot depending on setup.

Task Routing (modelRoutes)

Assign a named model configuration (preset key under modelPresets) to each kind of work so expensive frontier models are only used when needed. Values are preset names such as primary or economy - not free-form task titles.

{
  "modelRoutes": {
    "deep": "primary",
    "dev": "primary",
    "fast": "economy",
    "search": "economy",
    "plan": "primary",
    "review": "primary",
    "security": "primary",
    "docs": "economy"
  }
}

Automatic application

When a message starts with a workflow slash command, navin selects the routed preset for that turn (it wins over the chat model picker for that turn). Plain chat without a workflow command keeps the active / thread model.

Configure the map in Settings → Models → Task routing (same as modelRoutes in config).

Manual switch (/pilot)

In chat: /pilot lists routes; /pilot review (for example) switches the session preset to the one assigned to that role (in memory until restart or another switch). Prefer automatic routing for workflows; use /pilot when you want to stay on a role across free-form turns.

Model Fallbacks

When the active provider fails or rate-limits, navin can try other presets in order:

{
  "agents": {
    "defaults": {
      "modelPreset": "primary",
      "fallbackModels": ["economy", "localSmall"]
    }
  }
}

• Entries are preset names, not raw model IDs (unless you use an inline object; see providers.md).
• fallbackModels lives under agents.defaults, not inside each preset.
• Context is built for the smallest window in the active chain so every candidate can accept the same prompt.

Step-by-step: guides/configure-model-fallback.md.

End-to-End Example

OpenRouter as gateway, one strong preset, one cheap preset, routing, and fallback:

{
  "providers": {
    "openrouter": {
      "apiKey": "${OPENROUTER_API_KEY}"
    }
  },
  "modelPresets": {
    "strong": {
      "label": "Claude Sonnet",
      "provider": "openrouter",
      "model": "anthropic/claude-sonnet-4.5",
      "maxTokens": 8192,
      "contextWindowTokens": 65536,
      "temperature": 0.1
    },
    "fast": {
      "label": "GLM 5.2",
      "provider": "openrouter",
      "model": "z-ai/glm-5.2",
      "maxTokens": 4096,
      "contextWindowTokens": 65536,
      "temperature": 0.1
    }
  },
  "modelRoutes": {
    "deep": "strong",
    "dev": "strong",
    "fast": "fast",
    "docs": "fast"
  },
  "agents": {
    "defaults": {
      "modelPreset": "fast",
      "fallbackModels": ["strong"]
    }
  }
}

Naming Rules That Avoid Confusion

• Configuration label: what you see in the list (Claude Sonnet, GLM 5.2).
• Preset key: stable id in JSON (strong, fast) - used by routes and fallbacks.
• Provider name: registry id (openrouter, anthropic).
• Model id: exact string the provider API accepts (anthropic/claude-sonnet-4.5 on OpenRouter vs claude-sonnet-4-5 on Anthropic direct).

Never mix a key from provider A with a model id that only exists on provider B. That is the most common first-run failure.

Related Agent Defaults

Useful neighbors under agents.defaults (not exhaustive):

Environment-level overrides: environment-variables.md.

Gateway Heartbeat

When navin gateway runs, heartbeat periodically reads <workspace>/HEARTBEAT.md, runs quiet workspace checks, and only notifies a chat target when something actionable appears.

Default shape under gateway.heartbeat:

{
  "gateway": {
    "heartbeat": {
      "enabled": true,
      "interval_s": 1800
    }
  }
}

Use heartbeat for low-noise watch loops. Use scheduled automations when every run should produce a visible reminder. Details: automations.md.

Langfuse Observability

navin can wrap supported OpenAI-compatible calls with Langfuse when the langfuse package is installed and these env vars are set before startup:

• LANGFUSE_SECRET_KEY
• LANGFUSE_PUBLIC_KEY
• LANGFUSE_BASE_URL (for example https://cloud.langfuse.com)

Full install and verification steps: guides/configure-langfuse-observability.md. Recipe notes: provider-cookbook.md.

Checklist

1. Provider block has a valid key or local apiBase.
2. Preset provider matches that block’s registry name.
3. Preset model is a real ID for that provider (use the WebUI catalog when unsure).
4. agents.defaults.modelPreset points at an existing preset key (or default).
5. Route and fallback entries only reference existing preset keys.
6. navin agent -m "Hello!" succeeds before debugging chat channels.

See Also

• providers.md - matching, gateways, local servers, diagnosis
• provider-cookbook.md - copy-paste recipes
• guides/configure-model-fallback.md
• guides/configure-openai-compatible-provider.md
• my-tool.md - runtime self-inspection