DeerFlow

Source: https://github.com/bytedance/deer-flow

Overview

DeerFlow 2.0 is ByteDance's open-source super agent harness. The repo describes it as a system for researching, coding, and creating, with support for sandboxes, memory, tools, skills, and sub-agents. The page makes a clear point that v2 is a full rewrite, separate from the old 1.x line.

What changed in 2.0

The landing page says DeerFlow 2.0 is a ground-up rewrite and shares no code with v1. If you want the original Deep Research framework, that still exists on the 1.x branch. Active development is now on 2.0.

Core architecture

DeerFlow is designed as a harness, not just a chat interface. The important pieces are:

a lead agent that can plan and coordinate work
sub-agents for parallel or scoped tasks
long-term memory
a sandboxed filesystem and execution environment
a skills system for reusable workflows
core tools for search, fetch, file operations, and bash
MCP support for custom tool integrations
channel integrations for chat-based task submission

Configuration steps

The repo's quick start is roughly:

Clone the repository

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

Generate local configuration files

make config

This creates local config files from the example templates.

Configure at least one model in config.yaml The page shows model entries like these:

models:
  - name: gpt-4
    display_name: GPT-4
    use: langchain_openai:ChatOpenAI
    model: gpt-4
    api_key: $OPENAI_API_KEY
    max_tokens: 4096
    temperature: 0.7

It also shows examples for OpenRouter, Responses API mode, and CLI-backed providers such as Codex CLI and Claude Code OAuth.

Set environment variables The page suggests using .env or shell exports. Common examples shown on the page include:

OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key
INFOQUEST_API_KEY=your-infoquest-api-key

For OpenRouter-style setups, the repo notes that langchain_openai:ChatOpenAI plus base_url is the intended pattern.

Configure sandbox mode The docs mention multiple sandbox execution modes:

local execution on the host
Docker execution
Docker plus Kubernetes via provisioner

Start the application For Docker-based development:

make docker-init
make docker-start

For local development:

make check
make install
make dev

The page says the app is then accessible at http://localhost:2026.

Configuration details shown on the page

Model examples

The page gives several patterns:

standard OpenAI-compatible configuration with langchain_openai:ChatOpenAI
OpenRouter via base_url: https://openrouter.ai/api/v1
OpenAI Responses API using use_responses_api: true and output_version: responses/v1
Codex CLI provider using deerflow.models.openai_codex_provider:CodexChatModel
Claude Code provider using deerflow.models.claude_provider:ClaudeChatModel

CLI-backed providers

The page is explicit that Codex CLI reads ~/.codex/auth.json. For Claude Code, it mentions auth via environment variables or credentials files, and notes that on macOS DeerFlow does not probe Keychain automatically. If needed, you export the Claude Code OAuth credentials explicitly.

Channel config

The docs show a channels: block with these pieces:

langgraph_url
gateway_url
optional global session defaults
per-channel settings for Feishu, Slack, Telegram
allowed users and per-user session overrides

Example structure from the page:

channels:
  langgraph_url: http://localhost:2024
  gateway_url: http://localhost:8001
  session:
    assistant_id: lead_agent
    config:
      recursion_limit: 100
    context:
      thinking_enabled: true
      is_plan_mode: false
      subagent_enabled: false

Messaging channel setup

Create a bot with BotFather
Put the token in TELEGRAM_BOT_TOKEN
Enable the Telegram channel in config

Slack

The page says to:

create a Slack app
add bot scopes like app_mentions:read, chat:write, im:history, im:read, im:write, files:write
enable Socket Mode
create an App-Level Token with connections:write
subscribe to events like app_mention and message.im

Feishu / Lark

The page says to:

create a Feishu app
enable Bot capability
add permissions including im:message, im:message.p2p_msg:readonly, im:resource
subscribe to im.message.receive_v1
use Long Connection mode
set FEISHU_APP_ID and FEISHU_APP_SECRET

Commands exposed in chat

The repo lists several built-in commands:

/new to start a new conversation
/status to show thread info
/models to list models
/memory to view memory
/help to show help

Skills and tools

The page explains that skills are loaded progressively, only when needed. It also says DeerFlow comes with core tools such as web search, web fetch, file ops, and bash execution, while custom tools can be added via MCP and Python functions.

Sub-agents

The repo emphasizes that complex jobs should be decomposed. The lead agent can spawn sub-agents, each with its own scoped context and stop conditions. The page says sub-agents can run in parallel when possible and report structured results back.

Sandboxed file system

The docs describe an isolated Docker container with a filesystem for uploads, workspace, and outputs. The point is to keep the work auditable and separated from the host.

Memory and context engineering

DeerFlow keeps persistent memory across sessions, and the page says memory updates skip duplicate facts when applied. It also summarizes completed subtasks to keep context lean during long tasks.

Python client

The page shows an embedded Python client:

from deerflow.client import DeerFlowClient
client = DeerFlowClient()
response = client.chat("Analyze this paper for me", thread_id="my-thread")

It also supports streaming, listing models, listing skills, updating skills, and uploading files.

Practical notes

This repo is closer to an agent runtime platform than a normal chatbot wrapper. If you already have a project that needs long-running research, task decomposition, file work, and persistent memory, DeerFlow is aimed squarely at that problem.

Repo stats shown on the page

Stars: 38.7k
Forks: 4.6k
Watching: 185