Custom Models

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

{
  "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:

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.

Providers

OpenRouter

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

Ollama

{
  "llama3": {
    "base_url": "http://localhost:11434/v1",
    "context_window": 128000,
    "max_output_tokens": 4096
  }
}

No api_key_env needed for local Ollama.

vLLM

{
  "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.

Getting Started

Features

Integrations

Reference

Custom Models

Overview

models.json

Fields

Using custom models

Embedding models

Providers

OpenRouter

Ollama

vLLM

Interactive setup

​Overview

​OpenAI account sign-in

​models.json

​Fields

​Using custom models

​Embedding models

​Providers

​OpenRouter

​Ollama

​vLLM

​Interactive setup

Overview

OpenAI account sign-in

models.json

Fields

Using custom models

Embedding models

Providers

OpenRouter

Ollama

vLLM

Interactive setup