Custom model providers ↗

This key is optional. You can always pass any model name directly to /model or --model regardless of whether it appears in the switcher; the provider validates the name at request time.

You can set a default model in ~/.deepagents/config.toml — either by editing the file directly, using /model --default, or selecting a default in the interactive model switcher.

[models]
default = "ollama:qwen3:4b"        # your intentional long-term preference
recent = "anthropic:claude-sonnet-4-5"  # last /model switch (written automatically)

[models].default always takes priority over [models].recent. The /model command only writes to [models].recent, so your configured default is never overwritten by mid-session switches. To remove the default, use /model --default --clear or delete the default key from the config file.

Examples#

Model constructor params#

Any provider can use the params table to pass extra arguments to the model constructor:

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192

Per-model overrides#

If a specific model needs different params, add a model-keyed sub-table under params to override individual values without duplicating the entire provider config:

[models.providers.ollama]
models = ["qwen3:4b", "llama3"]

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192

[models.providers.ollama.params."qwen3:4b"]
temperature = 0.5
num_ctx = 4000

With this configuration:

• ollama:qwen3:4b gets {temperature: 0.5, num_ctx: 4000} — model overrides win.
• ollama:llama3 gets {temperature: 0, num_ctx: 8192} — no override, provider-level params only.

The merge is shallow: any key present in the model sub-table replaces the same key from the provider-level params, while keys only at the provider level are preserved.

Profile overrides#

(Advanced)

Override fields in the model’s runtime profile to change how the CLI interprets model capabilities. The most common use case is lowering max_input_tokens to trigger auto-summarization earlier — useful for testing or for constraining context usage:

# Apply to all models from this provider
[models.providers.anthropic.profile]
max_input_tokens = 4096

Per-model sub-tables work the same way as params — the model-level value wins on conflict:

[models.providers.anthropic.profile]
max_input_tokens = 4096

# This model gets a higher limit
[models.providers.anthropic.profile."claude-sonnet-4-5"]
max_input_tokens = 8192

Profile overrides are merged into the model’s profile after creation. Any feature that reads the profile — context-limit display in the status bar, auto-summarization thresholds, capability checks — will see the overridden values.

CLI overrides with --model-params#

For one-off adjustments without editing the config file, pass a JSON object via --model-params:

deepagents --model ollama:llama3 --model-params '{"temperature": 0.9, "num_ctx": 16384}'

# In non-interactive mode
deepagents -n "Summarize this repo" --model ollama:llama3 --model-params '{"temperature": 0}'

These take the highest priority, overriding values from config file params.

CLI profile overrides with --profile-override#

(Advanced)

To override model profile fields at runtime without editing the config file, pass a JSON object via --profile-override:

deepagents --profile-override '{"max_input_tokens": 4096}'

# Combine with --model
deepagents --model anthropic:claude-sonnet-4-5 --profile-override '{"max_input_tokens": 4096}'

# In non-interactive mode
deepagents -n "Summarize this repo" --profile-override '{"max_input_tokens": 4096}'

These are merged on top of config file profile overrides (CLI wins). The priority chain is: model default < config.toml profile < CLI --profile-override.

Specifying custom base_url#

Some provider packages accept a base_url to override the default endpoint. For example, langchain-ollama defaults to http://localhost:11434 via the underlying ollama client. To point it elsewhere, set base_url in your configuration:

[models.providers.ollama]
base_url = "http://your-host-here:port"

Refer to your provider’s reference documentation for compatibility information and additional considerations.

Model routers and proxies#

Model routers like OpenRouter and LiteLLM provide access to models from multiple providers through a single endpoint.

Use the dedicated integration packages for these services:

OpenRouter is a built-in provider — install the package and use it directly:

uv tool install 'deepagents-cli[openrouter]'

Compatible APIs#

For providers that expose APIs that are wire-compatible with OpenAI or Anthropic, you can use the existing langchain-openai or langchain-anthropic packages by pointing base_url at the provider’s endpoint:

[models.providers.openai]
base_url = "https://api.example.com/v1"
api_key_env = "EXAMPLE_API_KEY"
models = ["my-model"]

[models.providers.anthropic]
base_url = "https://api.example.com"
api_key_env = "EXAMPLE_API_KEY"
models = ["my-model"]

Any features added on top of the official spec by the provider will not be captured. If the provider offers a dedicated LangChain integration package, prefer that instead.

Adding models to the interactive switcher#

Some providers (e.g. langchain-ollama) — don’t bundle model profile data (see Provider reference for full listing). When this is the case, the interactive /model switcher won’t list models for that provider. You can fill in the gap by defining a models list in your config file for the provider:

[models.providers.ollama]
models = ["llama3", "mistral", "codellama"]

The /model switcher will now include an Ollama section with these models listed.

This is entirely optional. You can always switch to any model by specifying its full name directly:

/model ollama:llama3

Arbitrary providers#

You can use any LangChain BaseChatModel subclass using class_path. The CLI will import and instantiate it directly:

[models.providers.my_custom]
class_path = "my_package.models:MyChatModel"
api_key_env = "MY_API_KEY"
base_url = "https://my-endpoint.example.com"

[models.providers.my_custom.params]
temperature = 0
max_tokens = 4096

The package must be installed in the same Python environment as deepagents-cli:

# If deepagents-cli was installed with uv tool:
uv tool upgrade deepagents-cli --with my_package

When you switch to my_custom:my-model-v1 (via /model or --model), the model name (my-model-v1) is passed as the model kwarg:

MyChatModel(model="my-model-v1", base_url="...", api_key="...", temperature=0, max_tokens=4096)

class_path executes arbitrary Python code from your config file. This has the same trust model as pyproject.toml build scripts — you control your own machine.

Your provider package may optionally provide model profiles at a _PROFILES dict in <package>.data._profiles in lieu of defining them under the models key. See LangChain model profiles for more info.

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.