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

# Custom Models

> Use OpenRouter, Ollama, vLLM, or any OpenAI-compatible endpoint.

## Overview

Arden supports any OpenAI-compatible API endpoint. Register custom models via `~/.arden/models.json` or the `/add-model` skill.

Built-in providers cover Anthropic, OpenAI API keys, OpenAI account sign-in through the Codex endpoint, Google Gemini, and OpenRouter.

## OpenAI account sign-in

If you have an OpenAI subscription/account and do not want to use an API key,
connect **OpenAI Codex** from provider onboarding or **Desktop Settings →
Providers**.

* Arden opens the OpenAI browser authorization flow.
* Tokens are stored locally at `~/.arden/openai-codex-auth.json`.
* Default chat model: `openai-codex/gpt-5.5`.
* Default memory model: `openai-codex/gpt-5.4-mini`.
* The Auxiliary role starts on the memory model and can be changed independently in Settings.
* Tool-using reasoning calls use the Responses API shape internally (`reasoning: { effort: ... }`) so GPT reasoning models can call tools without hitting Chat Completions compatibility limits.

Use the regular **OpenAI** provider instead when you want API-key billing, embeddings, or direct platform API behavior.

## models.json

Create `~/.arden/models.json` with model IDs as top-level keys:

```json theme={null}
{
  "deepseek-r1": {
    "base_url": "https://openrouter.ai/api/v1",
    "api_key_env": "OPENROUTER_API_KEY",
    "context_window": 64000,
    "max_output_tokens": 8192
  },
  "llama-local": {
    "base_url": "http://localhost:11434/v1",
    "context_window": 128000,
    "max_output_tokens": 4096
  },
  "embedding": {
    "nomic-embed-text": {
      "base_url": "http://localhost:11434/v1",
      "dim": 768
    }
  }
}
```

## Fields

| Field                    | Required | Description                                            |
| ------------------------ | -------- | ------------------------------------------------------ |
| top-level key            | Yes      | Model identifier used in settings, e.g. `deepseek-r1`  |
| `base_url`               | Yes      | Base URL of the OpenAI-compatible API                  |
| `context_window`         | Yes      | Maximum context window for chat/completion models      |
| `max_output_tokens`      | No       | Maximum output tokens, defaults to `8192`              |
| `api_key_env`            | No       | Env var name containing the API key                    |
| `price_in` / `price_out` | No       | Price per million tokens for usage estimates           |
| `embedding.<id>.dim`     | Yes      | Embedding vector dimension for custom embedding models |

## Using custom models

After adding to `models.json`, set the model in your environment or settings:

```bash theme={null}
export ARDEN_CHAT_MODEL=deepseek-r1
```

Or change it in **Desktop Settings → Models**.

## Embedding models

Choose the embedding model in **Desktop Settings → Models → Embeddings**.
Arden asks for confirmation before a change because every active fact and
readable wiki page must be embedded again. The same view shows rebuild
progress and lets you retry a failed rebuild.

Choose **No embeddings** to disable semantic matching. Arden then makes no
embedding requests; full-text search continues to work.

<img src="https://mintcdn.com/ntrp/yXMP7sfCaHIwY_fB/images/settings-models.png?fit=max&auto=format&n=yXMP7sfCaHIwY_fB&q=85&s=588b71fed86c7713cc12b4f5850fb6c7" alt="Model and embedding settings" width="2640" height="1700" data-path="images/settings-models.png" />

## Providers

### OpenRouter

```json theme={null}
{
  "openrouter/deepseek-r1": {
    "base_url": "https://openrouter.ai/api/v1",
    "api_key_env": "OPENROUTER_API_KEY",
    "context_window": 64000,
    "max_output_tokens": 8192
  }
}
```

### Ollama

```json theme={null}
{
  "llama3": {
    "base_url": "http://localhost:11434/v1",
    "context_window": 128000,
    "max_output_tokens": 4096
  }
}
```

No `api_key_env` needed for local Ollama.

### vLLM

```json theme={null}
{
  "my-model": {
    "base_url": "http://localhost:8080/v1",
    "context_window": 32000,
    "max_output_tokens": 4096
  }
}
```

## Interactive setup

Use the `/add-model` skill in chat for guided model registration:

```
/add-model
```

The agent will walk you through configuring the endpoint.