# DeerFlow 2.0: ByteDance's Super Agent Harness, Reviewed for Engineers

> DeerFlow 2.0 is a ground-up rewrite of ByteDance's research agent into a general harness that orchestrates sub-agents, sandboxes and memory. It is MIT licensed, Python-based, and set up through an interactive wizard rather than a config file you write by hand.

**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 tasks that could take minutes to hours.

- Repository: https://github.com/bytedance/deer-flow
- Website: https://deerflow.tech
- Stars: 83,220 · Forks: 11,546
- Language: Python
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/bytedance-deer-flow

## What DeerFlow 2.0 replaces, and for whom

DeerFlow stands for Deep Exploration and Efficient Research Flow. The 1.x line was a deep research framework: give it a question, it searches, reads and writes a report. Version 2.0 is described in the README as a ground-up rewrite that "shares no code with v1", and the framing has changed from research framework to super agent harness. The stated job is handling tasks that run from minutes to hours, with sandboxes, memories, tools, skills, sub-agents and a message gateway doing the work.

That shift matters when you decide whether to adopt it. A research tool answers questions. A harness executes long-horizon work: it writes files, runs commands in a sandbox, spawns sub-agents for parallel branches, and keeps state between sessions. The intended user is an engineer or technical team that wants that machinery self-hosted and inspectable rather than rented from a hosted agent product. The README also points at a companion desktop tool, LLM Space, for prototyping agent ideas and replaying failures, which suggests the project expects users to debug agent behaviour rather than just consume outputs.

The cost of the rewrite is real. If you built on the 1.x API, nothing carries over. The README says the original framework is maintained on the 1.x branch and that contributions there are still welcome, but active development has moved to 2.0.

## How the harness is put together

The repository layout tells you most of the architecture before you read any code. There is a backend/ directory with a pyproject.toml, a frontend/ directory, a deploy/ and docker/ pair for containerised runs, a skills/ directory, a contracts/ directory, and tests/. The Makefile is the single entry point for nearly everything: setup, doctor, dev, docker-start, and the extension commands.

At runtime the pieces the README names are sub-agents, memory, sandboxes, tools, skills and a message gateway. Sub-agents are the parallel branch mechanism, and the config reference exposes runtime caps such as subagents.max_total_per_run, so a single run has a bounded number of sub-agents rather than an unbounded fan-out. The sandbox and file system give the agent a place to write and execute, which is why the security notice exists at all. Long-term memory and context engineering are separate features, and the README lists manual context compaction as a user-facing control, meaning the harness does not silently decide what to forget.

Skills and tools are the extension surface. There is a Claude Code integration listed under that heading, and the repository ships extensions_config.example.json alongside config.example.yaml, so extensions are configured rather than compiled in. The message gateway is what connects the agent to IM channels, which is how a long-running task can report back to a chat rather than a terminal you keep open.

## Installing DeerFlow 2.0 and running a first task

The README's Quick Start assumes Docker is the preferred path and that you have an LLM provider key. Start by cloning the repository and running the setup wizard from the project root.

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

The wizard is interactive. According to the README it walks you through choosing an LLM provider, an optional web search provider, 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 states this takes about two minutes. You can skip web search at this stage and add it later.

Before starting anything, verify the environment. The Makefile defines doctor as a check of configuration and system requirements, and the README says it gives actionable fix hints.

```bash
make doctor
```

If you would rather edit configuration by hand than answer the wizard, run make config instead. The Makefile help text says it generates local config files and aborts if config.yaml already exists, so it will not silently overwrite your work. config.example.yaml is the full reference, including CLI-backed providers such as Codex CLI and Claude Code OAuth, OpenRouter, the Responses API, and the subagent runtime caps mentioned earlier.

Finally, bring the stack up. The Makefile exposes docker-start for the containerised path and dev for local development.

```bash
make docker-start
```

The .env.example file documents the entry port as PORT=2026 and the bind interface as BIND_HOST, which defaults to 127.0.0.1. That default is deliberate: the file notes it matches a local-trusted-environment deployment model because the agent can execute commands. Set BIND_HOST=0.0.0.0 only when the host sits behind your own TLS, authentication or firewall, and complete first-run setup before it becomes reachable. If you are running split-origin or port-forwarded deployments, GATEWAY_CORS_ORIGINS takes a comma-separated list of exact origins; leave it unset when using the unified nginx endpoint.

## The security boundary you inherit the moment it runs

DeerFlow executes commands. The README carries a security notice titled "Improper Deployment May Introduce Security Risks", and the .env.example comments repeat the reasoning: BIND_HOST defaults to loopback precisely because the agent can execute commands. This is not a footnote. Any harness that gives a model bash access and file writes inherits the blast radius of the host it runs on.

The practical consequence is that the default configuration is safe only on a machine you already trust. The moment you set BIND_HOST=0.0.0.0 to reach the UI from another machine, you have taken on the job of putting an authenticating front door in front of it. The .env.example is explicit that this should only happen when the host is protected by your own TLS, auth or firewall, and that first-run setup should be complete before the port becomes reachable.

There is a second, quieter boundary: what leaves your machine. The .env.example lists API keys for Serper, Serply, Tavily, Jina, InfoQuest, Sofya, Firecrawl, Volcengine, OpenAI, Gemini, DeepSeek, Novita, MiniMax and OpenViking. Every search or model call goes to whichever of those you configured. The README's support-bundle command is worth noting here for the opposite reason: it is described as including redacted diagnostics and file manifests only, and as not including .env, raw conversation messages or user file contents. That is a reasonable default for a project whose users will file issues containing runtime state.

## Where DeerFlow 2.0 is the wrong tool

The clearest limitation is version churn. The README states plainly that 2.0 shares no code with v1 and that the original Deep Research framework lives on the 1.x branch. If you need an API that stays put across upgrades, this is a moving target, and the maintenance load falls on you at every major version.

Second, this is not a library you import and forget. The Makefile is the interface, the setup path is an interactive wizard, and the configuration surface spans config.yaml, .env, extensions_config.example.json and a sandbox mode setting. The README offers an embedded Python client, so programmatic use exists, but the primary shape is a running service with a frontend, a gateway and a sandbox. That is a lot of surface for a team that wanted one function call.

Third, the model is not included. The README recommends Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5, and links to a ByteDance Volcengine coding plan. Those recommendations are tied to a commercial offering from the same parent company, which is worth noticing even though the project itself is MIT licensed and configurable to other providers. You are supplying inference, search and crawling keys either way.

Finally, the README notes one concrete configuration constraint: optional per-model pricing must use one currency across all priced models, and DeerFlow disables Console cost estimates when currencies are mixed. If you want cost visibility, keep your pricing table in a single currency.

## How it differs from a coding agent like Claude Code

The comparison people reach for is Claude Code, and the difference is in what the agent is pointed at. Claude Code is a coding agent: it works inside a repository, reads and edits files, runs tests, and its unit of work is a change to a codebase. DeerFlow is a harness for long-horizon tasks that may involve research, code and content creation, and it brings its own scaffolding for that: sub-agents for parallel branches, long-term memory across sessions, a sandbox and file system, a message gateway for IM channels, and scheduled tasks.

The overlap is real, and the project acknowledges it. DeerFlow lists a Claude Code integration under Skills and Tools, and config.example.yaml is documented as supporting CLI-backed providers including Codex CLI and Claude Code OAuth. So the relationship is closer to nesting than replacement: you can drive DeerFlow with a coding-agent CLI as the model backend.

The practical difference shows up in state. A coding agent's context is the repository. DeerFlow's context is engineered explicitly, with long-term memory and manual context compaction as named features, and it can be reached through chat channels rather than only a terminal. If your task is "change this function and run the tests", a coding agent is the smaller, better-fitting tool. If your task is "spend the next two hours gathering, writing and filing something, then tell me in Slack", the harness is doing work a coding agent was not built for.

## Maintenance, licensing and what an upgrade costs

DeerFlow is MIT licensed, and the LICENSE file sits at the repository root. MIT is permissive: you can use, modify and redistribute it, including commercially, provided the copyright notice and permission notice are retained. That is the extent of what the repository states; anything about your specific obligations is a question for your own counsel, not for this article.

On maintenance, the last push to the default branch was on 2026-06-25, the same date as the v2.0.0 release. The repository is not archived. That date is roughly three months before the time of writing, so the project is not dormant, but the release cadence visible here is a single 2.0.0 tag rather than a stream of patch releases. Plan for that: there is no long tail of point releases to lean on if you hit a bug in the 2.0 line.

The upgrade path has a tool for it. The Makefile defines config-upgrade, described in its help text as merging new fields from config.example.yaml into config.yaml. That is the mechanism to use when a new release adds configuration keys, and it is preferable to regenerating config.yaml with make config, which aborts if the file already exists. There is also a CHANGELOG.md and CHANGELOG_zh.md at the root, and a RELEASING.md, so release notes are a maintained artefact rather than an afterthought.

The real upgrade cost is the 1.x to 2.x jump, which the README describes as a rewrite with no shared code. If you are on 1.x, treat 2.0 as a new deployment with a new configuration, not a version bump.

## Conclusion

Adopt DeerFlow 2.0 if you want a self-hosted harness that already wires sub-agents, a sandboxed file system, long-term memory and IM channels together, and if you are willing to supply your own model and search keys. Skip it if you need a stable API surface across versions: the README states 2.0 shares no code with v1, and the original Deep Research framework now lives on the 1.x branch. Before committing, run make doctor on the target host, read config.example.yaml for the subagent runtime caps, and check the security notice about deployment exposure.

## FAQ

### What is DeerFlow?

DeerFlow stands for Deep Exploration and Efficient Research Flow. The README describes it as an open-source super agent harness that orchestrates sub-agents, memory and sandboxes to handle tasks that can take minutes to hours, powered by extensible skills.

### Is DeerFlow free?

The project is MIT licensed, so the code itself is free to use, modify and redistribute. You still pay for what it calls out to: you supply your own LLM provider and optional web search keys through the setup wizard, which writes them to .env.

### How to install DeerFlow?

Clone the repository, then run make setup from the project root. The README states the wizard guides you through choosing an LLM provider, optional web search, and sandbox and bash-access preferences, generating a minimal config.yaml and writing keys to .env in about two minutes. Run make doctor afterwards to verify the setup.

### What is DeerFlow 2.0?

DeerFlow 2.0 is a ground-up rewrite of the project, released as v2.0.0. The README states it shares no code with v1 and that the original Deep Research framework is maintained on the 1.x branch while active development has moved to 2.0.

### How do you use DeerFlow with Claude Code?

DeerFlow lists a Claude Code integration under Skills and Tools, and config.example.yaml is documented as supporting CLI-backed providers including Codex CLI and Claude Code OAuth. The README also offers a one-line prompt that hands a coding agent the setup instructions in Install.md.

### How to use DeerFlow?

After make setup, start the stack with make docker-start for the containerised path or make dev for local development. Configuration lives in config.yaml and .env, with config.example.yaml as the full reference, and make doctor reports setup problems.

## Sources

- [Official documentation](https://deerflow.tech)
- [Official README](https://github.com/bytedance/deer-flow#readme)
- [Project repository](https://github.com/bytedance/deer-flow)
- [Release notes](https://github.com/bytedance/deer-flow/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bytedance-deer-flow