# 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:**

```bash
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

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Python | 3.12+ | 3.12+ |
| Node.js | 18+ | 20+ |
| Package managers | `uv`, `pnpm` | `uv`, `pnpm 10.26+` |
| Docker | Optional | For AIO sandbox mode |
| Kubernetes | Optional | For provisioner sandbox mode |

### Method 1: Setup Wizard (Recommended)

```bash
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:

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

2. Copy the example configuration files:

```bash
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:

```bash
cd backend
uv sync
```

5. Install frontend dependencies:

```bash
cd frontend
pnpm install
```

6. Start the services:

```bash
# 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

```bash
# 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

```bash
curl http://localhost:8001/health
```

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

| File | Format | Purpose |
|------|--------|---------|
| `config.yaml` | YAML | Core configuration: models, tools, sandbox, memory, skills, channels |
| `extensions_config.json` | JSON | MCP server configurations and per-skill enable/disable state |

### Minimal Working Configuration

```yaml
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

| Variable | Purpose |
|----------|---------|
| `OPENAI_API_KEY` | OpenAI API authentication |
| `ANTHROPIC_API_KEY` | Anthropic Claude API authentication |
| `DEEPSEEK_API_KEY` | DeepSeek API authentication |
| `GEMINI_API_KEY` | Google Gemini API authentication |
| `TAVILY_API_KEY` | Tavily search API key |
| `EXA_API_KEY` | Exa search API key |
| `FIRECRAWL_API_KEY` | Firecrawl crawling API key |
| `DEER_FLOW_CONFIG_PATH` | Override default config file location |
| `DEER_FLOW_EXTENSIONS_CONFIG_PATH` | Override extensions config file location |

> [!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:

| Skill | Description |
|-------|-------------|
| `deep-research` | Multi-step deep research with citations |
| `chart-visualization` | Generate charts (bar, line, pie, scatter, and 20+ chart types) |
| `data-analysis` | Analyze uploaded CSV/data files with Python |
| `image-generation` | Generate images using AI models |
| `video-generation` | Generate videos using AI models |
| `ppt-generation` | Generate PowerPoint presentations |
| `podcast-generation` | Generate podcast scripts and audio |
| `newsletter-generation` | Generate newsletter content |
| `academic-paper-review` | Review and summarize academic papers |
| `systematic-literature-review` | Conduct systematic literature reviews |
| `code-documentation` | Generate documentation for code |
| `frontend-design` | Design frontend interfaces |
| `consulting-analysis` | Business consulting analysis |
| `github-deep-research` | Deep research on GitHub repositories |
| `skill-creator` | Create new custom skills |
| `find-skills` | Discover and install community skills |
| `surprise-me` | Random creative task |
| `claude-to-deerflow` | Migrate Claude Code workflows to DeerFlow |

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`:

```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`:

```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:

```yaml
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.

---

_Generated May 2026 from bytedance/deer-flow at 259a684. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._