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

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=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). Users without a saved key fall back to the default credential from the config file.

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

# 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.90
CONTEXT_KEEP_RECENT=8

# Persona
NAVI_PERSONA_FILE=persona.txt
NAVI_DEFAULT_PROFILE_ID=navi_code