📑 Table of Contents

  1. What it is

  2. Why it exists

  3. What it can actually do

  4. Before you start

  5. Installation by OS

  6. Setup step by step

  7. Prompts to use it

  8. Commands table

  9. Daily workflow

  10. Tips

  11. Troubleshooting

  12. Quick reference

🦌 1. What It Is

DeerFlow stands for Deep Exploration and Efficient Research Flow. Version 2.0 is a ground up rewrite that shares no code with v1. The old Deep Research framework still lives on the main-1.x branch, but all active development moved to 2.0.

It is described by its authors as a super agent harness: a runtime that gives an agent a filesystem, memory, skills, sandbox aware execution, and the ability to plan and spawn sub agents for multi step tasks.

Built by ByteDance. Core authors credited in the repo are Daniel Walnut and Henry Li. Licensed MIT. On February 28th, 2026 it claimed the number 1 spot on GitHub Trending after the v2 launch.

🤔 2. Why It Exists

DeerFlow started life as a Deep Research framework. Then the community took it somewhere the team never planned.

People stopped using it just for research. They built data pipelines with it. They generated slide decks. They spun up dashboards. They automated whole content workflows. The pattern was loud and clear: this was never just a research tool. It was a harness, a runtime that hands agents the infrastructure to actually finish work instead of just talking about it.

So the team threw out v1 and rebuilt from zero. The result is batteries included and fully extensible. You can run it as is, or tear it apart and make it yours.

⚡ 3. What It Can Actually Do

You say

What happens

"Research this topic and write me a report"

Lead agent fans the task out to sub agents, each explores an angle in its own isolated context, then converges into one report

"Turn this into a slide deck"

The slide creation skill loads on demand and produces a deck, optionally with generated visuals

"Build me a dashboard from this data"

Agent uses its filesystem and sandbox to write, run, and edit code, then drops deliverables in the outputs folder

"Generate an image for this section"

The image generation skill loads progressively and produces the asset

"Run this shell command"

With AioSandboxProvider, execution runs inside an isolated container, not on your host

"Remember my writing style and stack"

Long term memory persists your profile and preferences across sessions, stored locally under your control

"Send DeerFlow a task from Telegram"

IM channels route the message through the Gateway and reply in chat, no public IP required

✅ 4. Before You Start

Checklist of what you need installed and ready:

  • Python 3.12 or newer

  • Node.js 22 or newer

  • pnpm (frontend package manager)

  • uv (Python package manager)

  • nginx (used by the unified endpoint)

  • git

  • Docker (recommended path, optional for pure local dev)

  • At least one LLM provider API key (OpenAI, OpenRouter, or a CLI backed provider like Codex CLI or Claude Code OAuth)

  • Optional: a web search provider key such as Tavily

❝

⚠️ Security: DeerFlow can execute system commands and read and write files. It is designed by default to run in a local trusted environment, bound to the 127.0.0.1 loopback interface only. Do not expose it to a LAN, public cloud, or multi endpoint network without an IP allowlist, an authentication gateway, and network isolation.

💻 5. Installation by OS

The flow is the same across systems. The shell you run it from is what differs.

🍎 macOS

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

If you use Claude Code OAuth as a provider, export the auth explicitly when needed:

eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"

🪟 Windows

Run the local development flow from Git Bash. Native cmd.exe and PowerShell are not supported for the bash based service scripts, and WSL is not guaranteed because some scripts rely on Git for Windows utilities such as cygpath.

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

🐧 Linux

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

⚠️ Linux Docker permission: if Docker commands fail with permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, add your user to the docker group and re login before retrying.

Linux plus Docker is the recommended target for a persistent server. macOS and Windows are best treated as development or evaluation environments.

🛠️ 6. Setup Step by Step

One action per step.

  1. Clone the repo and enter the folder.

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

  1. Run the setup wizard from the project root. It takes about 2 minutes.

make setup

  1. In the wizard, choose your LLM provider, optionally add a web search provider, and set execution and safety preferences such as sandbox mode, bash access, and file write tools. It writes a minimal config.yaml and saves your keys to .env.

  2. Verify the setup and get fix hints at any time.

make doctor

  1. Pick how you want to run it.

Docker development path (hot reload, source mounts):

make docker-init    # pull sandbox image, only once or when it updates
make docker-start   # start services, auto detects sandbox mode from config.yaml

Or the local development path. First check prerequisites and install:

make check     # verifies Node.js 22+, pnpm, uv, nginx
make install   # backend + frontend deps + pre commit hooks
make dev       # start services

  1. Open the app.

http://localhost:2026

For a production deployment with locally built images:

make up     # build images and start all production services
make down   # stop and remove containers
❝

The advanced manual route is make config instead of make setup, which copies the full template. See config.example.yaml for the complete reference.

💬 7. Prompts to Use It

Copy paste ready, grouped by use case.

Hand off setup to a coding agent

Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md

Research and reporting

Research the current state of open source AI agent frameworks, compare the top five on architecture, memory, and sandboxing, and write me a structured report with sources.

Build a deliverable

Take the report you just wrote and turn it into a clean slide deck. Generate a cover visual for it.

Multi step decomposition with sub agents

Plan this task, then spawn sub agents to handle each part in parallel: gather the data, analyze it, build a dashboard, and write a summary. Synthesize everything into one output.

⌨️ 8. Commands Table

Make commands

Command

What it does

make setup

Launch the interactive setup wizard, write config.yaml and .env

make config

Copy the full config template for manual editing

make doctor

Verify setup and print actionable fix hints

make check

Verify Node.js 22+, pnpm, uv, nginx

make install

Install backend and frontend deps plus pre commit hooks

make dev

Start services in local development mode with hot reload

make docker-init

Pull the sandbox image (run once or when it updates)

make docker-start

Start Docker development services

make up

Build images and start production services

make down

Stop and remove production containers

make setup-sandbox

Pre pull the sandbox image

make detect-blocking-io

Statically scan backend code for blocking IO on the event loop

In chat IM channel commands

Command

What it does

/new

Start a new conversation

/status

Show current thread info

/models

List available models

/memory

View memory

/help

Show help

🔁 9. Daily Workflow

How a real person actually uses this day to day.

You start your machine and bring DeerFlow up with make dev (or make docker-start if you run the Docker path). You open http://localhost:2026.

You drop a task into chat. For something small you let the lead agent handle it directly. For something heavy, a research deep dive or a build, you let it plan and spawn sub agents, each one working a slice in its own isolated context. While it churns, intermediate results get offloaded to the filesystem so the context window stays lean.

Your deliverables land in the outputs folder. Files you feed it go in uploads. The agent's scratch space is the workspace folder.

Over time memory does its job: it learns your stack, your writing style, your recurring workflows, so you repeat yourself less. If you would rather not sit at the browser, you wire up a channel like Telegram or Slack and fire tasks at it from your phone.

text

/mnt/user-data/
├── uploads/     ← your files
├── workspace/   ← agent working directory
└── outputs/     ← final deliverables

💡 10. Tips

  • Skills load progressively, only when a task needs them. That is what keeps DeerFlow usable even on token sensitive models. You do not pay context for capabilities you are not using.

  • The execution mode you pick changes behavior a lot. Through the Claude Code integration the modes are flash (fast), standard, pro (planning), and ultra (sub agents). Match the mode to the task weight instead of always running heavy.

  • Backend picks up config.yaml changes on the next config access during development, so model metadata edits do not need a manual restart.

  • Run make doctor before you start hunting a bug. It catches missing prerequisites and bad config fast.

  • For OpenRouter and other OpenAI compatible gateways, configure with langchain_openai:ChatOpenAI plus a base_url, and point api_key at your env variable, for example $OPENROUTER_API_KEY.

  • If CPU or memory stays pinned, drop the number of concurrent runs first before you jump to a bigger machine tier.

🚀 11. Quick Reference

# Clone and configure
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup
make doctor

# Docker development path
make docker-init
make docker-start

# Local development path
make check
make install
make dev

# Production
make up
make down

# Access
# http://localhost:2026

# Claude Code integration skill
npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

By The AI Leverage - Learn and master AI daily

Keep Reading