Configuration - Docs by LangChain

The CLI stores its configuration in the ~/.deepagents/ directory. The main config files are:

File	Format	Purpose
`config.toml`	TOML	Model defaults, provider settings, constructor params, profile overrides, themes, update settings, MCP trust store
`.env`	Dotenv	Global API keys and secrets
`hooks.json`	JSON	External tool subscriptions to CLI lifecycle events
`.mcp.json`	JSON	Global MCP server definitions

Environment variables

The CLI loads environment variables from dotenv files so you don’t need to export API keys in your shell profile or duplicate .env files across projects.

Loading order and precedence

Two .env files are loaded at startup:

Project .env — the .env file in your current working directory (if present)
Global ~/.deepagents/.env — a single shared file that acts as a fallback for all projects

The effective precedence is: shell environment > project .env > global .env. Values already set in the shell are never overwritten—including on /reload.

`DEEPAGENTS_CLI_` prefix

All CLI-specific environment variables use a DEEPAGENTS_CLI_ prefix (e.g., DEEPAGENTS_CLI_AUTO_UPDATE, DEEPAGENTS_CLI_DEBUG). See the CLI environment variable reference for the full list. The prefix also works as an override mechanism for any environment variable the CLI reads, including third-party credentials. The CLI checks DEEPAGENTS_CLI_{NAME} first, then falls back to {NAME}:

~/.deepagents/.env

# Override OPENAI_API_KEY only for the CLI, without affecting other tools
DEEPAGENTS_CLI_OPENAI_API_KEY=sk-cli-only

# Block a shell-exported key within the CLI by setting the prefixed var to empty
DEEPAGENTS_CLI_ANTHROPIC_API_KEY=

On /reload, the CLI re-reads .env files and picks up prefixed values, so you can rotate keys without restarting.

Example

Store API keys once in ~/.deepagents/.env:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
LANGSMITH_API_KEY=lsv2_...
TAVILY_API_KEY=tvly-...

# If OPENAI_API_KEY is already exported in your shell for other tools,
# use the prefix to give the CLI its own key without conflict
DEEPAGENTS_CLI_OPENAI_API_KEY=sk-cli-only-...

Then override per-project where needed by placing a .env in the project directory.

Config file

~/.deepagents/config.toml lets you customize model providers, set defaults, and pass extra parameters to model constructors.

Default and recent model

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

Provider configuration

Each provider is a TOML table under [models.providers]:

[models.providers.<name>]
models = ["gpt-4o"]
api_key_env = "OPENAI_API_KEY"
base_url = "https://api.openai.com/v1"
class_path = "my_package.models:MyChatModel"
enabled = true

[models.providers.<name>.params]
temperature = 0
max_tokens = 4096

[models.providers.<name>.params."gpt-4o"]
temperature = 0.7

Providers have the following configuration options:

models

string[]

optional

A list of model names to show in the interactive /model switcher for this provider. For providers that already ship with model profiles, any names you add here appear alongside the bundled ones, useful for newly released models that haven’t been added to the package yet. For arbitrary providers, this list is the only source of models in the switcher.Models listed here bypass the profile-based filtering criteria and always appear in the switcher. This makes it the recommended way to surface models that are excluded because their profile lacks tool_calling support or doesn’t exist yet.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.

api_key_env

string

optional

Override the environment variable name checked for credentials. Most chat model packages read from a default env var automatically. See the Provider reference table for which variable each provider checks.

base_url

string

optional

Override the base URL used by the provider, if supported. Refer to your provider packages’ reference docs for more info.

params

object

optional

Extra keyword arguments forwarded to the model constructor. Flat keys (e.g., temperature = 0) apply to every model from this provider. Model-keyed sub-tables (e.g., [params."gpt-4o"]) override individual values for that model only; the merge is shallow (model wins on conflict).

profile

object

optional

(Advanced) Override fields in the model’s runtime profile (e.g., max_input_tokens). Flat keys apply to every model from this provider. Model-keyed sub-tables (e.g., [profile."claude-sonnet-4-5"]) override individual values for that model only; the merge is shallow (model wins on conflict). These overrides are applied after the model is created, so they take effect for context-limit display, auto-summarization, and any other feature that reads the profile.

class_path

string

optional

Used for arbitrary model providers. Fully-qualified Python class in module.path:ClassName format. When set, the CLI imports and instantiates this class directly for provider <name>. The class must be a BaseChatModel subclass.

enabled

boolean

default:"true"

optional

Whether this provider appears in the /model selector. Set to false to hide a provider that was auto-discovered from an installed package (e.g., a transitive dependency you don’t want cluttering the switcher). You can still use a disabled provider directly via /model provider:model or --model.

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.

CLI overrides with `--model-params`

For one-off adjustments without editing the config file, pass a JSON object via --model-params at launch or mid-session with the /model command:

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}'

Inside the TUI

/model --model-params '{"temperature": 0.9}' ollama:llama3
/model --model-params '{"num_ctx": 16384}'  # opens selector, applies params to chosen model

These take the highest priority, overriding values from config file params. Mid-session params are applied for the current session only and are not persisted. --model-params cannot be combined with --default.

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 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. --profile-override values persist across mid-session /model hot-swaps — switching models re-applies the override to the new model.

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.

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 imports and instantiates the class directly — no built-in provider package required.

[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

api_key_env and base_url are optional. class_path providers are expected to handle their own authentication internally — useful when your model uses custom auth (JWT tokens, proprietary headers, mTLS, etc.) rather than a standard API key:

[models.providers.xyz]
class_path = "abc.integrations.deepagents:DeepAgentsXYZChat"
models = ["abc-xyz-1"]

[models.providers.xyz.params]
bypass_auth = true
temperature = 0

With this config, switch to the model with /model xyz:abc-xyz-1 or --model xyz:abc-xyz-1.

Deep Agents requires tool calling support. If your custom model supports tool calling but the CLI doesn’t know about it, declare it in the provider profile:

[models.providers.xyz.profile]
tool_calling = true
max_input_tokens = 128000

Set max_input_tokens to what your model supports to enable accurate context length tracking and auto-summarization.

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

# If deepagents-cli was installed with uv tool:
uv tool install 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.

Skills extra allowed directories

By default, when the CLI loads skills it validates that a resolved skill file path stays inside one of the standard skill directories. This prevents symlinks inside skill directories from reading arbitrary files outside those roots. If you store shared skill assets in a non-standard location and use symlinks from a standard skill directory to reference them, you can add that location to the containment allowlist. This does not add a new skill discovery location: skills are still only discovered from the standard directories.

extra_allowed_dirs

string[]

optional

Paths added to the skill containment allowlist. Supports ~ expansion.

[skills]
extra_allowed_dirs = [
    "~/shared-skills",
    "/opt/team-skills",
]

Alternatively, set the DEEPAGENTS_CLI_EXTRA_SKILLS_DIRS environment variable as a colon-separated list:

export DEEPAGENTS_CLI_EXTRA_SKILLS_DIRS="~/shared-skills:/opt/team-skills"

When the environment variable is set, it takes precedence over the config file value. Changes take effect on /reload.

Themes

Use /theme to open an interactive theme selector. Navigate the list to preview themes in real-time, press Enter to persist your choice to config.toml. The CLI ships with many built-in themes. The default theme is langchain, a dark theme with LangChain-branded colors. The selected theme is persisted under [ui]:

[ui]
theme = "langchain-dark"

User-defined themes

Define custom themes under [themes.<name>] sections in config.toml. Each section requires label (str). dark (bool) defaults to false if omitted — set to true for dark themes. All color fields are optional — omitted fields fall back to the built-in dark or light palette based on the dark flag.

[themes.my-solarized]
label = "My Solarized"
dark = true
primary = "#268BD2"
warning = "#B58900"

# Theme names with spaces require TOML quoting
[themes."ocean breeze"]
label = "Ocean Breeze"
primary = "#0077B6"
background = "#CAF0F8"

User-defined themes appear alongside built-in themes in the /theme selector.

Override built-in theme colors

To tweak a built-in theme’s colors without creating a new theme, use a [themes.<builtin-name>] section. Only color fields are read — label and dark are inherited from the built-in:

[themes.langchain]
primary = "#FF5500"

Omitted color fields retain the existing built-in values. Changes to [themes.*] sections take effect on /reload.

Auto-update

The CLI can automatically check for and install updates.

Config file
Environment variable

[update]
auto_update = true

export DEEPAGENTS_CLI_AUTO_UPDATE=1

The environment variable takes precedence over the config file. When enabled, the CLI checks PyPI for a newer version at session start and automatically upgrades using the detected install method (uv, Homebrew, or pip). When disabled (default), the CLI shows an update hint with the appropriate install command instead. You can also check for and install updates manually at any time with the /update slash command, which bypasses the cache and reports success or failure inline. After an upgrade, the CLI shows a “what’s new” banner on the next launch with a link to the changelog. At session exit, if a newer version was detected during the session, an update banner is displayed as a reminder.

Managed deployments

The install script supports running as root, targeting macOS MDM tools (Kandji, Jamf, etc.) that execute scripts in a minimal root environment. When id -u is 0, the script:

Resolves the real console user’s HOME (via /dev/console or a /Users directory scan)
chowns all created files back to the target user after each install step

Non-root installs are unaffected: all root-specific code paths short-circuit when not running as root. To pre-configure auto-update for managed installs, set DEEPAGENTS_CLI_AUTO_UPDATE=1 in the user’s shell profile or deploy a config.toml with [update] auto_update = true to ~/.deepagents/config.toml. To suppress automatic updates and update checks entirely, set DEEPAGENTS_CLI_NO_UPDATE_CHECK=1.

CLI environment variable reference

All CLI-specific environment variables use the DEEPAGENTS_CLI_ prefix. See DEEPAGENTS_CLI_ prefix for how the prefix also works as an override for third-party credentials.

DEEPAGENTS_CLI_AUTO_UPDATE

string

optional

Enable automatic CLI updates (1, true, or yes).

DEEPAGENTS_CLI_DEBUG

string

optional

Enable verbose debug logging to a file.

DEEPAGENTS_CLI_DEBUG_FILE

string

default:"/tmp/deepagents_debug.log"

optional

Path for the debug log file.

DEEPAGENTS_CLI_EXTRA_SKILLS_DIRS

string

optional

Colon-separated paths added to the skill containment allowlist.

DEEPAGENTS_CLI_LANGSMITH_PROJECT

string

optional

Override the LangSmith project name for agent traces. See Tracing with LangSmith.

DEEPAGENTS_CLI_NO_UPDATE_CHECK

string

optional

Disable automatic update checking when set.

DEEPAGENTS_CLI_SHELL_ALLOW_LIST

string

optional

Comma-separated shell commands to allow (or recommended / all).

DEEPAGENTS_CLI_USER_ID

string

optional

Attach a user identifier to LangSmith trace metadata.

External editor

Press Ctrl+X or type /editor to compose prompts in an external editor. The CLI checks $VISUAL, then $EDITOR, then falls back to vi (macOS/Linux) or notepad (Windows). GUI editors (VS Code, Cursor, Zed, Sublime Text, Windsurf) automatically receive a --wait flag so the CLI blocks until you close the file.

# Set in your shell profile (~/.zshrc, ~/.bashrc, etc.)
export VISUAL="code"    # GUI editor (--wait auto-injected)
export EDITOR="nvim"    # Terminal fallback

Hooks

Hooks let external programs react to CLI lifecycle events. Configure commands in ~/.deepagents/hooks.json and the CLI pipes a JSON payload to each matching command’s stdin whenever an event fires. Hooks run fire-and-forget in a background thread — they never block the CLI and failures are logged without interrupting your session.

Setup

Create ~/.deepagents/hooks.json:

{
  "hooks": [
    {
      "command": ["bash", "-c", "cat >> ~/deepagents-events.log"],
      "events": ["session.start", "session.end"]
    }
  ]
}

Now every time a session starts or ends, the CLI appends the event payload to ~/deepagents-events.log.

Hook configuration

The config file contains a single hooks array. Each entry has:

command

list[str]

required

Command and arguments to run. No shell expansion: use ["bash", "-c", "..."] if needed.

events

list[str]

optional

Event names to subscribe to. Omit or leave empty to receive all events.

{
  "hooks": [
    {
      "command": ["python3", "my_handler.py"],
      "events": ["session.start", "task.complete"]
    },
    {
      "command": ["bash", "log_everything.sh"]
    }
  ]
}

The second hook above has no events filter, so it receives every event the CLI emits.

Payload format

Each hook command receives a JSON object on stdin with an "event" key plus event-specific fields:

{
  "event": "session.start",
  "thread_id": "abc123"
}

Events reference

`session.start`

Fired when an agent session begins (both interactive and non-interactive modes).

thread_id

string

required

The session thread identifier.

`session.end`

Fired when a session exits.

thread_id

string

required

The session thread identifier.

`user.prompt`

Fired in interactive mode when the user submits a chat message. No additional fields.

`input.required`

Fired when the agent requires human input (human-in-the-loop interrupt). No additional fields.

`permission.request`

Fired before the approval dialog when one or more tool calls need user permission.

tool_names

list[str]

required

Names of the tools requesting approval.

`tool.error`

Fired when a tool call returns an error.

tool_names

list[str]

required

Names of the tool(s) that errored.

`task.complete`

Fired when the agent finishes its current task (the streaming loop ends without further interrupts).

thread_id

string

required

The session thread identifier.

`context.compact`

Fired before the CLI compacts (summarizes) the conversation context. No additional fields.

Execution model

Background thread: Hook subprocesses run in a thread via asyncio.to_thread so the main event loop is never blocked.
Concurrent dispatch: When multiple hooks match an event, they run concurrently in a thread pool.
5-second timeout: Each command has a 5-second timeout. Commands that exceed this are killed.
Fire-and-forget: Errors are caught per-hook and logged at debug/warning level. A failing hook never crashes or stalls the CLI.
Lazy loading: The config file is read once on the first event dispatch and cached for the rest of the session.
No shell expansion: Commands are executed directly (not through a shell). Wrap in ["bash", "-c", "..."] if you need shell features like pipes or variable expansion.

Hook examples

Log all events to a file

{
  "hooks": [
    {
      "command": ["bash", "-c", "jq -c . >> ~/.deepagents/hook-events.jsonl"],
      "events": []
    }
  ]
}

Desktop notification on task completion (macOS)

{
  "hooks": [
    {
      "command": [
        "bash", "-c",
        "osascript -e 'display notification \"Agent finished\" with title \"Deep Agents\"'"
      ],
      "events": ["task.complete"]
    }
  ]
}

Python handler

Write a handler script that reads the JSON payload from stdin:

my_handler.py

import json
import sys

payload = json.load(sys.stdin)
event = payload["event"]

if event == "session.start":
    print(f"Session started: {payload['thread_id']}", file=sys.stderr)
elif event == "permission.request":
    print(f"Approval needed for: {payload['tool_names']}", file=sys.stderr)

~/.deepagents/hooks.json

{
  "hooks": [
    {
      "command": ["python3", "my_handler.py"],
      "events": ["session.start", "permission.request"]
    }
  ]
}

Security considerations

Hooks follow the same trust model as Git hooks or shell aliases — any user who can write to ~/.deepagents/hooks.json can execute arbitrary commands. This is by design:

No command injection: Payload data flows only to stdin as JSON, never to command-line arguments. json.dumps handles escaping.
No shell by default: Commands run with shell=False, preventing shell injection.
Malformed config: Invalid JSON or unexpected types produce logged warnings, not security issues.

Only add hooks from sources you trust. A hook has the same permissions as your user account.

Edit this page on GitHub or file an issue.

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

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

​Environment variables

​Loading order and precedence

​DEEPAGENTS_CLI_ prefix

​Example

​Config file

​Default and recent model

​Provider configuration

​Model constructor params

​Per-model overrides

​CLI overrides with --model-params

​Profile overrides (Advanced)

​CLI profile overrides with --profile-override (Advanced)

​Custom base URL

​Compatible APIs

​Adding models to the interactive switcher

​Arbitrary providers

​Skills extra allowed directories

​Themes

​User-defined themes

​Override built-in theme colors

​Auto-update

​Managed deployments

​CLI environment variable reference

​External editor

​Hooks

​Setup

​Hook configuration

​Payload format

​Events reference

​session.start

​session.end

​user.prompt

​input.required

​permission.request

​tool.error

​task.complete

​context.compact

​Execution model

​Hook examples

​Security considerations

Environment variables

Loading order and precedence

`DEEPAGENTS_CLI_` prefix

Example

Config file

Default and recent model

Provider configuration

Model constructor params

Per-model overrides

CLI overrides with `--model-params`

Profile overrides (Advanced)

CLI profile overrides with `--profile-override` (Advanced)

Custom base URL

Compatible APIs

Adding models to the interactive switcher

Arbitrary providers

Skills extra allowed directories

Themes

User-defined themes

Override built-in theme colors

Auto-update

Managed deployments

CLI environment variable reference

External editor

Hooks

Setup

Hook configuration

Payload format

Events reference

`session.start`

`session.end`

`user.prompt`

`input.required`

`permission.request`

`tool.error`

`task.complete`

`context.compact`

Execution model

Hook examples

Security considerations