Configuration

All configuration is loaded from .env via pydantic-settings (navi/config.py). The global settings object is imported everywhere as from navi.config import settings.

General

LLM

Without llm.json (a bare dev checkout), Navi talks to one host built from OLLAMA_HOST/OLLAMA_API_KEY and the per-profile model list, exactly as before.

LLM routing (llm.json)

llm.json (repo root, committed — it holds no secrets) declares the hosts and the ordered chains of models to try on them. Backups are a property of the file, not of the profile: when the cloud is unreachable or out of quota, the next entry answers and a local model keeps Navi usable.

{
  "targets": {
    "cloud": { "host": "https://ollama.com", "api_key_env": "OLLAMA_API_KEY" },
    "home":  { "host": "http://192.168.1.129:11434" }
  },
  "routes": {
    "default": [
      { "model": "glm-5.3-flash:cloud", "target": "cloud", "context_window": 131072 },
      { "model": "qwen3.6:35b-128k", "target": "home", "context_window": 131072,
        "options": { "presence_penalty": 0.0 } }
    ],
    "embedding": [
      { "model": "nomic-embed-text:latest", "target": "home" },
      { "model": "nomic-embed-text:latest", "target": "cloud" }
    ]
  },
  "probe": { "interval_sec": 60, "timeout_sec": 5 }
}

• targets — named hosts. api_key_env names an environment variable and is read from os.environ or from the .env file itself (the process environment does not receive it), so the deploy branch's .env does not change. Any name works — that is how a second Ollama Cloud account joins a route: give it its own target and its own variable, e.g. cloud2 with "api_key_env": "OLLAMA_API_KEY_2", then list both in the chain. A literal api_key is also accepted, but llm.json is committed: keep secrets in .env and reference them by name.
• routes — ordered chains; the first entry is the primary, the rest are backups. context_window caps num_ctx for that model and drives the compressor's window, and options are merged over the global Ollama options. When every entry of a route serves the same budget, give them the same context_window: the compressor counts against whichever entry is active, so an uneven window silently changes how much history a failover can hold.
• probe — how often the background prober re-checks a degraded target.

A profile joins a route with "llm_route": "default" (see profiles.md). No llm_route means the profile's model list is used, each name resolved to the target the config says serves it.

What fails over, and when

LLM_COMPLETE_RETRIES applies only to the last entry left: a dead cloud model must not cost retries × LLM_STREAM_FIRST_CHUNK_TIMEOUT on every call while a healthy local model sits one step down the chain.

For streaming calls the first chunk is awaited before anything is yielded, so a failure is caught before output reaches the client. A stream that breaks after the first chunk is not retried — the turn fails rather than mixing two partial answers from two hosts.

Switching back

Switch-back never happens mid-turn. RouteHealth probes only degraded targets (once per probe.interval_sec, with probe.timeout_sec), using list() for reachability/auth, show() for a missing model, and a one-token chat for a quota cooldown. When the probe reports the primary healthy again, the next user turn starts on it; the running turn keeps the host it began on.

/health reports which entry serves each route and why a target is degraded — see api.md. POST /admin/ollama/clear-blacklists forgets all recorded failures (and restarts every route at its primary) after a config fix.

If the file is broken

A missing llm.json (or LLM_CONFIG_FILE="") means "no routes" and the legacy single-host path. A malformed file raises LLMConfigError at startup, naming the file and the offending target or route: silently routing to the wrong host is worse than refusing to start.

Web Search

Web search is not a Settings field: it is the navi-web MCP server. Its settings reach it through mcp_servers.d/navi-web.json, which maps SEARXNG_URL (and, optionally, BRAVE_SEARCH_API_KEY) from .env into the server's own environment. SEARXNG_URL is therefore a real .env setting — a self-hosted SearXNG, e.g. http://localhost:8888 — just not one Navi itself reads. Without it the server falls back to DuckDuckGo scraping. See mcp.md.

LLM Timeouts

Large contexts can take 60–90 s to prefill; LLM_STREAM_FIRST_CHUNK_TIMEOUT=90 covers the common case for local Ollama. Increase (e.g. 180) for very large contexts or slow GPUs; reduce for fast cloud endpoints.

Security / Sandboxing

settings.fs_allowed_paths_list and settings.terminal_allowed_commands_list are computed properties that parse the comma-separated strings into lists.

settings.terminal_user_allowed_commands_list — computed property parsed from the comma-separated string.

Database

Server / deployment shape

Swarm / hive registry

Navi instances can form a swarm: each announces itself to a tiny registry service ("hive", see hive/README.md) running on the main server; agents ask the book who is alive and where. The registry is never a blocking dependency — with HIVE_URL empty, or with the hive down, everything else works and the agent is simply told the book is unreachable.

See deploy/README.md for the one-command server deployment (bash deploy/install.sh): dockerized PostgreSQL + systemd + navi-code in PATH, web UI and auth off by default.

Logging

Tools

MCP user_key (BYOK)

Per-server JSON config (mcp_servers.d/<name>.json) — where a user's personal credential is injected. Details in mcp.md.

// HTTP server: key goes into an Authorization-style header
{ "transport": "streamable_http", "url": "https://…",
  "user_key": { "header": "Authorization", "prefix": "Bearer " } }

// stdio server: key goes into an env var
{ "transport": "stdio", "command": "uvx", "env": { "API_KEY": "default" },
  "user_key": { "env": "API_KEY" } }

Keys are stored Fernet-encrypted (NAVI_AUTH_ENCRYPTION_KEY, see Authentication above). A user without a saved key is served the default credential from the config file only if their role is admin; every other role is refused, and the server is left out of their tool list entirely. See mcp.md.

Session files

Public URL

Context compression

Gmail

Authentication (gnexus-auth OAuth)

Full auth setup guide: docs/auth.md.

Web push (PWA)

Push notifications fire when an agent turn (or a scheduled recall) completes and no browser tab is watching that session. See docs/push.md.

Synapse source

Without both URL and key, Synapse-linked outgoing events are silently skipped and the UI disables Synapse-linked options (source_ready: false). See docs/synapse.md.

Persona

Recommended: use NAVI_PERSONA_FILE=persona.txt rather than inlining the persona in .env, because multi-line values don't parse reliably in .env files.

The _load_persona_from_file validator reads the file on startup if NAVI_PERSONA is empty and NAVI_PERSONA_FILE is set.

Parallelism and background tasks

See docs/tasks.md for the full mechanism.

When a terminal (run), code_exec or ssh_exec call is detached and the agent did not pass timeout, the executor lifts it to 300 s for the detached run only — the tools' short foreground defaults (20/30/60 s) would otherwise mark long commands "completed" with partial output while the process is still running.

Example .env

# LLM — Ollama (primary)
OLLAMA_HOST=http://localhost:11434
OLLAMA_API_KEY=
OLLAMA_DEFAULT_MODEL=gemma4:31b-cloud
OLLAMA_NUM_CTX=65536
OLLAMA_THINK=true
OLLAMA_REQUEST_TIMEOUT=30

# LLM routing (hosts + backup chains). Committed; no secrets inside:
# LLM_CONFIG_FILE=llm.json

# LLM — OpenAI (optional)
# OPENAI_API_KEY=sk-...
# OPENAI_MODEL=gpt-4
# OPENAI_BASE_URL=https://api.openai.com/v1

# Database (PostgreSQL 15+ with pgvector)
DATABASE_URL=postgresql://user:pass@localhost:5432/navidb

# Security / sandboxing
FS_ALLOWED_PATHS=*
TERMINAL_ALLOWED_COMMANDS=*

# Misc
LOG_LEVEL=INFO
TOOLS_DIR=tools
SHARE_FILE_MAX_SIZE_MB=1024
SESSION_MESSAGES_WINDOW=1000
WS_REPLAY_BUFFER_SIZE=500

# Context compression
CONTEXT_COMPRESSION_ENABLED=true
CONTEXT_COMPRESSION_THRESHOLD=0.90
CONTEXT_KEEP_RECENT=8

# Persona
NAVI_PERSONA_FILE=persona.txt
NAVI_DEFAULT_PROFILE_ID=navi_code