DeerFlow User Guide

1. Quick Start

DeerFlow is an open-source AI agent framework built on LangGraph that combines deep research, multi-model orchestration, and sandboxed code execution into a conversational workspace. It supports web search, file operations, skill-based workflows (chart visualization, data analysis, image/video generation, and more), and IM channel integrations — all through a Next.js frontend or API.

Key features:

• Multi-model support (OpenAI, Anthropic, DeepSeek, Google Gemini, Ollama, vLLM, OpenRouter, MiniMax, and more)
• Sandboxed code execution (local, Docker AIO, or Kubernetes-provisioned)
• Extensible skill system with 15+ built-in public skills
• MCP (Model Context Protocol) server integration
• Persistent memory across conversations
• IM channel integrations (Feishu/Lark, Slack, Telegram, WeChat, WeCom)
• Plan mode with todo lists for structured task execution
• File upload and artifact generation
• Token usage tracking and conversation summarization

Prerequisites: Python 3.12+, Node.js 18+, pnpm package manager, uv (Python package manager)

Quickest path to running:

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
python scripts/setup_wizard.py

The setup wizard walks you through choosing an LLM provider, search provider, and sandbox mode, then writes your config.yaml and .env files.

Tip

If you already have API keys ready, the wizard completes in under 2 minutes. DuckDuckGo search works without any API key.

What to try next: Open http://localhost:2026 in your browser, type a question, and watch the agent plan, search, and respond with citations.

2. Installation

System Requirements

Method 1: Setup Wizard (Recommended)

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
python scripts/setup_wizard.py

The wizard guides you through:

1. LLM provider — choose from OpenAI, Anthropic, DeepSeek, Google Gemini, Ollama, vLLM, OpenRouter, Codex CLI, Claude Code OAuth, or a custom OpenAI-compatible endpoint
2. Search provider — DuckDuckGo (free, no key), Tavily, InfoQuest, Exa, or Firecrawl
3. Sandbox mode — local execution, Docker AIO container, or skip
4. Execution mode — LangGraph development server or standalone gateway

Important

The wizard writes config.yaml at the project root. If a config.yaml already exists, it is backed up before overwriting. You can also set the DEER_FLOW_CONFIG_PATH environment variable to point to a custom location.

Method 2: Manual Setup

1. Clone the repository:

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

2. Copy the example configuration files:

cp config.example.yaml config.yaml
cp extensions_config.example.json extensions_config.json
cp .env.example .env

3. Edit config.yaml to configure at least one model and one search tool (see the Configuration section).

4. Install backend dependencies:

cd backend
uv sync

5. Install frontend dependencies:

cd frontend
pnpm install

6. Start the services:

# Terminal 1: LangGraph dev server
cd backend
uv run langgraph dev --no-browser --host 0.0.0.0 --port 2024

# Terminal 2: Gateway API
cd backend
PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload

# Terminal 3: Frontend
cd frontend
pnpm run dev

Warning

When running services manually, ensure the LangGraph server is started before the gateway, as the gateway initializes LangGraph runtime components at startup.

Method 3: Docker Compose

# Set your project root path
export DEER_FLOW_ROOT=$(pwd)

# Start all services
docker compose -f docker/docker-compose-dev.yaml up --build

Access the application at http://localhost:2026.

Post-Install Verification

curl http://localhost:8001/health

{"status": "healthy", "service": "deer-flow-gateway"}

Install Troubleshooting

Q: uv sync fails with dependency resolution errors

Ensure you have Python 3.12+ and uv installed. Run uv --version to verify. If using an older Python, upgrade first.

Q: Frontend pnpm install fails

Verify pnpm is version 10.26+ (pnpm --version). If not, run corepack enable && corepack prepare pnpm@latest --activate.

Q: Docker build fails on macOS ARM

The default sandbox image supports both x86_64 and arm64. Ensure Docker Desktop has sufficient memory (at least 4 GB).

Q: Port 2026 already in use

The nginx proxy binds to port 2026. Stop any conflicting service or change the port in docker/docker-compose-dev.yaml.

3. Configuration

DeerFlow uses two configuration files:

Minimal Working Configuration

config_version: 7

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    max_tokens: 4096
    temperature: 0.7

tools:
  - name: web_search
    group: web
    use: deerflow.community.ddg_search.tools:web_search_tool
    max_results: 5

  - name: web_fetch
    group: web
    use: deerflow.community.jina_ai.tools:web_fetch_tool
    timeout: 10

sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
  allow_host_bash: false

Common Environment Variables

Tip

All api_key values in config.yaml support $ENV_VAR syntax. Put actual secrets in your .env file and reference them with $VARIABLE_NAME in the YAML.

For the complete configuration reference (all settings, all options), see the Admin Guide.

4. Core Usage

Starting a Conversation

Navigate to http://localhost:2026 (or your configured URL) to open the DeerFlow workspace. Type your question or task in the input box and press Enter.

The lead agent processes your request by:

1. Analyzing the query and creating a plan (visible in the UI as a task list)
2. Delegating to subagents (general-purpose, bash) as needed
3. Using tools (web search, file operations, code execution) to gather information
4. Presenting results with citations and artifacts

Chat Modes

DeerFlow supports two conversation modes, togglable in the workspace UI:

• Normal mode — the agent responds directly to your messages
• Plan mode — the agent creates a structured todo list before executing, giving you visibility into each step

Using Skills

Skills are specialized workflows the agent can invoke for specific tasks. Built-in public skills include:

To use a skill, simply describe your task naturally. The agent detects when a skill applies and invokes it automatically.

Note

Skills execute inside the sandbox environment. If you need file output (charts, documents), ensure your sandbox is configured with write access. Generated artifacts appear in the workspace artifacts panel.

File Uploads

Upload files directly in the chat input to provide context to the agent. Supported operations:

• PDF files are automatically converted to markdown for analysis (configurable converter: pymupdf4llm, markitdown, or auto)
• CSV/Excel files can be analyzed using the data-analysis skill
• Images can be viewed by models with vision support (supports_vision: true in config)

Artifacts

When the agent generates files (charts, documents, code, images), they appear as artifacts in the workspace. You can:

• View generated HTML/web content in a live preview
• Download generated files
• View source code in the built-in code editor

Model Selection

If multiple models are configured, you can switch between them in the workspace settings. Each model entry in config.yaml appears in the model selector.

Tip

Enable supports_thinking: true for models that support extended reasoning (DeepSeek, Claude, Gemini, Qwen). The workspace UI shows the agent's thinking process when this is active.

MCP Server Integration

DeerFlow connects to external MCP (Model Context Protocol) servers for additional tools. Configure them in extensions_config.json:

{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    }
  }
}

MCP servers support stdio, sse, and streamable_http transport types. OAuth authentication is also supported for SSE/HTTP servers.

Important

When many MCP tools are configured, enable tool_search in config.yaml to use deferred tool loading. This reduces context usage by listing tools by name in the system prompt and loading full schemas on demand.

Memory

DeerFlow maintains a persistent memory of user facts across conversations. Memory is:

• Automatically updated based on conversation content
• Injected into the system prompt for personalized responses
• Viewable and manageable through the workspace settings

To manage memory:

1. Open Settings in the workspace
2. Navigate to the Memory tab
3. View stored facts, delete individual entries, or clear all memory

5. Common Tasks

Research a Topic with Citations

Goal: Get a comprehensive research report on a topic.

1. Type your research question (e.g., "Research the current state of quantum computing in 2026")
2. The agent activates the deep-research skill automatically
3. It performs multi-step web searches, synthesizes findings, and presents results with source citations
4. Generated reports appear as downloadable artifacts

Analyze a CSV Dataset

Goal: Upload a CSV and get visualizations and insights.

1. Upload your CSV file in the chat input
2. Ask: "Analyze this dataset and create visualizations"
3. The agent uses the data-analysis skill to run Python code in the sandbox
4. Charts and summary statistics appear as artifacts

Generate a Chart

Goal: Create a specific chart type from data.

1. Describe the chart you want: "Create a bar chart comparing Q1-Q4 revenue"
2. Provide data inline or upload a file
3. The chart-visualization skill generates the chart using one of 26 chart types (area, bar, boxplot, column, district map, dual axes, fishbone, flow diagram, funnel, histogram, line, liquid, mind map, network graph, organization chart, path map, pie, pin map, radar, sankey, scatter, spreadsheet, treemap, venn, violin, word cloud)
4. Preview the chart in the artifacts panel

Create a Custom Agent

Goal: Create a specialized agent with its own personality and toolset.

1. Create a directory under backend/.deer-flow/agents/my-agent/
2. Add SOUL.md (system prompt defining the agent's personality and behavior)
3. Optionally add config.yaml for per-agent settings (model overrides, skill restrictions)
4. The agent appears in the workspace and can be selected for conversations

Connect to an IM Channel

Goal: Use DeerFlow through Slack, Telegram, Feishu, or WeChat.

1. Configure the channel in config.yaml under the channels: section
2. Provide the required bot tokens as environment variables
3. Restart the gateway — the channel service starts automatically
4. Message your bot in the configured platform

Warning

IM channels require the gateway to be running. If the channel service fails to start, check the gateway logs for authentication errors or missing tokens. All channels use outbound connections (WebSocket or polling), so no public IP is required.

Use a Local Ollama Model

Goal: Run DeerFlow with a locally-hosted model via Ollama.

1. Install Ollama and pull a model: ollama pull qwen3:32b
2. Install the Ollama LangChain adapter: cd backend && uv pip install 'deerflow-harness[ollama]'
3. Add the model to config.yaml:

models:
  - name: qwen3-local
    display_name: Qwen3 32B (Ollama)
    use: langchain_ollama:ChatOllama
    model: qwen3:32b
    base_url: http://localhost:11434
    num_predict: 8192
    temperature: 0.7
    reasoning: true
    supports_thinking: true

4. Restart the backend services and select the model in the workspace

Warning

Use langchain_ollama:ChatOllama instead of langchain_openai:ChatOpenAI for Ollama models. The OpenAI-compatible endpoint does not return reasoning_content as a separate field — thinking content is either flattened into <think> tags or dropped entirely.

Export Conversation History

Goal: Save a conversation for reference.

1. Open the conversation you want to export
2. Use the export button in the workspace toolbar
3. The conversation exports with all messages, artifacts, and metadata

6. Troubleshooting

Error: Failed to load configuration during gateway startup

Cause: The config.yaml file is missing, contains YAML syntax errors, or references undefined environment variables.

Solution:

1. Verify config.yaml exists at the project root (or at DEER_FLOW_CONFIG_PATH)
2. Validate YAML syntax: python -c "import yaml; yaml.safe_load(open('config.yaml'))"
3. Ensure at least one model is configured in the models: section
4. Check that all $ENV_VAR references in config have corresponding environment variables set

Prevention: Use the setup wizard (python scripts/setup_wizard.py) to generate a valid config.

Error: Model {name} not found in config

Cause: The requested model name does not match any entry in the models: section of config.yaml.

Solution:

1. Check spelling of the model name in your config
2. Ensure the model entry has a name: field matching what the agent requests
3. If using the UI model selector, refresh the page after config changes

Error: Model {name} does not support thinking

Cause: Thinking mode was requested for a model that does not have supports_thinking: true in its config.

Solution: Add supports_thinking: true to the model entry in config.yaml, along with when_thinking_enabled and when_thinking_disabled blocks as shown in config.example.yaml.

Error: Stream bridge not available (HTTP 503)

Cause: The LangGraph runtime failed to initialize during gateway startup.

Solution:

1. Check gateway logs for initialization errors
2. Ensure the LangGraph server is running and accessible
3. Verify langgraph.json in the backend directory is valid JSON

Error: Event loop is closed during memory updates

Cause: Concurrent memory update and conversation processing can trigger event loop conflicts (GitHub issue #2302).

Solution:

1. This is a known race condition in the memory update pipeline
2. Retry the conversation — the error is typically transient
3. If persistent, increase memory.debounce_seconds in config.yaml to reduce update frequency

Prevention: The memory system uses a debounced queue to batch updates and reduce conflicts.

Error: [LOOP DETECTED] You are repeating the same tool calls

Cause: The agent entered a loop calling the same tool repeatedly (GitHub issue #2304).

Solution:

1. Rephrase your prompt to be more specific
2. If the loop involves a specific tool, check that tool's configuration
3. The loop detection middleware automatically breaks the cycle after detection

Prevention: Use plan mode for complex tasks — the structured approach reduces loop risk.

Warning

If the loop detection triggers and the agent is asked to give an immediate answer, a secondary LLM error (HTTP 400) can occur (GitHub issues #2293, #2255). Start a new conversation thread if this happens.

Error: Error code: 400 on LLM requests

Cause: Malformed request to the LLM provider, often caused by duplicate tool calls or invalid message sequences (GitHub issue #2293).

Solution:

1. Start a new conversation thread
2. Rephrase the prompt to avoid triggering repeated tool use
3. Check that your model configuration matches the provider's requirements

Docker: Cannot access host ports from container

Cause: Docker containers cannot reach localhost on the host machine by default (GitHub issue #2297).

Solution:

1. Use host.docker.internal instead of localhost in container configurations
2. For Linux hosts, ensure the extra_hosts entry is present in docker-compose:

extra_hosts:
  - "host.docker.internal:host-gateway"

3. For Ollama, set base_url: http://host.docker.internal:11434 in config.yaml

Switching conversations interrupts running tasks

Cause: Clicking "New Chat" while a task is in progress and then switching back interrupts the original task (GitHub issue #2303).

Solution:

1. Wait for the current task to complete before starting a new conversation
2. If interrupted, re-submit the original prompt in the affected thread

Caution

Avoid navigating away from an active conversation thread while the agent is processing. The current architecture does not support background task continuation across thread switches.

Edited markdown artifacts display glitches

Cause: Modifying already-generated markdown files can cause display flickering in the artifacts panel (GitHub issue #2263).

Solution:

1. Download the file and edit it externally
2. Or wait for the agent to finish generating before making edits

Skill management shows JSON parsing error

Cause: The skills management endpoint may return HTML instead of JSON when misconfigured (GitHub issue #2203, closed/fixed).

Solution:

1. Ensure the backend gateway is running and accessible
2. Verify that /api/skills returns valid JSON
3. Update to the latest version if running an older build

7. FAQ

Q: Which LLM providers are supported?

DeerFlow supports OpenAI, Anthropic (Claude), DeepSeek, Google Gemini (native and OpenAI-compatible), Ollama (local), vLLM (self-hosted), OpenRouter, MiniMax, Novita AI, Codex CLI (local auth), Claude Code OAuth (local auth), and any OpenAI-compatible endpoint via langchain_openai:ChatOpenAI with a custom base_url.

Q: Do I need an API key to get started?

You need at least one LLM API key. For web search, DuckDuckGo works without any API key. The setup wizard guides you through the minimum required configuration.

Q: Can I use DeerFlow without Docker?

Yes. The default LocalSandboxProvider runs commands directly on the host. Docker is only needed for the AIO sandbox mode or Docker Compose deployment.

Q: How do I add a new MCP server?

Edit extensions_config.json and add a new entry under mcpServers with enabled: true. Supported transport types are stdio, sse, and streamable_http. Restart the backend for changes to take effect.

Q: How do I create a custom skill?

Use the built-in skill-creator skill by asking the agent to "create a new skill for [your use case]." Alternatively, create a SKILL.md file in skills/public/your-skill-name/ following the existing skill format.

Q: Can multiple models be configured simultaneously?

Yes. Add multiple entries to the models: list in config.yaml. The first model is used as the default. Users can switch models in the workspace UI.

Q: What sandbox modes are available?

Three modes: (1) Local (LocalSandboxProvider) — direct host execution, no isolation; (2) Docker AIO (AioSandboxProvider) — containerized execution with automatic container lifecycle management; (3) Kubernetes provisioner — per-sandbox Pods managed by the provisioner service for production-grade isolation.

Q: How does conversation memory work?

DeerFlow extracts facts from conversations and stores them in memory.json. These facts are injected into the system prompt for future conversations, enabling personalized responses. Memory can be managed via the workspace settings or the /api/memory API. The memory system uses a debounced queue with configurable delay (debounce_seconds) and confidence threshold (fact_confidence_threshold).

Q: What languages does the UI support?

English (en-US) and Chinese (zh-CN). The locale is detected automatically from browser settings or can be set manually. The locale preference is stored in a cookie.

Q: How do I configure conversation summarization?

Summarization is enabled by default in config.yaml. It triggers when token count reaches the configured threshold (default: 15,564 tokens), keeping the most recent messages (default: 10) after summarization. Adjust summarization.trigger and summarization.keep in the config.

Q: Can I use DeerFlow through messaging apps?

Yes. DeerFlow supports Feishu/Lark, Slack, Telegram, WeChat, and WeCom as IM channels. Configure them under channels: in config.yaml with the appropriate bot tokens. All channels use outbound connections — no public IP required.

Q: How do I upgrade my configuration after a DeerFlow update?

Run make config-upgrade to merge new fields from config.example.yaml into your existing config.yaml. The config_version field tracks schema changes.