Configuration

Reference for all environment variables and settings.

Config resolution

ntrp resolves configuration in this order (highest priority first):

1. Environment variables — NTRP_* prefix or standard provider key names
2. .env files — loaded from ~/.ntrp/.env and ./.env (project directory)
3. Settings file — ~/.ntrp/settings.json (persisted via TUI settings)
4. Auto-detection — models resolved from available provider keys

LLM providers

Set at least one provider API key, or connect the OpenAI Codex provider with browser sign-in from the TUI. ntrp auto-selects models based on what’s available.

Provider	Setup	Chat model	Memory model	Embedding model
Anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-6	claude-sonnet-4-6	—
OpenAI API	OPENAI_API_KEY	gpt-5.2	gpt-5.2	text-embedding-3-small
OpenAI Codex	Browser sign-in in /connect or /settings	openai-codex/gpt-5.5	openai-codex/gpt-5.4-mini	—
Google	GEMINI_API_KEY	gemini-3.1-pro-preview	gemini-3-flash-preview	gemini-embedding-001

Claude Pro/Max OAuth is not supported. We will not integrate it until Anthropic officially allows third-party applications to use subscription-based OAuth.

OpenAI Codex uses OpenAI browser sign-in, not an API key. Tokens are stored locally in ~/.ntrp/openai-codex-auth.json with 0600 permissions and refreshed automatically.

Override auto-detection with explicit model IDs:

export NTRP_CHAT_MODEL=claude-sonnet-4-6
export NTRP_MEMORY_MODEL=claude-haiku-4-5
export NTRP_EMBEDDING_MODEL=text-embedding-3-small

Embedding is optional. Without it, vector search is disabled but ntrp still works with full-text search.

Server

Variable	Default	Description
NTRP_HOST	127.0.0.1	Server bind address
NTRP_PORT	6877	Server port

Features

Variable	Default	Description
NTRP_MEMORY	true	Enable persistent memory
NTRP_DREAMS	false	Enable cross-domain dream generation
NTRP_CONSOLIDATION_INTERVAL	30	Minutes between consolidation runs (builtin automation)
NTRP_GMAIL	false	Enable Gmail integration
NTRP_GMAIL_DAYS	30	Days of email history to index
NTRP_CALENDAR	false	Enable Google Calendar

Optional integrations

Variable	Description
EXA_API_KEY	Exa.ai API key for web search (required only when WEB_SEARCH=exa)
WEB_SEARCH	Web provider mode: auto (default), exa, ddgs, or none
TELEGRAM_BOT_TOKEN	Telegram notifications

Agent behavior

Variable	Default	Description
NTRP_MAX_DEPTH	8	Max agentic recursion depth
NTRP_REASONING_EFFORT	unset	Optional model-specific reasoning effort, e.g. low, medium, high, xhigh, or whatever the selected model advertises
NTRP_DEFERRED_TOOLS	true	Hide infrequent integration/action tool schemas until the agent loads them with load_tools

Deferred tools reduce prompt size and improve cache stability. Gmail, calendar, Slack, automation, background-task, notification, directive, and MCP tools are loaded on demand. Always-visible tools include shell/file access, memory recall/write tools, web search/fetch, research, skills, current time, and load_tools itself.

Authentication

On first ntrp-server serve, an API key is generated and printed. The server stores only a salted SHA-256 hash — the plaintext key is never persisted.

# Generate a new key
ntrp-server serve --reset-key

The TUI client stores the key in your OS keychain (macOS Keychain, Linux libsecret). Fallback: ~/.ntrp/settings.json.

Variable	Description
NTRP_WEBHOOK_TOKEN	Separate token for webhook endpoints (email notifications)

Custom models

See Custom Models for registering OpenRouter, Ollama, vLLM, or any OpenAI-compatible endpoint.

Settings file

~/.ntrp/settings.json stores persisted configuration. Fields set here act as defaults that environment variables can override.

{
  "chat_model": "claude-sonnet-4-6",
  "memory_model": "claude-sonnet-4-6",
  "embedding_model": "text-embedding-3-small",
  "api_key_hash": "a1b2c3:..."
}