DeerFlow: ByteDance's Super Agent Harness

ByteDance released DeerFlow 2.0 as a ground-up rewrite in February 2026. Within weeks it claimed the #1 spot on GitHub Trending, accumulating 38,000 stars and 4,500 forks. The repository maintains 147 contributors with daily commits addressing everything from hotkey support to Kubernetes sandbox provisioners.

DeerFlow positions itself not as a framework but as a "super agent harness"—a runtime environment that gives agents the infrastructure to execute tasks, not just generate text. This distinction matters. Most agent tools focus on prompt engineering and LLM invocation. DeerFlow adds filesystem persistence, sandboxed code execution, sub-agent spawning, long-term memory, and multi-channel messaging integration.

From Research Tool to Execution Harness

The 1.x branch of DeerFlow was a Deep Research framework—useful for information gathering, limited in action. The community extended it beyond the original scope: data pipelines, slide generation, dashboard creation, content workflows. This usage pattern revealed that DeerFlow had become something else entirely: a runtime for autonomous agents.

Version 2.0 embraces this evolution. The architecture now explicitly supports sub-agents with isolated contexts, each receiving scoped tasks and returning structured results. A research task might spawn a dozen parallel agents, each exploring different angles, with results synthesized into reports, websites, or slide decks with generated visuals.

Architecture: LangGraph-Based Orchestration

DeerFlow builds on LangGraph and LangChain for workflow orchestration. The system defines agent nodes that communicate through a graph structure:

Agent Node	Function	Context Scope
Coordinator	Entry point, handles initial interaction	Session-wide
Planner	Creates research plans, coordinates tasks	Task planning
Researcher	Web searches, information gathering	Per-query isolation
Coder	Code generation and execution	Sandbox environment
Reporter	Final reports, summaries, citations	Output generation

The lead agent can spawn sub-agents dynamically. Each sub-agent operates in isolation—no access to parent context or sibling agents. This prevents context pollution and keeps sub-agents focused on specific tasks.

Sandbox Execution: Beyond Tool Calls

DeerFlow provides three sandbox modes:

• Local execution: Runs code directly on host machine (fastest, least isolated)
• Docker execution: Isolated containers with dedicated filesystem
• Kubernetes execution: Pods via provisioner service for scaled deployments

Each sandbox provides a full filesystem at standard paths:

/mnt/user-data/
├── uploads/     ← User files
├── workspace/   ← Agent working directory
└── outputs/     ← Final deliverables

The distinction between "chatbot with tool access" and "agent with execution environment" is significant. DeerFlow agents read, write, and edit files. They execute bash commands and Python code. They view images. All actions are sandboxed and auditable.

Skills System: Progressive Capability Loading

Skills in DeerFlow are structured capability modules—Markdown files defining workflows, best practices, and supporting resources. The system ships with built-in skills for research, report generation, slide creation, web pages, and image/video generation.

Skills load progressively: only when a task requires them, not all at once. This keeps context windows manageable even with token-sensitive models. The skills directory structure:

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

Custom skills can be added through the Gateway interface. DeerFlow accepts standard frontmatter metadata (version, author, compatibility) without rejecting otherwise valid external skills.

Context Engineering Features

DeerFlow implements several context management strategies:

Isolated Sub-Agent Context: Each sub-agent sees only its assigned task context. This is enforced architecturally, not just by convention.

Session Summarization: Within a single session, completed sub-tasks are summarized, intermediate results offloaded to the filesystem, and completed work compressed. This prevents context window overflow during long, multi-step tasks.

Long-Term Memory: Across sessions, DeerFlow maintains persistent memory of user profiles, preferences, and accumulated knowledge. Memory is stored locally (not in cloud services) and improves gradually through use—learning writing styles, technical stacks, recurring workflows.

Multi-Channel Integration

DeerFlow integrates with messaging platforms without requiring public IP addresses. Supported channels:

Channel	Transport	Setup Complexity
Telegram	Bot API (long-polling)	Easy
Slack	Socket Mode	Moderate
Feishu/Lark	WebSocket	Moderate

Each channel auto-starts when configured. No webhook servers or public endpoints required. Commands are available in-channel:

/new      → Start new conversation
/status   → Show current thread info
/models   → List available models
/memory   → View memory
/help     → Show help

Model Provider Flexibility

DeerFlow is model-agnostic with explicit support for OpenAI-compatible APIs. Configuration in config.yaml:

models:
  - name: gpt-4
    display_name: GPT-4
    use: langchain_openai:ChatOpenAI
    model: gpt-4
    api_key: $OPENAI_API_KEY
    
  - name: openrouter-gemini
    display_name: Gemini (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENAI_API_KEY
    base_url: https://openrouter.ai/api/v1
    
  - name: codex-cli
    display_name: GPT-5.4 (Codex CLI)
    use: deerflow.models.openai_codex_provider:CodexChatModel
    model: gpt-5.4
    supports_thinking: true

The system also supports Claude Code OAuth integration and Codex CLI as first-class providers, reading credentials from ~/.claude/.credentials.json and ~/.codex/auth.json respectively.

Recommended Models

ByteDance explicitly recommends specific models for DeerFlow:

• Doubao-Seed-2.0-Code (ByteDance's own model)
• DeepSeek v3.2
• Kimi 2.5

DeerFlow performs best with models supporting: 100k+ token context windows, reasoning capabilities for adaptive planning, multimodal inputs, and strong tool-use for reliable function calling.

Comparison with OpenClaw Architecture

Both systems pursue multi-agent orchestration but with different emphases:

Aspect	DeerFlow	OpenClaw
Primary runtime	Self-hosted Docker/Kubernetes	Gateway daemon + clients
Agent spawning	In-process via LangGraph	External sessions_spawn
Context isolation	Architectural (sub-agent nodes)	Process-based (sub-agents)
Skills system	Markdown + Gateway loading	Markdown + local skills/
Sandbox	Docker/Kubernetes/Local	Host or containerized
Memory	Local persistent storage	ByteRover + memory files
IM channels	Built-in (Telegram, Slack, Feishu)	Gateway-supported (Telegram, Discord, etc.)

DeerFlow emphasizes a unified, self-contained runtime. OpenClaw distributes capabilities across a Gateway daemon and multiple client interfaces. DeerFlow targets deployment as a service; OpenClaw targets personal assistant integration.

Technical Assessment

Strengths:

• Complete agent infrastructure in one repository
• LangGraph provides proven orchestration patterns
• Sandbox execution enables genuine autonomous operation
• Progressive skill loading manages context efficiently
• Built-in multi-channel support reduces integration friction
• Daily active development (commits within hours)

Considerations:

• Docker required for full feature set (no pure-local mode)
• Kubernetes sandbox adds operational complexity
• Self-hosted model requires infrastructure maintenance
• 147 contributors means rapid change, potential instability
• No managed cloud offering (must self-host)

Conclusion

DeerFlow represents a mature approach to agent infrastructure. It does not attempt to be a language model or a prompt template library. It provides the runtime environment that makes autonomous agents feasible: execution sandboxes, memory persistence, multi-agent coordination, and channel integration.

The 38,000 GitHub stars reflect genuine utility, not hype. The codebase demonstrates production engineering: comprehensive Docker setup, Kubernetes support, structured configuration, and daily maintenance. For teams building autonomous agents that need to execute code, manage files, and coordinate sub-agents, DeerFlow provides a complete foundation.

Use DeerFlow when you need a self-hosted agent runtime with execution capabilities, sub-agent orchestration, and multi-channel deployment. Consider OpenClaw when you need personal assistant integration with distributed client support.

Quick Facts

Metric	Value
GitHub Stars	38,000
Forks	4,500
Contributors	147
License	MIT
Primary Language	Python 56%
Version	2.0 (ground-up rewrite)
Release Date	February 2026
Repository	github.com/bytedance/deer-flow

Architecture Overview

Layer	Technology
Workflow Orchestration	LangGraph
LLM Integration	LangChain
Backend	Python (Poetry)
Frontend	Next.js
Sandbox	Docker / Kubernetes / Local
Memory	Local persistent storage

Agent Node Types

Node	Function	Isolation
Coordinator	Entry point, session handling	Session-wide
Planner	Task decomposition	Planning context
Researcher	Web search, data gathering	Per-query
Coder	Code generation/execution	Sandbox
Reporter	Report generation, citations	Output scope

Sandbox Modes

Mode	Isolation	Speed	Use Case
Local	Low	Fastest	Development
Docker	Medium	Medium	Production
Kubernetes	High	Slower	Scale

Supported IM Channels

Channel	Transport	Setup
Telegram	Bot API (long-polling)	Easy
Slack	Socket Mode	Moderate
Feishu/Lark	WebSocket	Moderate

Available Commands (In-Channel)

Command	Function
/new	Start new conversation
/status	Show thread info
/models	List models
/memory	View memory
/help	Show help

Recommended Models

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

Requirements

• Python 3.11+
• Node.js 22+
• Docker (for sandboxed execution)
• API keys for chosen LLM provider

Quick Start

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make config              # Generate config files
# Edit config.yaml and .env with API keys
make docker-init         # Pull sandbox image
make docker-start        # Start services

DeerFlow vs OpenClaw

Aspect	DeerFlow	OpenClaw
Runtime	Self-hosted Docker/K8s	Gateway + clients
Agent spawning	In-process (LangGraph)	sessions_spawn
Isolation	Node-level	Process-level
Skills	Markdown + Gateway	Markdown + local
Target	Service deployment	Personal assistant

DeerFlow for Builders

Direct implementation patterns for extending DeerFlow or integrating with it.

Custom Skill Definition

---
name: my-skill
version: 1.0.0
author: your-name
compatibility: deerflow >=2.0
---

# My Custom Skill

**Purpose:** [One-line description]

## When to Use

- Trigger condition 1
- Trigger condition 2

## Workflow

1. Step one
2. Step two
3. Step three

## Parameters

- `input_file`: Path to input
- `output_format`: json | markdown | html

## Example

```
DeerFlow, analyze this CSV using my-skill
```

Adding Custom Tools (Python)

# backend/app/tools/custom_tool.py
from langchain.tools import BaseTool
from pydantic import Field

class CustomSearchTool(BaseTool):
    name: str = "custom_search"
    description: str = "Search custom index"
    
    api_endpoint: str = Field(default="https://api.example.com/search")
    
    def _run(self, query: str) -> str:
        # Implementation
        response = requests.get(f"{self.api_endpoint}?q={query}")
        return response.json()["results"]

MCP Server Integration

# config.yaml - MCP server configuration
mcp_servers:
  - name: my-mcp-server
    url: https://mcp.example.com/sse
    auth:
      type: oauth
      flow: client_credentials
      client_id: $MCP_CLIENT_ID
      client_secret: $MCP_CLIENT_SECRET

Embedded Python Client

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

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

# Streaming
for event in client.stream("hello"):
    if event.type == "messages-tuple":
        print(event.data["content"])

# Management
models = client.list_models()
skills = client.list_skills()
client.upload_files("thread-1", ["./report.pdf"])

Sub-Agent Spawn Pattern

# Within a DeerFlow skill or node

# 1. Define sub-agent task
sub_agent_task = {
    "task": "Research sub-topic X",
    "context": {"parent_goal": "Main research goal"},
    "tools": ["web_search", "web_fetch"],
    "max_iterations": 10
}

# 2. Spawn sub-agent (LangGraph pattern)
from langgraph.types import Command

# Sub-agent runs in isolation
# Returns structured result to parent
result = await spawn_sub_agent(sub_agent_task)

# 3. Synthesize results
final_output = synthesize([result1, result2, result3])

Channel Webhook Handler (Custom)

# Custom channel integration
# Add to backend/app/channels/

from deerflow.channels.base import BaseChannel

class DiscordChannel(BaseChannel):
    name = "discord"
    
    async def start(self):
        # Connect to Discord Gateway
        # Listen for messages
        # Route to DeerFlow coordinator
        pass
    
    async def handle_message(self, message):
        # Parse commands (/new, /status)
        # Route to appropriate handler
        # Return responses to Discord

Configuration Patterns

# config.yaml - Complete example
models:
  - name: primary-llm
    use: langchain_openai:ChatOpenAI
    model: gpt-4
    api_key: $OPENAI_API_KEY
    max_tokens: 4096
    temperature: 0.7

sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8080  # K8s mode
  # Or for Docker:
  # use: deerflow.community.docker_sandbox:DockerSandboxProvider

channels:
  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []  # Empty = all users
  
  slack:
    enabled: false  # Enable when configured
    bot_token: $SLACK_BOT_TOKEN
    app_token: $SLACK_APP_TOKEN

memory:
  persistence: true
  storage_path: /mnt/user-data/memory

Docker Compose Extension

# docker-compose.custom.yml
version: '3.8'
services:
  deerflow:
    extends:
      file: docker-compose.yml
      service: deerflow
    volumes:
      - ./custom-skills:/mnt/skills/custom:ro
      - ./outputs:/mnt/user-data/outputs
    environment:
      - CUSTOM_API_KEY=${CUSTOM_API_KEY}
  
  # Add custom service
  custom-indexer:
    image: my-indexer:latest
    networks:
      - deerflow-network

Testing Skills Locally

# Test skill without full deployment
# Using DeerFlow embedded client

from deerflow.client import DeerFlowClient
from pathlib import Path

client = DeerFlowClient()

# Load skill
skill_path = Path("./my-skill/SKILL.md")
skill_content = skill_path.read_text()

# Test execution
response = client.chat(
    f"Execute this skill: {skill_content}\n\nTask: [test task]"
)

print(response)

Deployment Checklist

• [ ] Clone repository: git clone https://github.com/bytedance/deer-flow.git
• [ ] Generate config: make config
• [ ] Edit config.yaml — define at least one model
• [ ] Set API keys in .env file
• [ ] Initialize Docker: make docker-init
• [ ] Start services: make docker-start
• [ ] Verify: http://localhost:2026
• [ ] Configure IM channels (optional)
• [ ] Add custom skills to /mnt/skills/custom/
• [ ] Test sub-agent spawning
• [ ] Enable persistent memory