> ## Documentation Index
> Fetch the complete documentation index at: https://arden.timganiev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Reference for environment variables and persisted settings.

## 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                  |

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

Override auto-detection with explicit model IDs:

```bash theme={null}
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`.

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

## 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.

```bash theme={null}
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.

```json theme={null}
{
  "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](/integrations/models) for registering OpenRouter, Ollama, vLLM, or any OpenAI-compatible endpoint.