# DeerFlow: features, protocols, quickstart

## TL;DR

DeerFlow 2.0 is ByteDance's MIT-licensed "super agent harness", a ground-up rewrite of its earlier Deep Research framework, built on LangGraph and LangChain. A lead agent plans, uses sandboxes, skills, memory and MCP tools, and spawns sub-agents for long tasks. It suits teams self-hosting research, report and coding agents.

## Key facts

| Field | Value |
| --- | --- |
| Type | Harness |
| Languages / SDKs | Python, TypeScript |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Supervisor |
| GitHub stars | 83,261 (as of 2026-09-30) |
| GitHub forks | 11,552 |
| Last push | 2026-09-30 |
| Latest release | v2.1.0 |
| Repository | [bytedance/deer-flow](https://github.com/bytedance/deer-flow) |
| Website | [deerflow.tech](https://deerflow.tech) |
| Documentation | [github.com](https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md) |
| Last verified | 2026-09-30 |

## Key features

- A lead agent spawns sub-agents through a task tool, each with its own scoped context, model, tools and skill limits; context_mode="snapshot" hands over the parent's conversation history. ([source](https://github.com/bytedance/deer-flow#sub-agents))
- batch_task runs large sets of independent items as durable, SQL-backed work with concurrency limits, retries and restart recovery. ([source](https://github.com/bytedance/deer-flow#sub-agents))
- Sandbox modes run tool code on the host, in Docker containers, or in Kubernetes pods through a provisioner service. ([source](https://github.com/bytedance/deer-flow#sandbox-mode))
- MCP servers (stdio, HTTP and SSE, with OAuth for HTTP/SSE) and skills are configured in extensions_config.json. ([source](https://github.com/bytedance/deer-flow/blob/main/backend/docs/MCP_SERVER.md))
- An invoke_acp_agent tool hands work to external ACP agents such as Claude Code and Codex (through ACP adapters) or MiniMax Code. ([source](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml))
- Tasks can arrive from Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat and WeCom channels without a public IP. ([source](https://github.com/bytedance/deer-flow#im-channels))
- An embedded Python client (DeerFlowClient) exposes chat, streaming, skills, uploads and goals in-process without the HTTP services. ([source](https://github.com/bytedance/deer-flow#embedded-python-client))

## Architecture and orchestration pattern

Pattern: Supervisor.

DeerFlow 2.0 runs its agent inside a FastAPI Gateway and is built on LangGraph: `make_lead_agent` builds a LangGraph agent wrapped in a middleware chain (thread data, uploads, sandbox acquisition, summarization, titles and more), and the Gateway exposes LangGraph-compatible thread and run routes to a Next.js web UI, IM channels and a terminal workbench. The same backend is available in-process through `DeerFlowClient`.

Multi-agent work is supervisor-style. The lead agent decides when delegation pays off and calls `task` to start a sub-agent with its own context, model, tools and termination conditions; independent read-only work can run concurrently, while interdependent work stays with the lead. `batch_task` moves large independent item sets into a durable SQL-backed queue that survives Gateway restarts, and both paths share one sub-agent runtime capacity. Custom agents can be limited to a chosen set of sub-agents, and `invoke_acp_agent` delegates to external coding agents over ACP.

State lives in LangGraph checkpoints and a store (backed by the configured database), files live in a per-thread workspace inside the chosen sandbox, and long-term memory (DeerMem) extracts facts and summaries across conversations.

### Human in the loop

A run's interaction policy decides whether a human can be asked. In interactive runs the agent can pause with a clarification card in the web UI, which the user can answer or bypass with a normal chat message, and sandbox network requests can open a Human Input card for approval. Scheduled, webhook and autonomous runs never wait for a person; they make minimal reversible assumptions or return a structured BLOCKED result. Sub-agents always deny pending network requests. ACP agents can be configured with `auto_approve_permissions: false` so their permission requests are not approved automatically, and Stop interrupts a delegated task so the next turn can retry it.

### Harnesses it can drive

- Claude Code ([evidence](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml))
- Codex ([evidence](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://github.com/bytedance/deer-flow/blob/main/backend/docs/MCP_SERVER.md) | Client: stdio and HTTP/SSE MCP servers are loaded from extensions_config.json and registered as agent tools, with OAuth token flows for HTTP/SSE. |
| A2A | Unknown (checked 2026-09-30) | — | No A2A mention in the README or backend docs; GitHub code search for a2a in bytedance/deer-flow only matched hash strings in demo and experiment JSON files. |
| AG-UI | Unknown (checked 2026-09-30) | — | The only hit is backend/docs/STREAMING.md naming AG-UI as an example of a callback-style consumer of LangGraph custom events; no AG-UI adapter or endpoint is documented, and DeerFlow is not in the AG-UI README list. |

## Best for

- Long research and report tasks where a lead agent fans read-only investigation out to sub-agents. ([shortlist](https://multiagentguide.top/best/research-agents.md))
- Self-hosting an agent with Docker or Kubernetes sandboxes on your own server, reachable from chat apps. ([shortlist](https://multiagentguide.top/best/self-hosted-local.md))
- Batch jobs over many independent items that must survive restarts, using durable batch_task.
- Delegating implementation steps to Claude Code, Codex or MiniMax Code over ACP from a larger workflow. ([shortlist](https://multiagentguide.top/best/coding-agents.md))

## Not for

- Exposure on untrusted networks without extra controls: the project says it is designed for a local trusted environment on 127.0.0.1.
- Small machines: the README suggests at least 4 vCPU and 8 GB RAM even for local evaluation.
- Users looking for the original Deep Research framework API; that code lives on the 1.x branch.

## Quickstart

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

Install not yet verified by this site.

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

make setup          # wizard: model provider, web search, sandbox mode, bash access
make doctor         # check the generated config.yaml

# Option 1: Docker development stack (needs Docker Compose v2.24+)
make docker-init    # pull the sandbox image once
make docker-start   # Gateway, web UI and sandbox

# Option 2: local services (needs Node.js 22+, pnpm, uv, nginx)
make check && make install && make dev

# then open http://localhost:2026 and ask for a task that benefits from sub-agents
```

### Common pitfalls

- Requires Python 3.12+ and Node.js 22+ for local development; Docker mode needs Docker Compose v2.24+.
- Sizing: the README suggests 4 vCPU, 8 GB RAM and 20 GB free disk as a starting point for local evaluation, more for Docker or shared servers.
- Local Execution sandbox mode runs code directly on the host; use Docker or Kubernetes sandboxes for isolation.
- An admin who can register stdio MCP servers can effectively execute code on the host; treat Gateway admin as host-level access.
- The Docker stack binds to 127.0.0.1 by default; set `BIND_HOST` only after adding an IP allowlist and authentication, and create the admin account through `/setup` first.
- `make dev` requires a valid `config.yaml` in the project root (run `make setup` first); on Windows use Git Bash, not cmd.exe or PowerShell.

Official quickstart: https://github.com/bytedance/deer-flow#quick-start

## Pros

- MIT-licensed and model-neutral: models are declared in config.yaml, including OpenAI-compatible gateways such as OpenRouter. ([source](https://github.com/bytedance/deer-flow))
- Sub-agent delegation with snapshot context handoff, acceptance criteria checks on output files and durable batch execution. ([source](https://github.com/bytedance/deer-flow#sub-agents))
- Built on LangGraph, with LangGraph-compatible API routes and optional LangGraph Studio. ([source](https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md))
- Can drive Claude Code, Codex and other ACP agents as tools, and the example config leaves ACP permission auto-approval off. ([source](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml))
- Explicit rules for unattended runs: scheduled, webhook and autonomous runs never block on a human and report BLOCKED decisions instead. ([source](https://github.com/bytedance/deer-flow/blob/main/backend/docs/RUN_INTERACTION_POLICY.md))

## Cons

- Version 2.0 is a ground-up rewrite that shares no code with v1; the original Deep Research framework is maintained separately on the 1.x branch. ([source](https://github.com/bytedance/deer-flow/tree/main-1.x))
- The README's security notice warns that it runs high-privilege operations and is designed for a local trusted environment; wider deployment needs IP allowlists and authentication. ([source](https://github.com/bytedance/deer-flow))
- Gateway admin rights are equivalent to code execution on the host, because admins can register stdio MCP servers. ([source](https://github.com/bytedance/deer-flow))
- Heavy footprint: 4 vCPU and 8 GB RAM is the stated starting point for local evaluation. ([source](https://github.com/bytedance/deer-flow#deployment-sizing))
- No pip-installable release is documented; setup is a git clone plus make targets. ([source](https://github.com/bytedance/deer-flow#quick-start))

## Alternatives

- [OpenHands](https://multiagentguide.top/tools/openhands.md) ([DeerFlow vs OpenHands](https://multiagentguide.top/compare/deer-flow-vs-openhands.md))
- [Deep Agents](https://multiagentguide.top/tools/deepagents.md)
- [Hermes Agent](https://multiagentguide.top/tools/hermes-agent.md)
- [OpenClaw](https://multiagentguide.top/tools/openclaw.md)
- [LangGraph](https://multiagentguide.top/tools/langgraph.md)

## FAQ

### Does DeerFlow support MCP?

Yes. It loads stdio and HTTP/SSE MCP servers from extensions_config.json and registers their tools. A2A support is not documented, and AG-UI is mentioned only as an example consumer of streaming callbacks.

### Is DeerFlow free?

Yes. It is MIT-licensed and self-hosted; you pay only for the model provider you configure.

### Is DeerFlow 2.0 the same as the original DeerFlow deep research tool?

No. 2.0 is a ground-up rewrite with no shared code; the 1.x Deep Research framework lives on the main-1.x branch.

### Can I use DeerFlow from Claude Code?

The repository ships a claude-to-deerflow skill that lets Claude Code send tasks to a running DeerFlow instance. Separately, DeerFlow itself can call Claude Code or Codex as ACP agents.

### How is DeerFlow different from OpenHands?

DeerFlow is a LangGraph-based harness where a lead agent delegates to sub-agents for research, reports and code. OpenHands is centred on coding agents managed from Agent Canvas and can run Claude Code, Codex or Gemini CLI through ACP.

## Sources

- [bytedance/deer-flow repository (README)](https://github.com/bytedance/deer-flow)
- [README: Quick start](https://github.com/bytedance/deer-flow#quick-start)
- [README: Deployment sizing](https://github.com/bytedance/deer-flow#deployment-sizing)
- [README: Sandbox mode](https://github.com/bytedance/deer-flow#sandbox-mode)
- [README: Sub-agents](https://github.com/bytedance/deer-flow#sub-agents)
- [README: IM channels](https://github.com/bytedance/deer-flow#im-channels)
- [README: Embedded Python client](https://github.com/bytedance/deer-flow#embedded-python-client)
- [config.example.yaml (ACP agents)](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml)
- [Architecture](https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md)
- [MCP configuration](https://github.com/bytedance/deer-flow/blob/main/backend/docs/MCP_SERVER.md)
- [Run interaction policy](https://github.com/bytedance/deer-flow/blob/main/backend/docs/RUN_INTERACTION_POLICY.md)
- [Streaming design (AG-UI mention)](https://github.com/bytedance/deer-flow/blob/main/backend/docs/STREAMING.md)
- [1.x branch](https://github.com/bytedance/deer-flow/tree/main-1.x)
- [v2.1.0 release](https://github.com/bytedance/deer-flow/releases/tag/v2.1.0)
- [DeerFlow website](https://deerflow.tech)
- [AG-UI README integration list](https://github.com/ag-ui-protocol/ag-ui)

## Unknown fields

protocols.a2a: searched the README, backend/docs and GitHub code search (a2a) in bytedance/deer-flow; only unrelated hash strings matched. protocols.agui: searched the same sources plus the AG-UI README integration list; only a passing mention in backend/docs/STREAMING.md of AG-UI as an example callback consumer, which is not documented support. docs_url points to the repository's architecture doc because the project has no separate documentation site.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/deer-flow