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

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

config.yaml

Start by copying the example:

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.

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

models:
  - name: claude-3-5-sonnet
    use: langchain_anthropic:ChatAnthropic
    model: claude-3-5-sonnet-20241022
    api_key: $ANTHROPIC_API_KEY
    default_request_timeout: 600.0
    max_retries: 2
    max_tokens: 8192
    supports_vision: true
    supports_thinking: true
    when_thinking_enabled:
      thinking:
        type: enabled
    when_thinking_disabled:
      thinking:
        type: disabled

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

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

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

Sandbox

Choose the execution environment for agent file and command operations:

sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
  allow_host_bash: false  # set true only for trusted single-user workflows

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

sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002

Tools

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

tools:
  # Web search (choose one)
  - use: deerflow.community.ddg_search.tools:web_search_tool # default, no key required
  # - use: deerflow.community.tavily.tools:web_search_tool
  #   api_key: $TAVILY_API_KEY
 
  # Web fetch (choose one)
  - use: deerflow.community.jina_ai.tools:web_fetch_tool
 
  # Image search
  - use: deerflow.community.image_search.tools:image_search_tool
 
  # File operations
  - use: deerflow.sandbox.tools:ls_tool
  - use: deerflow.sandbox.tools:read_file_tool
  - use: deerflow.sandbox.tools:glob_tool
  - use: deerflow.sandbox.tools:grep_tool
  - use: deerflow.sandbox.tools:write_file_tool
  - use: deerflow.sandbox.tools:str_replace_tool
  - 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:

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:

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:

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

memory:
  enabled: true
  storage_path: memory.json
  debounce_seconds: 30
  max_facts: 100
  injection_enabled: true
  max_injection_tokens: 2000

Frontend environment variables

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

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

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:

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

make config-upgrade