deer-flow/backend/docs/CONFIGURATION.md

Configuration Guide

This guide explains how to configure DeerFlow for your environment.

Quick Start

1. Copy the example configuration (from project root):

   # From project root directory (deer-flow/)
   cp config.example.yaml config.yaml
   

2. Set your API keys:

   Option A: Use environment variables (recommended):

   export OPENAI_API_KEY="your-api-key-here"
   export ANTHROPIC_API_KEY="your-api-key-here"
   # Add other keys as needed
   

   Option B: Edit config.yaml directly (not recommended for production):

   models:
     - name: gpt-4
       api_key: your-actual-api-key-here  # Replace placeholder
   

3. Start the application:

   make dev
   

Configuration Sections

Models

Configure the LLM models available to the agent:

models:
  - name: gpt-4                    # Internal identifier
    display_name: GPT-4            # Human-readable name
    use: langchain_openai:ChatOpenAI  # LangChain class path
    model: gpt-4                   # Model identifier for API
    api_key: $OPENAI_API_KEY       # API key (use env var)
    max_tokens: 4096               # Max tokens per request
    temperature: 0.7               # Sampling temperature

Supported Providers:

• OpenAI (langchain_openai:ChatOpenAI)
• Anthropic (langchain_anthropic:ChatAnthropic)
• DeepSeek (langchain_deepseek:ChatDeepSeek)
• Any LangChain-compatible provider

Thinking Models: Some models support "thinking" mode for complex reasoning:

models:
  - name: deepseek-v3
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

Tool Groups

Organize tools into logical groups:

tool_groups:
  - name: web          # Web browsing and search
  - name: file:read    # Read-only file operations
  - name: file:write   # Write file operations
  - name: bash         # Shell command execution

Tools

Configure specific tools available to the agent:

tools:
  - name: web_search
    group: web
    use: src.community.tavily.tools:web_search_tool
    max_results: 5
    # api_key: $TAVILY_API_KEY  # Optional

Built-in Tools:

• web_search - Search the web (Tavily)
• web_fetch - Fetch web pages (Jina AI)
• ls - List directory contents
• read_file - Read file contents
• write_file - Write file contents
• str_replace - String replacement in files
• bash - Execute bash commands

Sandbox

Choose between local execution or Docker-based isolation:

Option 1: Local Sandbox (default, simpler setup):

sandbox:
  use: src.sandbox.local:LocalSandboxProvider

Option 2: Docker Sandbox (isolated, more secure):

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  port: 8080
  auto_start: true
  container_prefix: deer-flow-sandbox

  # Optional: Additional mounts
  mounts:
    - host_path: /path/on/host
      container_path: /path/in/container
      read_only: false

Skills

Configure the skills directory for specialized workflows:

skills:
  # Host path (optional, default: ../skills)
  path: /custom/path/to/skills

  # Container mount path (default: /mnt/skills)
  container_path: /mnt/skills

How Skills Work:

• Skills are stored in deer-flow/skills/{public,custom}/
• Each skill has a SKILL.md file with metadata
• Skills are automatically discovered and loaded
• Available in both local and Docker sandbox via path mapping

Title Generation

Automatic conversation title generation:

title:
  enabled: true
  max_words: 6
  max_chars: 60
  model_name: null  # Use first model in list

Environment Variables

DeerFlow supports environment variable substitution using the $ prefix:

models:
  - api_key: $OPENAI_API_KEY  # Reads from environment

Common Environment Variables:

• OPENAI_API_KEY - OpenAI API key
• ANTHROPIC_API_KEY - Anthropic API key
• DEEPSEEK_API_KEY - DeepSeek API key
• TAVILY_API_KEY - Tavily search API key
• DEER_FLOW_CONFIG_PATH - Custom config file path

Configuration Location

The configuration file should be placed in the project root directory (deer-flow/config.yaml), not in the backend directory.

Configuration Priority

DeerFlow searches for configuration in this order:

1. Path specified in code via config_path argument
2. Path from DEER_FLOW_CONFIG_PATH environment variable
3. config.yaml in current working directory (typically backend/ when running)
4. config.yaml in parent directory (project root: deer-flow/)

Best Practices

1. Place config.yaml in project root - Not in backend/ directory
2. Never commit config.yaml - It's already in .gitignore
3. Use environment variables for secrets - Don't hardcode API keys
4. Keep config.example.yaml updated - Document all new options
5. Test configuration changes locally - Before deploying
6. Use Docker sandbox for production - Better isolation and security

Troubleshooting

"Config file not found"

• Ensure config.yaml exists in the project root directory (deer-flow/config.yaml)
• The backend searches parent directory by default, so root location is preferred
• Alternatively, set DEER_FLOW_CONFIG_PATH environment variable to custom location

"Invalid API key"

• Verify environment variables are set correctly
• Check that $ prefix is used for env var references

"Skills not loading"

• Check that deer-flow/skills/ directory exists
• Verify skills have valid SKILL.md files
• Check skills.path configuration if using custom path

"Docker sandbox fails to start"

• Ensure Docker is running
• Check port 8080 (or configured port) is available
• Verify Docker image is accessible

Examples

See config.example.yaml for complete examples of all configuration options.