Configuration

Config resolution

Persisted app options in ~/.arden/settings.json take precedence over matching environment values. Provider and service secrets resolve from the process environment, then ./.env, then ~/.arden/.env, with secrets saved through Desktop used only as a fallback. Defaults and provider auto-detection apply after those sources.

LLM providers

Set at least one provider API key, or connect OpenAI Codex with browser sign-in from the desktop client.

Provider	Setup	Typical chat model	Embedding model
Anthropic	`ANTHROPIC_API_KEY`	Claude	–
OpenAI API	`OPENAI_API_KEY`	GPT	`text-embedding-3-small`
OpenAI Codex	Browser sign-in in desktop onboarding/settings	OpenAI account models	–
Google	`GEMINI_API_KEY`	Gemini	`gemini-embedding-001`
OpenRouter/custom	Desktop settings or custom model config	Provider model	depends

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

Override auto-detection with explicit model IDs:

export ARDEN_CHAT_MODEL=claude-sonnet-4-6
export ARDEN_EMBEDDING_MODEL=text-embedding-3-small

Configure role-specific models and reasoning effort in Desktop Settings. They are persisted in model_roles and model_reasoning_efforts in the settings file; the legacy ARDEN_<ROLE>_MODEL variables are not configuration inputs. Choose an embedding model, or No embeddings, in Desktop Settings → Models. Changing it rebuilds the semantic index after confirmation. A disabled choice is persisted as "embedding_model": null.

Embedding is optional. Without it, Arden makes no embedding requests and continues to work with full-text search.

Server

Variable	Default	Description
`ARDEN_HOST`	`127.0.0.1`	Server bind address
`ARDEN_PORT`	`6877`	Server port

Features

Variable	Default	Description
`ARDEN_MEMORY`	`true`	Enable persistent memory
`ARDEN_GMAIL_DAYS`	`30`	Days of Gmail history to index
`ARDEN_DEFERRED_TOOLS`	`true`	Hide infrequent integration/action tool schemas until loaded

Optional integrations

Variable	Description
`EXA_API_KEY`	Exa.ai API key for web search when `WEB_SEARCH=exa`
`WEB_SEARCH`	Web provider mode: `auto`, `exa`, `ddgs`, or `none`
`SLACK_BOT_TOKEN`	Slack bot token (`xoxb-...`)
`SLACK_USER_TOKEN`	Slack user token (`xoxp-...`)
`TELEGRAM_BOT_TOKEN`	Telegram notifications

For Google and Slack, use Settings → Integrations. Use Settings → MCP for MCP servers.

Agent behavior

Variable	Default	Description
`ARDEN_MAX_DEPTH`	`8`	Max agentic recursion depth
`ARDEN_COMPRESSION_THRESHOLD`	app default	Token threshold for context compaction
`ARDEN_MAX_MESSAGES`	app default	Message-count threshold for compaction

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

Authentication

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

arden-server serve --reset-key

Desktop clients store the key locally and encrypt it with OS-backed storage when supported.

Settings file

~/.arden/settings.json stores persisted app configuration. Persisted app options override matching environment values; saved provider and service keys remain fallbacks for environment-provided secrets.

{
  "chat_model": "claude-sonnet-4-6",
  "model_roles": {
    "research": {"model": "claude-sonnet-4-6"},
    "workflow": {"model": "claude-sonnet-4-6"},
    "auxiliary": {"model": "claude-sonnet-4-6"},
    "memory": {"model": "claude-sonnet-4-6"}
  },
  "embedding_model": "text-embedding-3-small",
  "api_key_hash": "a1b2c3:..."
}

Custom models

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

Getting Started

Features

Integrations

Reference

Configuration

Config resolution

LLM providers

Server

Features

Optional integrations

Agent behavior

Authentication

Settings file

Custom models

​Config resolution

​LLM providers

​Server

​Features

​Optional integrations

​Agent behavior

​Authentication

​Settings file

​Custom models

Config resolution

LLM providers

Server

Features

Optional integrations

Agent behavior

Authentication

Settings file

Custom models