DeerFlow 2.0: ByteDance's Ground-Up Rewrite of a Long-Horizon Agent Harness

What DeerFlow 2.0 Actually Replaces

DeerFlow 2.0 is not an incremental update. The README is explicit: it is a ground-up rewrite that shares no code with v1. The original Deep Research framework still lives on the 1.x branch, but active development has moved to 2.0. This matters if you are evaluating DeerFlow for an existing project. Any v1 customizations, plugins, or workflows will not carry over. The project's identity has also shifted. v1 was a deep research tool. 2.0 is described as a super agent harness that researches, codes, and creates. The scope is broader, and the architecture is different. If you need a stable, incremental upgrade path, this is not it. If you are starting fresh and want a long-horizon agent system, the rewrite is the intended entry point.

How the Harness Orchestrates Work

The core mechanism is orchestration across several components. The README lists sub-agents, memory, sandboxes, tools, skills, and a message gateway as the building blocks. Sub-agents handle parallel or delegated pieces of a task. Memory provides long-term state across runs. Sandboxes provide isolated execution environments. Skills are extensible units that add capabilities. The message gateway likely routes messages between the harness, sub-agents, and external channels, though the README does not detail the protocol. The system is designed for tasks that take minutes to hours, which implies a persistent loop rather than a single prompt-response cycle. The harness manages context, decides when to spawn sub-agents, and uses memory to retain information across steps. This is a different model from a simple chain-of-thought wrapper. It is closer to a small operating system for agents.

Getting It Running: The Setup Wizard and Docker Path

The recommended path is Docker, but the first step is the same for both options: clone the repository and run make setup. The README gives the exact commands: git clone https://github.com/bytedance/deer-flow.git, then cd deer-flow, then make setup. The wizard is interactive and guides you through choosing an LLM provider, optional web search, and execution and safety preferences such as sandbox mode, bash access, and file-write tools. It generates a minimal config.yaml and writes your keys to .env. The README says the process takes about two minutes. After setup, you can run make doctor to verify the installation and get fix hints. For manual configuration, make config copies the full template, and config.example.yaml is the reference. The wizard's role is significant: it encodes safety choices at setup time, which is a sensible guard for a tool that can execute code.

Sandbox Modes and the Security Trade-off

The README includes a security notice that improper deployment may introduce security risks. This is not boilerplate. The harness can execute code, and the setup wizard asks about sandbox mode and bash access. If you enable bash access, you are giving the agent direct shell capabilities. The sandbox mode is meant to contain that risk, but the README does not explain the isolation boundaries. It also mentions file-write tools, which means the agent can modify files on the host if not sandboxed. For any deployment that touches sensitive data or production systems, the sandbox must be configured correctly. The security recommendations are not detailed in the visible portion, but the warning is clear. This is a tool for controlled environments, not for casual experimentation on a machine with important files. The trade-off is between agent autonomy and host safety, and the project leaves the balance to the operator.

Context Engineering and Long-Term Memory

Two features stand out in the core features list: context engineering and long-term memory. Context engineering is about managing the token budget across long runs. The README also mentions manual context compaction, which lets you shrink the context when it grows too large. This is a practical necessity for tasks that run for hours. Without compaction, the context window would fill up and degrade output quality. Long-term memory is separate from context. It persists across sessions, so the agent can recall facts or decisions from previous runs. The README does not specify the storage backend or retrieval mechanism, but the presence of these features suggests a deliberate design for sustained work. The combination of compaction and memory is what allows the harness to go beyond single-shot tasks. It is a point of differentiation from simpler agent frameworks that reset state after each call.

Skills, Tools, and the Claude Code Integration

Skills are the extensibility mechanism. The README says the harness is powered by extensible skills, and lists Claude Code integration as a specific skill. This means you can plug in an existing coding agent rather than building code execution from scratch. The integration is a notable choice because it acknowledges that code generation and execution are hard problems, and reusing a mature tool is pragmatic. The skills system is likely how you add new capabilities without modifying the core harness. The README does not provide a skill API or examples, so the learning curve is unclear. But the architecture is clear: skills are the unit of extension, and tools are the lower-level primitives they use. For teams evaluating DeerFlow, the skills system is the first thing to test, because it determines how much you can customize behavior without forking the project.

Multi-Provider Support and the Recommended Model List

DeerFlow supports multiple LLM providers. The setup wizard asks you to choose one, and config.example.yaml includes CLI-backed providers like Codex CLI and Claude Code OAuth, plus OpenRouter and the Responses API. This is a flexible setup for teams that already use specific providers. However, the README strongly recommends a short list: Doubao-Seed-2.0-Code, DeepSeek v3.2, and Kimi 2.5. These are the models the project has tuned for. If you use a different model, you may encounter issues with tool calling, context compaction, or sub-agent coordination. The README also notes a constraint on pricing: optional per-model pricing must use one currency across all priced models, and Console cost estimates are disabled when currencies are mixed. This is a small but concrete limitation. It means if you run models from providers that bill in different currencies, you lose cost tracking in the console.

Tracing, Scheduling, and the Terminal Workbench

The README lists LangSmith, Langfuse, and Monocle tracing as options. These are observability backends for debugging agent runs. Given the complexity of long-horizon tasks, tracing is not optional; you need to see what the agent did and why. The README also mentions scheduled tasks, which let you run agents on a schedule, and a terminal workbench (TUI) for interactive use. The TUI is a different interface from the web app, and it is useful for developers who live in the terminal. The combination of tracing, scheduling, and a TUI suggests a tool aimed at developers who want to integrate agents into their workflows, not just try a demo. The embedded Python client is another integration point, though the README does not show its API. These features collectively make DeerFlow a serious platform, but they also add operational overhead: you need to configure tracing, manage schedules, and learn the TUI.

Maintenance and Upgrade Cost

DeerFlow 2.0 was released on June 25, 2026, and the last push is the same date. This is a very fresh release. The README states that v1 is on the 1.x branch and contributions are still welcome there, but active development is on 2.0. The maintenance cost is therefore uncertain. A ground-up rewrite means the codebase is new, and the community is still forming. The project has a support bundle command (make support-bundle) that generates redacted diagnostics for issue reporting. This is a thoughtful touch for maintenance. It suggests the maintainers expect real-world issues and want reproducible reports. The license is MIT, which is permissive and allows commercial use without copyleft obligations. However, the README promotes ByteDance's Volcengine coding plan and InfoQuest toolset, so there is a commercial tie-in. If you adopt DeerFlow, you are adopting a project that is actively steered by ByteDance, and the roadmap may prioritize their ecosystem.

Editorial conclusion

Adopt DeerFlow 2.0 if you need a self-hosted harness for multi-step agent tasks that can run unattended for hours, and you are comfortable with the Docker-first deployment and the need to configure sandboxing carefully. Do not adopt it if you rely on the v1 deep research pipeline, since 2.0 shares no code with v1 and the old branch is only maintained for contributions. Before adopting, verify that your chosen LLM provider is among the recommended ones (Doubao-Seed-2.0-Code, DeepSeek v3.2, Kimi 2.5), confirm that your target models support the tool-calling and context-compaction features you need, and review the security notice about improper deployment risks, especially if you enable bash access or file-write tools.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes