ByteDance DeerFlow 2.0: Open-source super agent harness with skills, sub-agents, and sandboxes

DeerFlow 2.0 is ByteDance's open-source super agent harness that orchestrates sub-agents, memory, and sandboxes to handle complex, multi-step tasks through extensible skills. Built on LangGraph and LangChain, it evolved from a deep research framework into a full-featured agent runtime with 65.7k GitHub stars.

Version 2.0 is a ground-up rewrite (no code shared with v1) that ships with batteries included: filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for tasks that take minutes to hours.

Primary sources

• Repository: github.com/bytedance/deer-flow
• Official website: deerflow.tech
• Documentation: Install.md, CONTRIBUTING.md
• License: MIT
• Key contributors: Daniel Walnut, Henry Li

TL;DR

From deep research to super agent harness

DeerFlow started as a deep research framework—and the community pushed it far beyond that original scope. Developers used it to build data pipelines, generate slide decks, spin up dashboards, and automate content workflows—things ByteDance never anticipated.

That told the team something important: DeerFlow wasn't just a research tool. It was a harness—a runtime that gives agents the infrastructure to actually get work done.

So they rebuilt it from scratch.

DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness—batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.

Use it as-is. Or tear it apart and make it yours.

Core features

1. Skills & Tools: extensible, progressive loading

Skills are what make DeerFlow do almost anything.

A standard Agent Skill is a structured capability module—a Markdown file that defines a workflow, best practices, and references to supporting resources. DeerFlow ships with built-in skills for:

• Research
• Report generation
• Slide creation
• Web pages
• Image and video generation

But the real power is extensibility: add your own skills, replace the built-in ones, or combine them into compound workflows.

Skills are loaded progressively—only when the task needs them, not all at once. This keeps the context window lean and makes DeerFlow work well even with token-sensitive models.

Directory structure (inside sandbox container):

/mnt/skills/public
├── research/SKILL.md
├── report-generation/SKILL.md
├── slide-creation/SKILL.md
├── web-page/SKILL.md
└── image-generation/SKILL.md

/mnt/skills/custom
└── your-custom-skill/SKILL.md      ← yours

Tools follow the same philosophy. DeerFlow comes with a core toolset—web search, web fetch, file operations, bash execution—and supports custom tools via MCP servers and Python functions. Swap anything. Add anything.

Gateway-generated follow-up suggestions now normalize both plain model output and block/list-style rich content before parsing JSON array responses, so provider-specific content wrappers don't silently drop suggestions.

2. Sub-agents: parallel execution for complex tasks

Complex tasks rarely fit in a single pass. DeerFlow decomposes them.

The lead agent can spawn sub-agents on the fly—each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel when possible, report back structured results, and the lead agent synthesizes everything into a coherent output.

This is how DeerFlow handles tasks that take minutes to hours: a research task might fan out into a dozen sub-agents, each exploring a different angle, then converge into a single report—or a website—or a slide deck with generated visuals. One harness, many hands.

Isolated sub-agent contexts: Each sub-agent runs in its own isolated context. This means the sub-agent cannot see the context of the main agent or other sub-agents—ensuring focus on the task at hand without distraction.

3. Sandbox & File System: isolated execution environments

DeerFlow doesn't just talk about doing things. It has its own computer.

Each task gets its own execution environment with a full filesystem view—skills, workspace, uploads, outputs. The agent reads, writes, and edits files. It can view images and, when configured safely, execute shell commands.

Sandbox modes:

1. Local Execution - Runs code directly on host (file tools map to per-thread directories; bash disabled by default)
2. Docker Execution - Runs in isolated Docker containers
3. Docker with Kubernetes - Runs in Kubernetes pods via provisioner service

With AioSandboxProvider, shell execution runs inside isolated containers. With LocalSandboxProvider, file tools still work but host bash is disabled by default because it's not a secure isolation boundary. Re-enable host bash only for fully trusted local workflows.

Filesystem paths (inside sandbox container):

/mnt/user-data/
├── uploads/          ← your files
├── workspace/        ← agents' working directory
└── outputs/          ← final deliverables

This is the difference between a chatbot with tool access and an agent with an actual execution environment.

4. Context engineering: summarization and strict tool-call recovery

Summarization: Within a session, DeerFlow manages context aggressively—summarizing completed sub-tasks, offloading intermediate results to the filesystem, compressing what's no longer immediately relevant. This lets it stay sharp across long, multi-step tasks without blowing the context window.

Strict tool-call recovery: When a provider or middleware interrupts a tool-call loop, DeerFlow now strips provider-level raw tool-call metadata on forced-stop assistant messages and injects placeholder tool results for dangling calls before the next model invocation. This keeps OpenAI-compatible reasoning models that strictly validate tool_call_id sequences from failing with malformed history errors.

5. Long-term memory: persistent across sessions

Most agents forget everything the moment a conversation ends. DeerFlow remembers.

Across sessions, DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge. The more you use it, the better it knows you—your writing style, your technical stack, your recurring workflows. Memory is stored locally and stays under your control.

Memory updates now skip duplicate fact entries at apply time, so repeated preferences and context don't accumulate endlessly across sessions.

6. Claude Code integration: terminal-native workflows

The claude-to-deerflow skill lets you interact with a running DeerFlow instance directly from Claude Code. Send research tasks, check status, manage threads—all without leaving the terminal.

Install the skill:

npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

What you can do:

• Send messages to DeerFlow and get streaming responses
• Choose execution modes: flash (fast), standard, deep
• Check DeerFlow health, list models/skills/agents
• Manage threads and conversation history
• Upload files for analysis

Environment variables (optional, for custom endpoints):

DEERFLOW_URL=http://localhost:2026
DEERFLOW_GATEWAY_URL=http://localhost:2026
DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph

See skills/public/claude-to-deerflow/SKILL.md for full API reference.

IM channel support: Telegram, Slack, Feishu, WeChat, WeCom, DingTalk

DeerFlow supports receiving tasks from messaging apps. Channels auto-start when configured—no public IP required for any of them.

Configuration in config.yaml:

channels:
  langgraph_url: http://localhost:8001/api
  gateway_url: http://localhost:8001

  # Optional: global session defaults
  session:
    assistant_id: lead_agent
    config:
      recursion_limit: 100
    context:
      thinking_enabled: true
      is_plan_mode: false
      subagent_enabled: false

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

  slack:
    enabled: true
    bot_token: $SLACK_BOT_TOKEN
    app_token: $SLACK_APP_TOKEN
    allowed_users: []

  feishu:
    enabled: true
    app_id: $FEISHU_APP_ID
    app_secret: $FEISHU_APP_SECRET

  wechat:
    enabled: false
    bot_token: $WECHAT_BOT_TOKEN
    ilink_bot_id: $WECHAT_ILINK_BOT_ID
    qrcode_login_enabled: true
    allowed_users: []

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

  dingtalk:
    enabled: true
    client_id: $DINGTALK_CLIENT_ID
    client_secret: $DINGTALK_CLIENT_SECRET
    allowed_users: []
    card_template_id: ""  # Optional: AI Card template ID

IM commands:

Messages without a command prefix are treated as regular chat—DeerFlow creates a thread and responds conversationally.

Embedded Python client: no HTTP required

DeerFlow can be used as an embedded Python library without running the full HTTP services. The DeerFlowClient provides direct in-process access to all agent and Gateway capabilities, returning the same response schemas as the HTTP Gateway API.

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# Chat
response = client.chat("Analyze this paper for me", thread_id="my-thread")

# Streaming (LangGraph SSE protocol: values, messages-tuple, end)
for event in client.stream("hello"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])

# Configuration & management — returns Gateway-aligned dicts
models = client.list_models()        # {"models": [...]}
skills = client.list_skills()        # {"skills": [...]}
client.update_skill("web-search", enabled=True)
client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}

All dict-returning methods are validated against Gateway Pydantic response models in CI (TestGatewayConformance), ensuring the embedded client stays in sync with the HTTP API schemas.

See backend/packages/harness/deerflow/client.py for full API documentation.

One-line agent setup for Claude Code / Codex / Cursor

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 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: make setup

1. Clone the repository:

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

2. Run the setup wizard:

make setup

This launches an interactive wizard that guides you through:

• Choosing an LLM provider
• Optional web search configuration
• Execution/safety preferences: sandbox mode, bash access, file-write tools

It generates a minimal config.yaml and writes your keys to .env. Takes about 2 minutes.

3. Verify your setup:

make doctor

4. Start services:

Docker (recommended):

make docker-init    # Pull sandbox image (once)
make docker-start   # Start services

Local development:

make check      # Verify Node.js 22+, pnpm, uv, nginx
make install    # Install dependencies + pre-commit hooks
make dev        # Start services with hot-reload

Access: http://localhost:2026

Deployment sizing

Use this table as a practical starting point when choosing how to run DeerFlow:

Notes:

• These numbers cover DeerFlow itself. If you also host a local LLM, size that service separately.
• Linux + 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.

Recommended models

DeerFlow is model-agnostic—it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:

• Long context windows (100k+ tokens) for deep research and multi-step tasks
• Reasoning capabilities for adaptive planning and complex decomposition
• Multimodal inputs for image understanding and video comprehension
• Strong tool-use for reliable function calling and structured outputs

ByteDance recommends:

• Doubao-Seed-2.0-Code
• DeepSeek v3.2
• Kimi 2.5

Observability: LangSmith and Langfuse tracing

DeerFlow has built-in observability for LangSmith and Langfuse. When enabled, all LLM calls, agent runs, and tool executions are traced.

LangSmith (add to .env):

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
LANGSMITH_PROJECT=xxx

Langfuse (add to .env):

LANGFUSE_TRACING=true
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_BASE_URL=https://cloud.langfuse.com

Using both providers: If both are enabled, DeerFlow attaches both tracing callbacks and reports the same model activity to both systems.

Security notice: improper deployment may introduce risks

DeerFlow has high-privilege capabilities including system command execution, resource operations, and business logic invocation. It is designed by default to be deployed in a local trusted environment (accessible only via 127.0.0.1 loopback interface).

If you deploy DeerFlow in untrusted environments—such as LAN networks, public cloud servers, or other multi-endpoint accessible environments—without security measures, it may introduce security risks:

1. Unauthorized illegal invocation - Agent functionality could be discovered by unauthorized third parties or malicious scanners
2. Compliance and legal risks - If illegally invoked to conduct cyberattacks, data theft, or other illegal activities

Security recommendations:

• IP allowlist - Use iptables, hardware firewalls, or switch ACLs to deny all other IP addresses
• Authentication gateway - Configure reverse proxy (e.g., nginx) with strong pre-authentication
• Network isolation - Place agent and trusted devices in dedicated VLAN, isolated from other networks
• Stay updated - Follow DeerFlow's security feature updates

We strongly recommend deploying DeerFlow in a local trusted network environment.

GitHub stats and community

Key contributors: Daniel Walnut, Henry Li

On February 28th, 2026, DeerFlow claimed the #1 spot on GitHub Trending following the launch of version 2.

Related on ExplainX

• What are agent skills? Complete guide — structured playbooks for agents
• Claude Code vs Codex debate — developer tool comparison
• LangGraph guide — multi-agent orchestration (if you have this article)
• Agent harness engineering — architecture patterns
• Agent skills registry — community-curated agent playbooks
• AI tools directory — discover utilities by task

Bottom line

DeerFlow 2.0 is ByteDance's open-source super agent harness that handles complex, multi-step tasks through sub-agents, skills, sandboxes, and long-term memory. Built on LangGraph + LangChain with 65.7k GitHub stars, it's a complete rewrite (no code shared with v1) that ships batteries included.

Use it for:

• Deep research with multi-agent decomposition
• Data pipelines with sandbox execution
• Content generation (reports, slides, web pages, images, videos)
• Automated workflows via IM channels (Telegram, Slack, Feishu, WeChat, WeCom, DingTalk)
• Claude Code integration for terminal-native agent tasks

The real power: DeerFlow is fully extensible. Add your own skills, replace built-in tools, or embed it as a Python library in your own applications.

Get started: git clone https://github.com/bytedance/deer-flow && cd deer-flow && make setup

This article is an independent summary for developers on explainx.ai and is not sponsored by ByteDance. Features and specifications are based on the public GitHub repository and documentation as of May 7, 2026; verify on the official repo before production use.