DeerFlow

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.

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.

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

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

• 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.

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.

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

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.

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.

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.