Self-hosting DeerFlow 2.0: a complete setup guide

Self-hosting DeerFlow 2.0: a complete setup guide

DeerFlow 2.0, released by ByteDance on March 25, 2026, hit #1 on GitHub Trending within 48 hours. It gives your AI agent an actual computer to work in: an isolated Docker sandbox with a shell, a browser, a persistent filesystem, and the ability to spawn sub-agents for long-horizon tasks. If you've been watching n8n and OpenClaw and wondering what comes next, this is the tool worth your weekend.

This guide covers the full self-hosted setup — Docker deployment, model provider configuration, and the architectural decisions that will save you hours of debugging. No managed cloud account required.

---

What DeerFlow 2.0 actually does

Most "AI agent" tools are wrappers around a single LLM with tool access. DeerFlow operates as a SuperAgent harness: a coordinator that plans tasks, spawns sub-agents to handle discrete parts, and executes everything inside a sandboxed environment rather than on your host machine.

The sandbox is the key distinction. Each agent session gets its own Docker container with a full filesystem, a bash terminal, and a browser. When DeerFlow runs a coding task, the code executes inside that container — not on your server. That isolation matters if you're running untrusted tasks, processing user-submitted data, or just want clean rollback behavior.

DeerFlow is built on LangGraph and LangChain. It ships with a planning layer, a memory system for multi-session context, a skill registry for reusable capabilities, and a message gateway for coordinating between sub-agents. The web interface runs on port 2026 locally — but under the hood, each message kicks off an agent workflow, not a single LLM call.

The architecture in three layers

The repo gained approximately 12,000 stars in the 48 hours following the March 25 release. (byteiota.com)

---

Hardware and prerequisites

DeerFlow is not a lightweight tool. The sandbox spins up Docker containers per session, and if you're running models locally via Ollama, you need enough VRAM to keep the planner model loaded while sub-agents execute.

Minimum tested setup:

• 16 GB RAM (24 GB recommended for local models)

• Docker and Docker Compose

• Python 3.12+, Node.js 22+

• Tavily API key (free tier covers personal use)

• At least one LLM API key: OpenAI, Anthropic, DeepSeek, or a local Ollama endpoint

Running a 14B planner and a 7B sub-agent model puts peak usage around 20 GB. For cloud API users, DeepSeek V3 at $0.0014 per 1,000 input tokens is approximately 50× cheaper than GPT-4o — with no meaningful quality gap on factual research tasks.

---

Self-hosted DeerFlow 2.0 setup with Docker

Clone and configure

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

make config generates config.yaml and .env. Minimal config.yaml:

llm:
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}

tools:
  search:
    provider: tavily
    api_key: ${TAVILY_API_KEY}

sandbox:
  enabled: true
  image: ghcr.io/bytedance/deer-flow-sandbox:latest

Set credentials in .env:

OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...

Choose your model provider

Initialize and launch

make docker-init   # pulls sandbox images (~2–5 min first run)
make docker-start  # starts all services

Open http://localhost:2026. The task decomposition sidebar — showing which sub-agent handles which slice in real time — is the best diagnostic tool in the UI.

To stop: make docker-stop. Logs: make docker-logs.

---

DeerFlow 2.0 vs. alternatives: where it fits

The self-hosted agent space has three archetypes:

1. Visual workflow builders (n8n, Dify) — repeatable processes, low technical floor

2. Local LLM runners (Ollama + Open WebUI) — chat and simple tool use, minimum infra

3. SuperAgent harnesses (DeerFlow) — complex, long-horizon tasks that need real execution

DeerFlow is overkill for "summarize this document." It is exactly right for "research this topic, write the code to analyze it, run the analysis, and produce a report."

Versus AutoGen or CrewAI: both require custom Python code per workflow. DeerFlow ships as a complete system with UI, sandbox, and pre-built skills — you trade flexibility for speed to first result. For most engineers, that's the right trade. (VentureBeat)

---

Real trade-offs to know before you commit

Sandbox startup latency. Cold start adds 8–15 seconds before the first agent action. Container pool management doesn't exist yet in the current release — it's an active community gap.

Memory persistence is per-session by default. Cross-session continuity requires a Redis or SQLite-backed memory backend. It's documented but not enabled by default.

API key sprawl. At minimum you need an LLM key and a Tavily key; with MCP integrations, you're managing 5–6 keys in a .env file. Use a proper secrets manager (Vault, Doppler) from day one for anything beyond a single machine.

These are solvable. They're not reasons to avoid the tool — they're reasons to plan for them.

---

What to run first

The best first task is one where you already know the expected output. Try this: give it a GitHub repo URL and ask it to summarize the codebase, identify the three most complex functions, and write a unit test for one of them. You'll see the browser tool, the code sandbox, and the sub-agent spawner all activate — and you can evaluate the output against your own knowledge of the repo.

Once you've confirmed function, the research-to-report workflow is where DeerFlow earns its keep. A prompt like "Research the three best open-source alternatives to Datadog for Kubernetes monitoring, compare resource overhead, and write a markdown comparison table" takes 4–6 minutes and produces output that would take an engineer 45–60 minutes manually.

---

Getting it into your regular workflow

DeerFlow 2.0 is worth the setup if you do research-heavy engineering work — tool evaluations, technical comparisons, codebase documentation, analysis pipelines. The self-hosted version gives you data privacy that cloud agents can't match, and the sandbox model keeps agent failures contained.

If you've already set up the Ollama + Open WebUI stack, DeerFlow sits naturally on top of it: point config.yaml at your Ollama endpoint and keep the same models. Same hardware, significantly more capable task orchestration.

Try it this week, while the community is active and the documentation is fresh.

---

Sources

• DeerFlow GitHub Repository