Deer-flow Documentation: Complete Guide to Architecture, Configuration, and Usage

Deer-flow is an open-source super-agent harness that orchestrates sub-agents, long-term memory, and sandboxed execution through a unified FastAPI gateway and LangGraph runtime.

This comprehensive Deer-flow documentation covers the complete stack maintained in the bytedance/deer-flow repository. Whether you are deploying the full containerized platform or embedding the Python client into existing applications, understanding the architecture and configuration system is essential for effective implementation.

High-Level Architecture

Deer-flow implements a modular microservices architecture designed for local development and production Kubernetes deployments. The system unifies a React frontend, reverse proxy, LangGraph runtime, and sandboxed execution environment behind a consistent API gateway.

Component Overview

The request flow follows a structured path through specialized services:

1. Browser (React UI) – Next.js frontend served via the reverse proxy
2. Nginx (Port 2026) – Unified reverse proxy routing /api/* requests and WebSocket connections
3. LangGraph Server (Port 2024) – Core agent runtime executing the lead agent graph defined in src/agents/lead_agent/agent.py
4. FastAPI Gateway (Port 8001) – REST API exposing model management, file uploads, skill registry, and MCP endpoints via backend/src/gateway/app.py
5. Sandbox Provider – Isolated execution environment via local (backend/src/sandbox/local/local_sandbox_provider.py) or Docker-based (backend/src/community/aio_sandbox/aio_sandbox_provider.py) implementations

Key Entry Points

The orchestration logic resides in specific source files that handle distinct responsibilities:

• Agent Logic: backend/src/agents/lead_agent/agent.py constructs the LangGraph middleware chain and sub-agent routing
• Tool Discovery: backend/src/tools/__init__.py exposes get_available_tools() for dynamic tool loading
• Memory Management: backend/src/agents/memory/updater.py persists conversation threads to .deer-flow/threads/
• MCP Integration: backend/src/mcp/manager.py handles dynamic registration of external tool servers via extensions_config.json

Configuration System

Deer-flow uses a single YAML-based configuration file (config.yaml) parsed by backend/src/config/app_config.py to drive model selection, sandbox modes, and skill paths. This centralized approach ensures consistency across the gateway, agent runtime, and sandbox providers.

Core Configuration Sections

The config.yaml structure organizes functionality into logical domains:

Models: Define LLM providers, API keys, and optional "thinking" mode parameters.

models:
  - name: gpt-4
    use: langchain_openai:ChatOpenAI
    api_key: $OPENAI_API_KEY

Tool Groups: Logical categorization for UI organization and permission scoping.

tool_groups:
  - name: web
  - name: file:write

Tools: Individual implementations referencing Python callables that return LangChain Tool instances.

tools:
  - name: web_search
    group: web
    use: src.community.tavily.tools:web_search_tool

Sandbox: Execution environment selection between local development and isolated Docker containers.

# Local development mode

sandbox:
  use: src.sandbox.local:LocalSandboxProvider

# Production Docker mode

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider

Skills: Path mapping for markdown-based skill packages stored in skills/public/ and skills/custom/.

skills:
  path: ./skills
  container_path: /mnt/skills

Environment Variable Substitution

Configuration values prefixed with $ are resolved from the process environment at runtime. This security pattern prevents credential leakage into version control while maintaining operational flexibility.

# config.yaml

models:
  - name: claude-3
    api_key: $ANTHROPIC_API_KEY

The substitution logic handles missing variables gracefully, logging warnings while allowing the application to start with reduced functionality for non-critical configuration items.

Embedded Python Client

Deer-flow exposes functionality through a pure Python client in backend/src/client.py, enabling programmatic interaction without managing server processes. This embedded approach suits automation scripts, Jupyter notebooks, and integration into existing Python applications.

Basic Usage

Initialize the client and execute synchronous chat operations against the configured agent runtime.

from src.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat("Summarize the latest AI research trends.")
print(response)

The DeerFlowClient class automatically discovers the local configuration and manages thread state persistence under .deer-flow/threads/.

Streaming Interactions

For real-time feedback during long-running agent tasks, use the streaming interface to process events as they occur.

from src.client import DeerFlowClient

client = DeerFlowClient()
for event in client.stream("Create a 3-slide deck about quantum computing."):
    if event.type == "messages-tuple" and event.data["type"] == "ai":
        print(event.data["content"])
    elif event.type == "values":
        print("Artifacts:", event.data["artifacts"])

The event stream exposes internal LangGraph state transitions, including message tuples, tool invocations, and artifact generation.

File and Skill Management

The client provides methods for uploading documents and managing the skill registry programmatically.

# Upload a PDF (auto-converted to Markdown)

upload_result = client.upload_files(
    thread_id="demo", 
    files=["./paper.pdf"]
)
print(upload_result)

# List available skills

print(client.list_skills())

# Enable a specific skill

client.update_skill("web-search", enabled=True)

File uploads trigger automatic format conversion pipelines, while skill updates modify the active tool set available to the agent runtime.

Key Files and Entry Points

Understanding the repository structure accelerates debugging and extension efforts. These critical paths define the system's behavior:

Path	Role
backend/src/gateway/app.py	FastAPI entry point exposing /api/* endpoints
backend/src/agents/lead_agent/agent.py	LangGraph agent construction and middleware chain
backend/src/tools/__init__.py	Tool discovery via get_available_tools()
backend/src/sandbox/local/local_sandbox_provider.py	Local development sandbox implementation
backend/src/community/aio_sandbox/aio_sandbox_provider.py	Docker-based production sandbox
backend/src/mcp/manager.py	MCP server registration and lifecycle management
backend/src/client.py	Embedded Python client library
frontend/README.md	Frontend build and development instructions
backend/docs/ARCHITECTURE.md	Visual system architecture documentation
backend/docs/CONFIGURATION.md	Complete configuration reference
docker/docker-compose-dev.yaml	Development orchestration file

Quick Start Guide

Deploy Deer-flow locally using Docker or native Python tooling:

1. Clone and install

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

2. Generate configuration

   make config

   This creates config.yaml from config.example.yaml.

3. Configure secrets Add API keys to .env (never commit this file):

   OPENAI_API_KEY=sk-...
   ANTHROPIC_API_KEY=sk-...

4. Launch services

   • Docker (recommended): make docker-start → Access UI at http://localhost:2026
   • Local development: make dev (requires Python 3.11+, uv, pnpm)

5. Interact Use the web UI, the embedded Python client (backend/src/client.py), or direct HTTP API calls to /api/*.

Extending Deer-flow

The modular architecture supports three primary extension mechanisms:

Custom Skills

Create markdown-based skill packages in skills/custom/. Each skill requires a SKILL.md file describing capabilities and implementation details. The loader at backend/src/skills/loader.py automatically discovers and registers these skills at runtime.

MCP Tools

Register external tool servers via extensions_config.json. The MCP manager (backend/src/mcp/manager.py) handles dynamic loading and lifecycle management of these extensions, enabling integration with GitHub, databases, and other external services.

New Tool Development

Implement new tools by creating Python callables that return LangChain Tool instances. Reference these in the tools: section of config.yaml using the module path format src.module.path:function_name.

Summary

• Deer-flow is a comprehensive super-agent harness combining LangGraph runtime, FastAPI gateway, and sandboxed execution.
• Configuration is centralized in config.yaml with environment variable substitution for secure secret management.
• Architecture spans ports 2026 (Nginx), 2024 (LangGraph), and 8001 (Gateway), with components defined in backend/src/agents/lead_agent/agent.py and backend/src/gateway/app.py.
• Embedded client at backend/src/client.py enables Python-native integration without server processes.
• Extension points include markdown skills in skills/custom/, MCP servers via extensions_config.json, and custom tools in config.yaml.

Frequently Asked Questions

What is Deer-flow and how does it differ from other agent frameworks?

Deer-flow is an open-source super-agent harness that orchestrates sub-agents, long-term memory, and sandboxed execution through a unified architecture. Unlike simpler agent libraries, Deer-flow provides a complete production stack including a React frontend, Nginx reverse proxy, LangGraph runtime, and configurable sandbox providers (local or Docker) within a single repository.

How do I configure the sandbox mode in Deer-flow?

Sandbox configuration is controlled via the sandbox section in config.yaml. For local development, set use: src.sandbox.local:LocalSandboxProvider. For production isolation, use use: src.community.aio_sandbox:AioSandboxProvider to enable Docker-based execution. The sandbox provider handles safe execution of tool code without exposing the host system.

Can I use Deer-flow as a Python library without running the full server?

Yes. Deer-flow provides an embedded Python client in backend/src/client.py that allows direct programmatic interaction without managing server processes. Import DeerFlowClient to execute chat operations, stream events, upload files, and manage skills purely within Python scripts or Jupyter notebooks.

Where are conversation threads and memory stored in Deer-flow?

Persistent per-user memory and conversation threads are stored under .deer-flow/threads/ in the project directory. The memory updater at backend/src/agents/memory/updater.py manages this storage, ensuring conversation context persists across sessions while maintaining isolation between different user threads.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}