deer-flow/frontend/src/content/en/application/configuration.mdx

---
title: Configuration
description: DeerFlow App is configured through two files and a set of environment variables. This page covers the application-level configuration that most operators need to set up before deploying.
---

import { Callout, Tabs } from "nextra/components";

# Configuration

DeerFlow App is configured through two files and a set of environment variables. This page covers the application-level configuration that most operators need to set up before deploying.

## Configuration files

| File                     | Purpose                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------- |
| `config.yaml`            | Backend configuration: models, sandbox, tools, skills, memory, and all Harness settings |
| `extensions_config.json` | MCP servers and skill enable/disable state (managed by the App UI and Gateway API)      |

Frontend environment variables control the Next.js build and runtime behavior.

## config.yaml

Start by copying the example:

```bash
cp config.example.yaml config.yaml
```

The most important sections for application configuration are:

### Models

Configure the LLM providers the agent can use. At least one model is required.

<Tabs items={["OpenAI", "Anthropic", "DeepSeek", "Ollama", "llama.cpp", "Gemini"]}>
  <Tabs.Tab>
```yaml
models:
  - name: gpt-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    supports_vision: true
```
  </Tabs.Tab>
  <Tabs.Tab>
```yaml
models:
  - name: claude-sonnet-5-5
    use: langchain_anthropic:ChatAnthropic
    model: claude-sonnet-5-5
    api_key: $ANTHROPIC_API_KEY
    default_request_timeout: 600.0
    max_retries: 2
    max_tokens: 8192
    supports_vision: true
```
  </Tabs.Tab>
  <Tabs.Tab>
```yaml
models:
  - name: deepseek-v4
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: deepseek-v4-pro
    api_key: $DEEPSEEK_API_KEY
    timeout: 600.0
    max_retries: 2
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled
    when_thinking_disabled:
      extra_body:
        thinking:
          type: disabled
```
  </Tabs.Tab>
  <Tabs.Tab>
```yaml
models:
  - name: qwen3-local
    use: langchain_ollama:ChatOllama
    model: qwen3:32b
    base_url: http://localhost:11434  # No /v1 suffix — uses native Ollama API
    num_predict: 8192
    temperature: 0.7
    reasoning: true
    supports_thinking: true
    supports_vision: false
```

Install Ollama provider: `cd backend && uv add 'deerflow-harness[ollama]'`

<Callout type="warning">
  Use <code>langchain_ollama:ChatOllama</code> (not the OpenAI-compatible
  endpoint) for Ollama models. The native API correctly separates thinking
  content; the OpenAI-compatible endpoint may flatten or drop it.
</Callout>
  </Tabs.Tab>
  <Tabs.Tab>
```bash
llama-server -m /path/to/model.gguf --host 0.0.0.0 --port 8080 --alias qwen-local
```

```yaml
models:
  - name: qwen-llamacpp
    use: langchain_openai:ChatOpenAI
    model: qwen-local
    api_key: no-key
    base_url: http://localhost:8080/v1
    request_timeout: 600.0
    max_retries: 2
    supports_vision: false
```

`llama-server` exposes an OpenAI-compatible `/v1/chat/completions` endpoint, so point `base_url` at its `/v1` root. `ChatOpenAI` expects a non-empty API key; `no-key` is only a placeholder when llama.cpp authentication is disabled. If the server uses `--api-key`, configure that value instead.

For Docker deployments, `localhost` refers to the DeerFlow container. Use a host address reachable from the container, such as `http://host.docker.internal:8080/v1` on Docker Desktop.

<Callout type="warning">
  DeerFlow relies on tool calling. Make sure the GGUF model's chat template supports
  function/tool calls. Current llama.cpp enables its Jinja chat-template engine by
  default; custom templates must preserve tool-call support.
</Callout>
  </Tabs.Tab>
  <Tabs.Tab>
```yaml
models:
  - name: gemini-2.5-pro
    use: langchain_google_genai:ChatGoogleGenerativeAI
    model: gemini-2.5-pro
    gemini_api_key: $GEMINI_API_KEY
    timeout: 600.0
    max_retries: 2
    max_tokens: 8192
    supports_vision: true
```
  </Tabs.Tab>
</Tabs>

#### Reasoning capabilities

`supports_thinking` and `supports_reasoning_effort` only say whether a knob exists. When a provider's contract differs from DeerFlow's generic assumptions — thinking that cannot be turned off, or an effort vocabulary other than `minimal/low/medium/high` — declare a mapping-valued `reasoning` block instead. The two booleans are then derived from it, the chat UI offers only the values the model accepts, and every model call (chat, summarization, title generation, subagents) follows the same policy. Existing Ollama `reasoning: true` / `false` values, and the `low` / `medium` / `high` level strings gpt-oss style models take, remain native ChatOllama settings and do not opt into this contract.

```yaml
models:
  - name: glm-5.3-flash
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: glm-5.3-flash
    api_base: https://api.z.ai/api/paas/v4
    api_key: $ZAI_API_KEY
    supports_vision: true
    reasoning:
      thinking: required            # unsupported | optional | required
      dialect: openai_extra_body    # auto | openai_extra_body | anthropic | vllm_chat_template | ollama | none
      history: clear                # preserve | clear
      effort:
        values: [low, high, max]    # the provider's own vocabulary
        default: high               # used when the caller does not choose
        aliases:                    # DeerFlow generic value -> provider value
          minimal: low
          medium: high
    extra_body:
      tool_stream: true
```

- `thinking: required` keeps thinking on even when a background caller asks for it off; set `on_disable_request: reject` to fail such calls instead.
- Effort values outside `values` map through `aliases` or fall back to `default`; they never reach the provider. Effort values written into the profile or into `when_thinking_enabled` / `when_thinking_disabled` are validated against `values` at startup for the same reason.
- When changing `effort.path`, remove old `reasoning_effort` keys from the profile and thinking templates. A declared contract rejects these conflicting keys at startup. The chat UI also drops a remembered provider-specific effort when switching to a legacy model that does not advertise it.
- `default` also applies to callers that never choose an effort — summarization, title generation, and subagents — so pick a level you are happy to pay for on every background call (`high` above, with `max` left selectable in the composer).
- `dialect: auto` (the default) infers the on/off payload from `when_thinking_enabled`, so existing profiles can add `reasoning` without rewriting their templates. Profiles without a `reasoning` block behave exactly as before.
- `when_thinking_enabled` and `when_thinking_disabled` are deep-merged into the profile's settings: a template can add or override keys, never remove them, so the profile's other `extra_body` keys (for example `tool_stream`) survive both toggles. Put enable-only keys such as `extra_body.thinking.budget_tokens` in `when_thinking_enabled`, not in the profile's base `extra_body` — a disable template cannot clear them, and Anthropic-style APIs reject them beside `type: disabled`.
- Contradictory profiles (for example `required` together with `when_thinking_disabled`) fail at startup.

### Sandbox

Choose the execution environment for agent file and command operations:

<Tabs items={["Local (default)", "Docker container", "K8s Provisioner"]}>
  <Tabs.Tab>
```yaml
sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
  allow_host_bash: false  # set true only for trusted single-user workflows
```
  </Tabs.Tab>
  <Tabs.Tab>
```yaml
sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
  replicas: 3
  idle_timeout: 600
```

Install: `agent-sandbox` is already a core dependency of `deerflow-harness`, so no extra install step is needed.

  </Tabs.Tab>
  <Tabs.Tab>
```yaml
sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002
```
  </Tabs.Tab>
</Tabs>

### Tools

Configure which tools the agent has access to. The defaults use DuckDuckGo (no API key) and Jina AI for web operations:

```yaml
tools:
  # Web search (choose one)
  - name: web_search
    group: web
    use: deerflow.community.ddg_search.tools:web_search_tool # default, no key required
  # - name: web_search
  #   group: web
  #   use: deerflow.community.tavily.tools:web_search_tool
  #   api_key: $TAVILY_API_KEY

  # Web fetch (choose one)
  - name: web_fetch
    group: web
    use: deerflow.community.jina_ai.tools:web_fetch_tool

  # Image search
  - name: image_search
    group: web
    use: deerflow.community.image_search.tools:image_search_tool

  # File operations
  - name: ls
    group: file:read
    use: deerflow.sandbox.tools:ls_tool
  - name: read_file
    group: file:read
    use: deerflow.sandbox.tools:read_file_tool
  - name: glob
    group: file:read
    use: deerflow.sandbox.tools:glob_tool
  - name: grep
    group: file:read
    use: deerflow.sandbox.tools:grep_tool
  - name: write_file
    group: file:write
    use: deerflow.sandbox.tools:write_file_tool
  - name: str_replace
    group: file:write
    use: deerflow.sandbox.tools:str_replace_tool
  - name: bash
    group: bash
    use: deerflow.sandbox.tools:bash_tool
```

### Database backend

DeerFlow uses the `database` section for both LangGraph checkpoint data and application data such as runs, feedback, and thread metadata.

By default, DeerFlow uses SQLite for local, single-node persistence:

```yaml
database:
  backend: sqlite
  sqlite_dir: .deer-flow/data
```

SQLite mode stores everything in one `deerflow.db` file. This is fine for development or single-user deployments, but concurrent production traffic can hit SQLite's single-writer limit and raise `sqlite3.OperationalError: database is locked`.

For production or multi-user deployments, use Postgres:

```yaml
database:
  backend: postgres
  postgres_url: $DATABASE_URL

run_events:
  backend: db
```

Set `DATABASE_URL` in your environment, for example `postgresql://user:password@localhost:5432/deerflow`.

Install PostgreSQL support for local runs:

```bash
cd backend && uv sync --all-packages --extra postgres
```

For Docker or scripted starts, set `UV_EXTRAS=postgres` before installing or building. The legacy standalone `checkpointer` section is still accepted for compatibility, but prefer `database` for new deployments.

### Memory

```yaml
memory:
  enabled: true
  injection_enabled: true
  manager_class: deermem          # backend selector: deermem | noop | openviking | dotted path
  mode: middleware                 # middleware (default) | tool (experimental)
  backend_config:                  # DeerMem-private knobs (the backend self-interprets these)
    storage_path: ""               # empty = deer-flow base_dir (per-user memory under it)
    debounce_seconds: 30
    max_facts: 100
    fact_confidence_threshold: 0.7
    max_injection_tokens: 2000
    # model:                       # LLM for extraction; omit all fields = use the app default model
    #   provider: openai
    #   model: gpt-4o-mini
    #   api_key: $OPENAI_API_KEY
```

The optional `openviking` backend connects to an independent OpenViking server
through `langchain-openviking` and currently supports one DeerFlow user in
`mode: middleware`. Its private configuration uses `base_url`,
`owner_user_id`, `api_key_env`, `failure_policy`, and `retrieval` with an
ordinary OpenViking USER API key instead of the DeerMem fields shown above. See
`docs/OPENVIKING.md` in the repository for the complete configuration and
Docker startup sequence.

## Frontend environment variables

Set these before running `pnpm build` or starting the frontend in production:

| Variable                         | Required                   | Description                                                       |
| -------------------------------- | -------------------------- | ----------------------------------------------------------------- |
| `BETTER_AUTH_SECRET`             | **Required** in production | Secret for session signing. Use `openssl rand -base64 32`.        |
| `BETTER_AUTH_URL`                | Recommended                | Public-facing base URL (e.g., `https://your-domain.com`)          |
| `SKIP_ENV_VALIDATION`            | Optional                   | Set to `1` to skip env validation during build (not recommended)  |
| `NEXT_PUBLIC_BACKEND_BASE_URL`   | Optional                   | Override the Gateway base URL used for REST and SSR calls         |
| `NEXT_PUBLIC_LANGGRAPH_BASE_URL` | Optional                   | Override the LangGraph API base URL (defaults to `<backend>/api`) |

In development, set these in a `.env` file at the repo root:

```bash
BETTER_AUTH_SECRET=your-strong-secret-here-min-32-chars
```

## extensions_config.json

This file manages MCP server connections and skill enable/disable state. It is created automatically when you first manage extensions through the App UI or Gateway API.

Manual example:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "enabled": true
    }
  },
  "skills": {
    "deep-research": { "enabled": true },
    "data-analysis": { "enabled": true }
  }
}
```

## Config upgrade

When the config schema changes, `config_version` is bumped. To merge new fields into your existing config without losing customizations:

```bash
make config-upgrade
```

## Runtime environment variables

DeerFlow reads these from its own process environment — via a `.env` file, the
Docker environment, or the shell.

Only `DEER_FLOW_SKILLS_PATH` resolves a relative value against
`DEER_FLOW_PROJECT_ROOT`. `DEER_FLOW_HOME` and `DEER_FLOW_CONFIG_PATH` are used
as given, so a relative value resolves against the process working directory —
set both to absolute paths so writable state and the loaded config file land
where you expect them.

| Variable                 | Default                            | Description                                                                                 |
| ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------- |
| `DEER_FLOW_PROJECT_ROOT` | current working directory          | Root for project-relative defaults, including the `skills` lookup                           |
| `DEER_FLOW_HOME`         | `<project root>/.deer-flow`        | Writable directory for runtime state (threads, uploads); use an absolute path               |
| `DEER_FLOW_CONFIG_PATH`  | auto-discovered under project root | Absolute path to `config.yaml`                                                              |
| `DEER_FLOW_SKILLS_PATH`  | `<project root>/skills`            | Directory containing skill definitions (a relative value resolves against the project root) |
| `AUTH_JWT_SECRET`        | auto-generated                     | JWT signing secret for the Gateway                                                          |

Log verbosity is not an environment variable — set `log_level` in `config.yaml`
instead (`debug`, `info`, `warning`, or `error`; default `info`). See
[Harness Configuration](/docs/harness/configuration) for the module reference.

`DEER_FLOW_ROOT` is a host-side variable for the Docker Compose dev stack only;
the DeerFlow process does not read it. See the
[Deployment Guide](/docs/application/deployment-guide).

When `AUTH_JWT_SECRET` is unset, DeerFlow generates a secret on first start and
persists it to `.jwt_secret`, so sessions survive restarts. Set it explicitly in
production to keep a stable, secret value.

<Cards num={2}>
  <Cards.Card
    title="Deployment Guide"
    href="/docs/application/deployment-guide"
  />
  <Cards.Card
    title="Harness Configuration"
    href="/docs/harness/configuration"
  />
</Cards>