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.

LLM

For direct Ollama Cloud access without fallback: set OLLAMA_HOST=https://ollama.com and OLLAMA_API_KEY=<key>.

Web Search

Multi-server fallback (OLLAMA_BACKENDS_FILE)

When OLLAMA_BACKENDS_FILE points to a JSON file, Navi uses FallbackOllamaBackend instead of the single-server backend. The file contains an ordered list of servers:

[
  { "host": "https://ollama.com", "api_key": "ollama_..." },
  { "host": "http://localhost:11434" }
]

Each profile's model field is also a priority list (see docs/profiles.md). The fallback algorithm tries all combinations in a nested loop:

for each server (in order):
    for each model (in order):
        try → success: use this server+model
        LLMConnectionError → blacklist server, skip remaining models, try next server
        LLMModelNotFoundError → blacklist (server, model) pair, try next model
raise if all exhausted

Blacklisting is in-memory (module-level sets in navi/llm/fallback.py) and persists until server restart. A dead server or missing model is only probed once per process lifetime, avoiding latency spikes from repeated retries.

For streaming calls, the first chunk is awaited before yielding, so connection/model errors are caught before any output is sent to the client — clean retry with no partial response.

LLM Timeouts

Large contexts can take 60–90 s to prefill; LLM_STREAM_FIRST_CHUNK_TIMEOUT=180 is a safe upper bound for local Ollama. Reduce if using a fast cloud endpoint.

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

Logging

Tools

Session files

Public URL

Context compression

Gmail

Authentication (gnexus-auth OAuth)

Full auth setup guide: docs/auth.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.

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

# Multi-server fallback mode (overrides OLLAMA_HOST/API_KEY):
# OLLAMA_BACKENDS_FILE=ollama_backends.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.70
CONTEXT_KEEP_RECENT=8

# Persona
NAVI_PERSONA_FILE=persona.txt