bytedance/deer-flow

An open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of...

74.7k stars · 10.1k forks · 319 watchers · Python Topics: nodejs, python, agent, typescript, ai, podcast, multi-agent, superagent, harness, ai-agents, llm, langchain, agentic, langgraph, agentic-framework, agentic-workflow, deep-research, langmanus

README

🦌 DeerFlow - 2.0 English | 中文 | 日本語 | Français | Русский

On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥

DeerFlow (Deep Exploration and Efficient Research Flow) is an open-source super agent harness that orchestrates sub-agents, memory, and sandboxes to do almost anything — powered by extensible skills.

deer-flow-720p.mp4

NoteDeerFlow 2.0 is a ground-up rewrite. It shares no code with v1. If you're looking for the original Deep Research framework, it's maintained on the 1.x branch — contributions there are still welcome. Active development has moved to 2.0.

Official Website Learn more and see real demos on our official website. Coding Plan from ByteDance Volcengine

We strongly recommend using Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5 to run DeerFlow Learn more 中国大陆地区的开发者请点击这里

InfoQuest DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus--InfoQuest (supports free online experience)

Table of Contents

🦌 DeerFlow - 2.0

Official Website Coding Plan from ByteDance Volcengine InfoQuest Table of Contents One-Line Agent Setup Quick Start

Configuration Running the Application

Deployment Sizing Option 1: Docker (Recommended) Option 2: Local Development

Advanced

Sandbox Mode MCP Server IM Channels LangSmith Tracing Langfuse Tracing Using Both Providers

From Deep Research to Super Agent Harness Core Features

Skills & Tools

Claude Code Integration

Sub-Agents Sandbox & File System Context Engineering Long-Term Memory

Recommended Models Embedded Python Client Terminal Workbench (TUI) Documentation ⚠️ Security Notice

Improper Deployment May Introduce Security Risks Security Recommendations

Contributing License Acknowledgments

Key Contributors

Star History

One-Line Agent Setup If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence: Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md

That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide. Quick Start Configuration

Clone the DeerFlow repository git clone https://github.com/bytedance/deer-flow.git cd deer-flow

Run the setup wizard From the project root directory (deer-flow/), run: make setup This launches an interactive wizard that guides you through choosing an LLM provider, optional web search, and execution/safety preferences such as sandbox mode, bash access, and file-write tools. It generates a minimal config.yaml and writes your keys to .env. Takes about 2 minutes. The wizard also lets you configure an optional web search provider, or skip it for now. Run make doctor at any time to verify your setup and get actionable fix hints.

Advanced / manual configuration: If you prefer to edit config.yaml directly, run make config instead to copy the full template. See config.example.yaml for the complete reference including CLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, Responses API, and more.

Manual model configuration examples models: - name: gpt-4o display_name: GPT-4o use: langchain_openai:ChatOpenAI model: gpt-4o api_key: $OPENAI_API_KEY

- name: openrouter-gemini-2.5-flash display_name: Gemini 2.5 Flash (OpenRouter) use: langchain_openai:ChatOpenAI model: google/gemini-2.5-flash-preview api_key: $OPENROUTER_API_KEY base_url: https://openrouter.ai/api/v1

- name: gpt-5-responses display_name: GPT-5 (Responses API) use: langchain_openai:ChatOpenAI model: gpt-5 api_key: $OPENAI_API_KEY use_responses_api: true output_version: responses/v1

- name: qwen3-32b-vllm display_name: Qwen3 32B (vLLM) use: deerflow.models.vllm_provider:VllmChatModel model: Qwen/Qwen3-32B api_key: $VLLM_API_KEY base_url: http://localhost:8000/v1 supports_thinking: true when_thinking_enabled: extra_body: chat_template_kwargs: enable_thinking: true OpenRouter and similar OpenAI-compatible gateways should be configured with langchain_openai:ChatOpenAI plus base_url. If you prefer a provider-specific environment variable name, point api_key at that variable explicitly (for example api_key: $OPENROUTER_API_KEY). To route OpenAI models through /v1/responses, keep using langchain_openai:ChatOpenAI and set use_responses_api: true with output_version: responses/v1. For vLLM 0.19.0, use deerflow.models.vllm_provider:VllmChatModel. For Qwen-style reasoning models, DeerFlow toggles reasoning with extra_body.chat_template_kwargs.enable_thinking and preserves vLLM's non-standard reasoning field across multi-turn tool-call conversations. Legacy thinking configs are normalized automatically for backward compatibility. Reasoning models may also require the server to be started with --reasoning-parser .... If your local vLLM deployment accepts any non-empty API key, you can still set VLLM_API_KEY to a placeholder value. CLI-backed provider examples: models: - name: gpt-5.4 display_name: GPT-5.4 (Codex CLI) use: deerflow.models.openai_codex_provider:CodexChatModel model: gpt-5.4 supports_thinking: true supports_reasoning_effort: true

- name: claude-sonnet-4.6 display_name: Claude Sonnet 4.6 (Claude Code OAuth) use: deerflow.models.claude_provider:ClaudeChatModel model: claude-sonnet-4-6 max_tokens: 4096 supports_thinking: true

Codex CLI reads ~/.codex/auth.json Claude Code accepts CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_CREDENTIALS_PATH, or ~/.claude/.credentials.json ACP agent entries are separate from model providers — if you configure acp_agents.codex, point it at a Codex ACP adapter such as npx -y @zed-industries/codex-acp On macOS, export Claude Code auth explicitly if needed:

eval "$(python3 scripts/export_claude_code_oauth.py --print-export)" API keys can also be set manually in .env (recommended) or exported in your shell: OPENAI_API_KEY=your-openai-api-key TAVILY_API_KEY=your-tavily-api-key

Running the Application Deployment Sizing Use the table below as a practical starting point when choosing how to run DeerFlow:

Deployment target Starting point Recommended Notes

Local evaluation / make dev 4 vCPU, 8 GB RAM, 20 GB free SSD 8 vCPU, 16 GB RAM Good for one developer or one light session with hosted model APIs. 2 vCPU / 4 GB is usually not enough.

Docker development / make docker-start 4 vCPU, 8 GB RAM, 25 GB free SSD 8 vCPU, 16 GB RAM Image builds, bind mounts, and sandbox containers need more headroom than pure local dev.

Long-running server / make up 8 vCPU, 16 GB RAM, 40 GB free SSD 16 vCPU, 32 GB RAM Preferred for shared use, multi-agent runs, report generation, or heavier sandbox workloads.

These numbers cover DeerFlow itself. If you also host a local LLM, size that service separately. Linux plus Docker is the recommended deployment target for a persistent server. macOS and Windows are best treated as development or evaluation environments. If CPU or memory usage stays pinned, reduce concurrent runs first, then move to the next sizing tier.

Option 1: Docker (Recommended) Development (hot-reload, source mounts): make docker-init # Pull sandbox image (only once or when image updates) make docker-start # Start services (auto-detects sandbox mode from config.yaml) make docker-start starts provisioner only when config.yaml uses provisioner mode (sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider with provisioner_url). Docker builds use the upstream uv registry by default. If you need faster mirrors in restricted networks, export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple and NPM_REGISTRY=https://registry.npmmirror.com before running make docker-init or make docker-start. Backend processes automatically pick up config.yaml changes on the next config access, so model metadata updates do not require a manual restart during development. TipOn Linux, if Docker-based commands fail with permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, add your user to the docker group and re-login before retrying. See CONTRIBUTING.md for the full fix.

Production (builds images locally, mounts runtime config and data): make up # Build images and start all production services make down # Stop and remove containers Access: http://localhost:2026 The unified nginx endpoint is same-origin by default and does not emit browser CORS headers. If you run a split-origin or port-forwarded browser client, set GATEWAY_CORS_ORIGINS to comma-separated exact origins such as http://localhost:3000; the Gateway then applies the CORS allowlist and matching CSRF origin checks. ImportantThe Gateway holds run state (RunManager and the stream bridge) in process, so production defaults to a single Gateway worker (GATEWAY_WORKERS=1). Raising the worker count without a shared cross-worker stream bridge — which is not yet available — breaks run cancellation, SSE reconnects, request de-duplication, and IM channels, because nginx uses no sticky sessions and each worker keeps its own run state. Scale a single worker up with more CPU/RAM (or move the database and sandbox onto dedicated tiers) instead of raising GATEWAY_WORKERS.

See CONTRIBUTING.md for detailed Docker development guide. Option 2: Local Development If you prefer running services locally: Prerequisite: complete the "Configuration" steps above first (make setup). make dev requires a valid config.yaml in the project root. Set DEER_FLOW_PROJECT_ROOT to define that root explicitly, or DEER_FLOW_CONFIG_PATH to point at a specific config file. Runtime state defaults to .deer-flow under the project root and can be moved with DEER_FLOW_HOME; skills default to skills/ under the project root and can be moved with DEER_FLOW_SKILLS_PATH. Run make doctor to verify your setup before starting. On Windows, run the local development flow from Git Bash. Native cmd.exe and PowerShell shells are not supported for the bash-based service scripts, and WSL is not guaranteed because some scripts rely on Git for Windows utilities such as cygpath.

Check prerequisites: make check # Verifies Node.js 22+, pnpm, uv, nginx

Install dependencies: make install # Install backend + frontend dependencies + pre-commit hooks

(Optional) Pre-pull sandbox image:

Recommended if using Docker/Container-based sandbox

(Optional) Load sample memory data for local review: python scripts/load_memory_sample.py This copies the sample fixture into the default local runtime memory file so reviewers can immediately test Settings > Memory. See backend/docs/MEMORY_SETTINGS_REVIEW.md for the shortest review flow.

Start services: make dev

Access: http://localhost:2026

Startup Modes DeerFlow runs the agent runtime inside the Gateway API. Development mode enables hot-reload; production mode uses a pre-built frontend.

Local Foreground Local Daemon Docker Dev Docker Prod

Dev ./scripts/serve.sh --devmake dev ./scripts/serve.sh --dev --daemonmake dev-daemon ./scripts/docker.sh startmake docker-start —

Prod ./scripts/serve.sh --prodmake start ./scripts/serve.sh --prod --daemonmake start-daemon — ./scripts/deploy.shmake up

Action Local Docker Dev Docker Prod

Stop ./scripts/serve.sh --stopmake stop ./scripts/docker.sh stopmake docker-stop ./scripts/deploy.sh downmake down

Restart ./scripts/serve.sh --restart [flags] ./scripts/docker.sh restart —

Gateway owns /api/langgraph/ and translates those public LangGraph-compatible paths to its native /api/ routers behind nginx. Docker Production Deployment deploy.sh supports building and starting separately:

One-step (build + start)

Two-step (build once, start later)

Stop

Local Execution (runs sandbox code directly on the host machine) Docker Execution (runs sandbox code in isolated Docker containers) Docker Execution with Kubernetes (runs sandbox code in Kubernetes pods via provisioner service)

For Docker development, service startup follows config.yaml sandbox mode. In Local/Docker modes, provisioner is not started. See the Sandbox Configuration Guide to configure your preferred mode. MCP Server DeerFlow supports configurable MCP servers and skills to extend its capabilities. For HTTP/SSE MCP servers, OAuth token flows are supported (client_credentials, refresh_token). See the MCP Server Guide for detailed instructions. IM Channels DeerFlow supports receiving tasks from messaging apps. Channels auto-start when configured — no public IP required for any of them. DeerFlow can also expose user-owned IM channel connections in the workspace UI. When channel_connections is enabled, logged-in users can bind Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, or WeCom from the sidebar / Settings > Channels. It reuses the existing outbound channels.* transports, so no public IP or provider callback URL is required. Incoming IM messages then run under the connected DeerFlow user account. See IM Channel Connections for setup and security notes.

Channel Transport Difficulty

Telegram Bot API (long-polling) Easy

Slack Socket Mode Moderate

Feishu / Lark WebSocket Moderate

WeChat Tencent iLink (long-polling) Moderate

WeCom WebSocket Moderate

DingTalk Stream Push (WebSocket) Moderate

Configuration in config.yaml: channels: # LangGraph-compatible Gateway API base URL (default: http://localhost:8001/api) langgraph_url: http://localhost:8001/api # Gateway API URL (default: http://localhost:8001) gateway_url: http://localhost:8001

# Optional: global session defaults for all mobile channels session: assistant_id: lead_agent # or a custom agent name; custom agents are routed via lead_agent + agent_name config: recursion_limit: 100 context: thinking_enabled: true is_plan_mode: false subagent_enabled: false

feishu: enabled: true app_id: $FEISHU_APP_ID app_secret: $FEISHU_APP_SECRET # domain: https://open.feishu.cn # China (default) # domain: https://open.larksuite.com # International

wecom: enabled: true bot_id: $WECOM_BOT_ID bot_secret: $WECOM_BOT_SECRET

slack: enabled: true bot_token: $SLACK_BOT_TOKEN # xoxb-... app_token: $SLACK_APP_TOKEN # xapp-... (Socket Mode) allowed_users: [] # empty = allow all

telegram: enabled: true bot_token: $TELEGRAM_BOT_TOKEN allowed_users: [] # empty = allow all

wechat: enabled: false bot_token: $WECHAT_BOT_TOKEN ilink_bot_id: $WECHAT_ILINK_BOT_ID qrcode_login_enabled: true # optional: allow first-time QR bootstrap when bot_token is absent allowed_users: [] # empty = allow all polling_timeout: 35 state_dir: ./.deer-flow/wechat/state max_inbound_image_bytes: 20971520 max_outbound_image_bytes: 20971520 max_inbound_file_bytes: 52428800 max_outbound_file_bytes: 52428800

# Optional: per-channel / per-user session settings session: assistant_id: mobile-agent # custom agent names are also supported here context: thinking_enabled: false users: "123456789": assistant_id: vip-agent config: recursion_limit: 150 context: thinking_enabled: true subagent_enabled: true

dingtalk: enabled: true client_id: $DINGTALK_CLIENT_ID # Client ID of your DingTalk application client_secret: $DINGTALK_CLIENT_SECRET # Client Secret of your DingTalk application allowed_users: [] # empty = allow all card_template_id: "" # Optional: AI Card template ID for streaming typewriter effect Notes:

assistant_id: lead_agent calls the default LangGraph assistant directly. If assistant_id is set to a custom agent name, DeerFlow still routes through lead_agent and injects that value as agent_name, so the custom agent's SOUL/config takes effect for IM channels. IM channel workers call Gateway's LangGraph-compatible API internally and automatically attach process-local internal auth plus the CSRF cookie/header pair required for thread and run creation.

Set the corresponding API keys in your .env file:

Telegram

Slack

Feishu / Lark

WeChat iLink

WeCom

DingTalk

Chat with @BotFather, send /newbot, and copy the HTTP API token. Set TELEGRAM_BOT_TOKEN in .env and enable the channel in config.yaml.

Slack Setup

Create a Slack App at api.slack.com/apps → Create New App → From scratch. Under OAuth & Permissions, add Bot Token Scopes: app_mentions:read, chat:write, im:history, im:read, im:write, files:write. Enable Socket Mode → generate an App-Level Token (xapp-…) with connections:write scope. Under Event Subscriptions, subscribe to bot events: app_mention, message.im. Set SLACK_BOT_TOKEN and SLACK_APP_TOKEN in .env and enable the channel in config.yaml.

Feishu / Lark Setup

Create an app on Feishu Open Platform → enable Bot capability. Add permissions: im:message, im:message.p2p_msg:readonly, im:resource. Under Events, subscribe to im.message.receive_v1 and select Long Connection mode. Copy the App ID and App Secret. Set FEISHU_APP_ID and FEISHU_APP_SECRET in .env and enable the channel in config.yaml.

WeChat Setup

Enable the wechat channel in config.yaml. Either set WECHAT_BOT_TOKEN in .env, or set qrcode_login_enabled: true for first-time QR bootstrap. When bot_token is absent and QR bootstrap is enabled, watch backend logs for the QR content returned by iLink and complete the binding flow. After the QR flow succeeds, DeerFlow persists the acquired token under state_dir for later restarts. For Docker Compose deployments, keep state_dir on a persistent volume so the get_updates_buf cursor and saved auth state survive restarts.

WeCom Setup

Create a bot on the WeCom AI Bot platform and obtain the bot_id and bot_secret. Enable channels.wecom in config.yaml and fill in bot_id / bot_secret. Set WECOM_BOT_ID and WECOM_BOT_SECRET in .env. Make sure backend dependencies include wecom-aibot-python-sdk. The channel uses a WebSocket long connection and does not require a public callback URL. The current integration supports inbound text, image, and file messages. Final images/files generated by the agent are also sent back to the WeCom conversation.

DingTalk Setup

Create a DingTalk application in the DingTalk Developer Console and enable Robot capability. Set the message receiving mode to Stream Mode in the robot configuration page. Copy the Client ID and Client Secret, set DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET in .env, and enable the channel in config.yaml. (Optional) To enable streaming AI Card replies (typewriter effect), create an AI Card template on the DingTalk Card Platform, then set card_template_id in config.yaml to the template ID. You also need to apply for the Card.Streaming.Write and Card.Instance.Write permissions.

When DeerFlow run

source