Configuration

DeerFlow’s configuration system is designed around one goal: every meaningful behavior should be expressible in a config file, not hardcoded in the application. This makes deployments reproducible, auditable, and easy to customize per environment.

Config file location

DeerFlow resolves config.yaml using the following priority order:

1. The path passed to AppConfig.from_file(config_path) explicitly.
2. The DEER_FLOW_CONFIG_PATH environment variable.
3. backend/config.yaml (relative to the backend directory).
4. config.yaml in the repository root.

If none of these paths exist, the application raises an error at startup.

To use a custom location:

export DEER_FLOW_CONFIG_PATH=/path/to/my-config.yaml

Environment variable interpolation

Any field value can reference an environment variable using $VAR_NAME syntax:

models:
  - name: gpt-4o
    api_key: $OPENAI_API_KEY

This keeps secrets out of the config file itself. The variable is resolved at runtime from the process environment.

The use field

Many configuration entries use a use: field to specify the Python class or object to instantiate. The format is:

package.subpackage.module:ClassName

or for module-level objects:

package.subpackage.module:variable_name

Examples:

sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
 
tools:
  - use: deerflow.community.tavily.tools:web_search_tool
    api_key: $TAVILY_API_KEY

This pattern is how DeerFlow achieves pluggability without hardcoding class references.

Extra fields are passed through

For model configuration, ModelConfig uses pydantic ConfigDict(extra="allow"). This means any extra fields you add under a model entry are passed directly to the model constructor. This allows provider-specific options (like extra_body, reasoning, or custom timeout keys) to work without modifying the harness:

models:
  - name: my-model
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    some_provider_specific_option: value # passed through to ChatOpenAI constructor

Configuration version

config.yaml includes a config_version field that tracks the schema version:

config_version: 6

When the schema changes (new fields, renamed sections), this number is bumped. If your local config.yaml is behind the current version, run:

make config-upgrade

This merges new fields from config.example.yaml into your existing config.yaml without overwriting your customizations.

Module configuration reference

The following table maps each top-level config.yaml section to its documentation page:

Minimal config to get started

The minimum valid config.yaml requires at least one model and a sandbox:

config_version: 6
 
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
 
sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
 
tools:
  - use: deerflow.community.ddg_search.tools:web_search_tool
  - use: deerflow.community.jina_ai.tools:web_fetch_tool
  - use: deerflow.sandbox.tools:ls_tool
  - use: deerflow.sandbox.tools:read_file_tool
  - use: deerflow.sandbox.tools:write_file_tool
  - use: deerflow.sandbox.tools:bash_tool

Start from config.example.yaml in the repository root and uncomment the sections you need.