Configuration

Config Files

lynox uses two config files, merged at startup:

File	Scope	Purpose
~/.lynox/config.json	User	API key, model, personal preferences
.lynox/config.json	Project	Project-specific overrides (safe subset only)

Project configs cannot override security-sensitive fields like API keys or vault settings.

Key Settings

LLM Provider

{
  "provider": "anthropic",
  "api_base_url": "https://api.mistral.ai/v1",
  "openai_model_id": "mistral-medium-2604"
}

Setting	Values	Default
provider	anthropic (tested), openai (Mistral tested; Ollama / LM Studio / OpenAI / Groq / vLLM / Gemini experimental), custom (Anthropic-compat proxy — experimental), vertex (legacy — experimental, not usable in the Docker image; see Legacy: Google Vertex AI)	anthropic
api_base_url	Endpoint for provider: openai or custom	—
openai_model_id	Model ID for provider: openai (e.g. mistral-medium-2604, llama3.2)	—

Only anthropic and openai with the Mistral endpoint are exercised on every release. The other paths work in principle but are not regularly tested — see LLM Providers for full details.

Prefer pinned model IDs (mistral-medium-2604) over floating tags like mistral-medium-latest — pins keep behavior reproducible across silent provider snapshot rolls. See LLM Providers — Mistral for the rationale.

Model & Intelligence

{
  "default_tier": "balanced",
  "thinking_mode": "adaptive",
  "effort_level": "high"
}

Setting	Values	Default
default_tier	fast, balanced, deep — the band the main chat runs on (also picked visually via Settings → LLM → Main chat model). Background tasks and subagents auto-route across bands regardless	balanced
thinking_mode	adaptive, disabled	adaptive
effort_level	low, medium, high, max	high
balanced_model	Which Claude Sonnet build serves the balanced tier (Anthropic provider). Set claude-sonnet-5 to opt into the 1M-token context window; leave unset for the default	default Sonnet
compaction_token_budget	Token budget that triggers automatic thread summarization (min 32000)	150000
context_cost_log	Opt-in: write a content-free per-turn context-composition log to the data dir (diagnostics)	false

The tiers are provider-agnostic capability bands (fast = cheapest/quickest, balanced = default workhorse, deep = reasoning-heavy); each resolves to a concrete model for your active provider. The legacy Anthropic-brand names (haiku/sonnet/opus) are still accepted and normalized automatically, so existing configs keep working.

• deep — Most capable, reasoning-heavy, higher cost
• balanced — Default workhorse (recommended)
• fast — Quickest, lowest cost

Cost Limits

{
  "max_session_cost_usd": 50.00,
  "max_daily_cost_usd": 100.00,
  "max_monthly_cost_usd": 500.00
}

lynox tracks token usage per session, day, and month. Defaults shown above are the engine’s built-in ceilings; lower them in config.json if you want a tighter budget. When a limit is reached, it pauses and asks before continuing.

Web Search

Web search is included out of the box via SearXNG (bundled in docker-compose). No configuration needed — it works automatically.

{
  "search_provider": "searxng",
  "searxng_url": "http://searxng:8080"
}

Setting	Values	Default
searxng_url	SearXNG instance URL — leave unset to fall back to DuckDuckGo HTML scrape (best-effort)	—

See SearXNG setup for details.

Memory

{
  "memory_extraction": true,
  "memory_half_life_days": 90
}

• memory_extraction — Automatically extract and store insights from conversations
• memory_half_life_days — How quickly memories fade (higher = longer retention)

Knowledge Graph

{
  "knowledge_graph_enabled": true,
  "embedding_provider": "onnx",
  "embedding_model": "all-minilm-l6-v2"
}

Setting	Values	Default
knowledge_graph_enabled	true, false	true
embedding_provider	onnx, local	onnx
embedding_model	all-minilm-l6-v2, multilingual-e5-small, bge-m3	all-minilm-l6-v2

Use multilingual-e5-small or bge-m3 if you primarily work in non-English languages.

Changeset Review

{
  "changeset_review": true
}

When enabled, a file write is backed up and then applied at once — it is not held back. In exchange the diff preview and the permission prompt are skipped for write_file and edit_file, and the review happens after the run: a diff you can accept, roll back, or roll back in part. So this setting chooses when you review a write, not whether the write waits for you. It has no effect on autonomous runs or without an active workspace, and it does not cover writes a shell command makes. Useful for high-autonomy setups where you still want a final check.

Backups

{
  "backup_retention_days": 30,
  "backup_encrypt": true,
  "backup_gdrive": false
}

backup_schedule is accepted and ignored — it used to stand in this example beside the keys that work, with no hint that nothing reads it. Automatic backups are a trigger, not a config key.

See Backups for details.

Security

{
  "enforce_https": false
}

When enforce_https is true, all outbound HTTP requests from tools are blocked — only HTTPS is allowed.

Network Policy

{
  "network_policy": "allow-all",
  "network_allowed_hosts": []
}

Controls the agent’s outbound network access for the http_request, api_setup, and web_research tools:

• allow-all (default) — no restriction; existing behavior.
• deny-all — block all outbound requests from these tools.
• allow-list — allow only the hosts listed in network_allowed_hosts.
• guarded — surface-aware lockdown: discovery surfaces stay open, while full-control requests reach only the vetted baseline hosts, the operator floor, and hosts you have explicitly accepted for a connected API.

What network_policy does not cover

It is a policy over those three tools, not over the machine. Even on deny-all, outbound traffic still leaves the container on paths this setting never sees:

• the engine’s own connections — the LLM provider, mail, push notifications, backups, and connected Google services;
• anything a shell command starts. The bash tool is not one of the three gated tools, so a program it runs — or writes and then runs — reaches the network normally.

So read deny-all as “these three tools will refuse”, not as “this machine is offline”. If you need the stronger property, it has to come from the layer below: run the container on a network that cannot route outbound (for example a local model plus an egress-filtered Docker network), because no setting inside the engine can promise it.

Override with the LYNOX_NETWORK_POLICY and LYNOX_NETWORK_ALLOWED_HOSTS (comma-separated) environment variables.

Extensions

{
  "agents_dir": "./agents",
  "manifests_dir": "./workflows"
}

See Extension Points for details.

Experience Mode

{
  "experience": "business"
}

• business — Optimized for business users (default)
• developer — Shows more technical details and options (experimental)

Environment Variables

Environment variables always take the highest precedence. The full priority chain for secrets is:

1. Environment variable (e.g. ANTHROPIC_API_KEY) — always wins, useful for overriding stale vault entries
2. Encrypted vault (~/.lynox/vault.db) — persisted via Web UI or ask_secret
3. Config file (~/.lynox/config.json) — lowest priority

When an env var overrides a vault value, a log message is printed: [lynox] ANTHROPIC_API_KEY env var overrides vault value.

Credentials can also be stored interactively via lynox’s secure ask_secret dialog — the agent will prompt you when it needs a key, and the value goes directly to the encrypted vault without ever entering the chat. See Security for details.

LLM Provider

Variable	Purpose
ANTHROPIC_API_KEY	Claude API key (Anthropic provider). Anthropic-only — does NOT serve provider: openai.
ANTHROPIC_BASE_URL	Base URL for provider: openai or custom (e.g. https://api.mistral.ai/v1)
LYNOX_LLM_PROVIDER	LLM provider: anthropic (default), openai, custom (Anthropic-compat proxy — experimental), vertex (legacy — experimental, not usable in the Docker image)
LYNOX_BALANCED_MODEL	Which Claude Sonnet build serves the balanced tier. Set claude-sonnet-5 to opt into the 1M-token context window; unset keeps the default.

OpenAI-Compatible

Variable	Purpose
MISTRAL_API_KEY	Mistral API key — primary slot for provider: openai with the Mistral endpoint (natively supported).
OPENAI_API_KEY	Bearer for generic OpenAI-compatible endpoints (experimental). Secondary slot — MISTRAL_API_KEY is also accepted. Leave blank for local Ollama / LM Studio without auth.
OPENAI_MODEL_ID	Model ID, e.g. mistral-medium-2604 (prefer pinned over -latest), llama3.2, gpt-4o, llama-3.3-70b-versatile
ANTHROPIC_BASE_URL	Provider base URL — see LLM Providers for the value per backend

Legacy: Google Vertex AI (experimental)

provider: vertex is no longer offered by the installer. The env vars below are still read, but Vertex needs the optional package @anthropic-ai/vertex-sdk, which the Docker image does not include. In the image a Vertex setup fails when the engine starts; it only works in an npm install where you add the package yourself, and that path is not regularly tested. New installs should use Anthropic direct or Mistral.

Variable	Purpose
GCP_PROJECT_ID	GCP project ID
CLOUD_ML_REGION	Vertex region, e.g. europe-west4, us-east5
GOOGLE_APPLICATION_CREDENTIALS	Path to GCP service-account JSON

Web Search

Variable	Purpose
SEARXNG_URL	SearXNG instance URL (included in docker-compose, recommended). Without it, web_research falls back to a best-effort DuckDuckGo HTML scrape.

Network & Server

Variable	Purpose
LYNOX_HTTP_PORT	HTTP API port (default: 3000 in Docker, 3100 locally)
LYNOX_HTTP_SECRET	Bearer token for HTTP API authentication
LYNOX_WEBUI_URL	Web UI URL (default: http://localhost:5173)
LYNOX_TRUST_PROXY	Trust X-Forwarded-For for client-IP resolution (default false). Set true only when lynox runs behind a reverse proxy you control — otherwise rate-limiting and the IP allowlist key on the proxy’s address instead of the real client.
LYNOX_TRUSTED_PROXY_HOPS	With LYNOX_TRUST_PROXY=true, how many trailing X-Forwarded-For entries your proxy chain appends (default 1). The client IP is read from that many hops in from the right, never the spoofable leftmost entry.

Security & Storage

Variable	Purpose
LYNOX_VAULT_KEY	Encryption key for the secret vault
LYNOX_DATA_DIR	Override data directory (default: ~/.lynox)
LYNOX_WORKSPACE	CLI only: an existing directory that bash starts in and that the file tools are limited to (besides /tmp and the artifacts directory; reads also from /app); a path that does not exist is ignored; unset, file writes go to the workspace root. The server ignores it and uses <workspace root>/http-api
LYNOX_WORKSPACE_ROOT	Directory that holds the workspaces (default: <data dir>/workspace). Another directory must be one of its own: the engine refuses a root whose path is the data directory, contains it, or lies inside it. If bind mounts make the two overlap anyway, the data erasure refuses either way, and backup and export refuse when the data directory ends up inside the root. Backup, export and the data erasure reach the workspaces there
LYNOX_BUGSINK_DSN	Error reporting DSN (self-hosted, opt-in)

Google Workspace

Variable	Purpose
GOOGLE_CLIENT_ID	Google OAuth client ID
GOOGLE_CLIENT_SECRET	Google OAuth client secret
GOOGLE_SERVICE_ACCOUNT_KEY	Path to Google service account JSON key file (headless/Docker)

On lynox.cloud these are optional: an instance with no client pair of its own connects through lynox’s shared Google client, and the card offers that as one button. Setting them switches the instance to your own client — see Google Workspace.

Editing Config

You can edit config in two ways:

1. Web UI — Settings → Config
2. Direct — Edit ~/.lynox/config.json manually (restart required)