DeerFlow: Open-Source Super Agent Harness
/deer-flow
DeerFlow is an open-source super agent harness from ByteDance that orchestrates sub-agents, memory, and sandboxes for long-horizon AI tasks lasting minutes to hours. Reach for it if you want a self-hosted stack with LangGraph checkpointing and a real production path through Postgres and Redis. Skip it if you just need a single-agent chatbot — the sandbox modes and worker-coordination internals are overkill for that.
An Open-Source Super Agent Harness
DeerFlow (Deep Exploration and Efficient Research Flow) is an open-source super agent harness built by ByteDance that coordinates sub-agents, memory, and sandboxes to research, code, and create. Version 2.0 is a ground-up rewrite that shares no code with the original v1 Deep Research framework, now maintained on the 1.x branch. It runs as a Gateway API plus a web frontend with LangGraph-backed checkpointing built in.
Core Capabilities and Integrations
- ✓A Gateway API that keeps run state in-process and exposes LangGraph-compatible endpoints under `/api/langgraph/*`, translated to DeerFlow's native `/api/*` routes behind nginx.
- ✓Provider flexibility in one `config.yaml`: OpenAI-style models via `langchain_openai:ChatOpenAI`, OpenRouter and other OpenAI-compatible gateways through `base_url`, vLLM 0.19.0 via `deerflow.models.vllm_provider:VllmChatModel`, and CLI-backed auth for Codex CLI and Claude Code.
- ✓Sandboxed execution with bash access and file-write tools toggled during setup, including a provisioner mode for shared AIO sandbox backends.
- ✓LangGraph checkpointing on SQLite or Postgres, plus an optional delta-mode checkpoint cache (in-memory or Redis) for materialized histories.
- ✓A documented multi-worker path for production: Redis stream bridge, heartbeat-based run-ownership leases, and SSE replay that emits a `gap` event instead of silently skipping missed messages.
- ✓InfoQuest, a BytePlus-built search and crawling toolset, integrated for web research on top of the optional web search provider you configure separately.
- ✓A skills system rooted in a plain `skills/` directory (movable via `DEER_FLOW_SKILLS_PATH`), which is how sub-agents pick up new capabilities without code changes to the harness itself.
- ✓LLM Space, a separate desktop app for prototyping agent ideas, stepping through each harness run, replaying failures, and benchmarking performance.
Getting Started with DeerFlow
Clone the repo with `git clone https://github.com/bytedance/deer-flow.git && cd deer-flow`, then run `make setup`. That launches an interactive wizard — pick an LLM provider, decide whether to configure a web search provider, and set sandbox mode, bash access, and file-write permissions — and it writes a minimal `config.yaml` plus your keys to `.env` in about two minutes. Run `make doctor` any time to check the setup and get fix hints. If you want the full config surface instead of the wizard's minimal file, run `make config` to copy the complete template, which documents CLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, the OpenAI Responses API, and subagent runtime caps like `subagents.max_total_per_run`. For Docker, `make docker-init` pulls the sandbox image once, then `make docker-start` brings up the stack with hot-reload; `make docker-logs` tails it. For local (non-Docker) development, run `make check` first to confirm Node.js 22+, pnpm, uv, and nginx are present, then `make install` for backend/frontend dependencies and pre-commit hooks, then `make dev`. On Windows, run the local flow from Git Bash — native cmd.exe and PowerShell aren't supported for the bash-based service scripts, and WSL isn't guaranteed to work.
Running DeerFlow: Deployment Options
For development, Docker is the path the README recommends: `make docker-init` once, then `make docker-start` for a hot-reloading stack, or run `./scripts/serve.sh --dev` / `make dev` locally after the install steps above. The README's sizing guidance: local evaluation wants at least 4 vCPU / 8 GB RAM / 20 GB free SSD (8 vCPU / 16 GB RAM recommended); Docker development wants at least 4 vCPU / 8 GB RAM / 25 GB free SSD (8 vCPU / 16 GB RAM recommended). For production, `make up` builds images locally and starts all services, reachable at http://localhost:2026; `make down` stops and removes containers. A long-running server should start at 8 vCPU / 16 GB RAM / 40 GB free SSD and scale to 16 vCPU / 32 GB RAM for shared or multi-agent use. Persistent deployments need `database.backend` set to `sqlite` or `postgres`, shared by the LangGraph checkpointer, LangGraph Store, and DeerFlow's own data. Production defaults to a single Gateway worker (`GATEWAY_WORKERS=1`); running more than one requires Postgres, a Redis stream bridge (`stream_bridge.type: redis`), `run_ownership.heartbeat_enabled: true`, and `run_events.backend: db`.
Strengths
- ✓The `make setup` wizard covers LLM provider, web search, and sandbox/bash/file-write permissions in about two minutes, and `make doctor` gives specific fix hints instead of a bare failure.
- ✓Config edits to `config.yaml` apply on next access without a restart — only two checkpoint-storage settings are frozen per-process by design.
- ✓Multi-worker production is a real, documented setup (Redis stream bridge, lease heartbeats, SSE gap events with replay) rather than an unsupported edge case.
- ✓Provider support spans hosted APIs, OpenRouter, self-hosted vLLM, and CLI-backed auth for Codex CLI and Claude Code, all from one config file.
- ✓MIT license, so there's no copyleft obligation if you fold DeerFlow into a commercial product.
Deployment Considerations and Advanced Requirements
- △Only one Gateway worker runs by default in production (`GATEWAY_WORKERS=1`); scaling past that means adding Postgres, a Redis stream bridge, and heartbeat-based lease ownership, not just adding replicas.
- △The recommended long-running server sizing starts at 8 vCPU / 16 GB RAM / 40 GB free SSD and climbs to 16 vCPU / 32 GB RAM for shared use — not something you casually run on a small VPS.
- △macOS and Windows are positioned as development/evaluation environments only; Linux plus Docker is the recommended target for a persistent server.
- △Windows local development needs Git Bash specifically — native cmd.exe/PowerShell aren't supported for the service scripts, and WSL support isn't guaranteed.
- △Version 2.0 shares no code with v1, so anything built against the original Deep Research framework doesn't carry forward — that codebase is now frozen on the 1.x branch.
Comparing Agent Frameworks
Frequently Asked Questions
DeerFlow is released under the MIT license, so you can use, modify, and redistribute it, including in commercial projects, without copyleft restrictions.
DeerFlow supports OpenAI-style models through `langchain_openai:ChatOpenAI`, OpenRouter and other OpenAI-compatible gateways, vLLM 0.19.0 deployments, and CLI-backed providers such as Codex CLI and Claude Code OAuth, all defined in `config.yaml`.
DeerFlow supports local development through `make dev`, which runs the Gateway and frontend with hot-reload after `make check` and `make install`; the app is reachable at http://localhost:2026.
For local evaluation, DeerFlow's README recommends 8 vCPU and 16 GB RAM (minimum 4 vCPU/8 GB, 20 GB free SSD); a long-running server target is 16 vCPU and 32 GB RAM (starting point 8 vCPU/16 GB, 40 GB free SSD).
Multi-worker DeerFlow deployments are supported but require Postgres, a Redis stream bridge, heartbeat-enabled run ownership, and a database-backed run-events store — the default single-worker mode (`GATEWAY_WORKERS=1`) can't be scaled by just adding replicas.
DeerFlow integrates InfoQuest, an intelligent search and crawling toolset built by BytePlus, and also lets you configure a separate optional web search provider during the `make setup` wizard.
The problem it solves
Long-horizon agent tasks — the kind that research a topic, write code, and produce an output over minutes to hours rather than a single request/response — need more than a chat loop: sandboxed execution so generated code can't touch the host, memory that persists across steps, and a clean way to recover when a worker dies mid-run. DeerFlow packages those pieces (sub-agents, sandboxes, memory, a message gateway) into one harness instead of leaving you to wire a checkpoint store, a sandbox provider, and a run-ownership/lease system together yourself.
Best use cases
- •Long-horizon research agents that need to survive minutes-to-hours-long runs without losing state if a worker restarts.
- •Coding agents that need actual sandboxed bash and file-write access, not just chat-based suggestions.
- •Teams already using LangGraph/LangChain who want sandboxing, memory, and multi-agent orchestration bundled instead of wired together from separate libraries.
- •Agent workflows built around InfoQuest-style web search and crawling rather than a single hosted search API.
- •Prototyping harness steps locally in LLM Space before shipping changes to a production Gateway deployment.
Who should try it — and who should skip
Try DeerFlow if you're building a long-horizon agent product that plans, codes, and researches over runs lasting minutes to hours, and you're fine operating a Gateway API, sandbox containers, and a checkpoint database yourself. It suits teams already on LangGraph/LangChain who want the sandbox, memory, and orchestration pieces bundled rather than hand-wired. Skip it if you want a hosted, zero-ops agent product, or your workload is a single short LLM call that doesn't need sub-agents, sandboxing, or persistent memory — the setup wizard and sizing requirements won't pay for themselves there.
Related repositories
Curious whether deer-flow is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about deer-flow.