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

> Explore the Deer-flow documentation. Learn to orchestrate sub-agents, memory, and execution with this open-source super-agent harness. Master its architecture, configuration, and usage for powerful AI applications.

- Repository: [Bytedance Inc./deer-flow](https://github.com/bytedance/deer-flow)
- Tags: documentation
- Published: 2026-03-08

---

**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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/app.py)
5. **Sandbox Provider** – Isolated execution environment via local ([`backend/src/sandbox/local/local_sandbox_provider.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/sandbox/local/local_sandbox_provider.py)) or Docker-based ([`backend/src/community/aio_sandbox/aio_sandbox_provider.py`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/agents/lead_agent/agent.py) constructs the LangGraph middleware chain and sub-agent routing
- **Tool Discovery**: [`backend/src/tools/__init__.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/tools/__init__.py) exposes `get_available_tools()` for dynamic tool loading
- **Memory Management**: [`backend/src/agents/memory/updater.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/agents/memory/updater.py) persists conversation threads to `.deer-flow/threads/`
- **MCP Integration**: [`backend/src/mcp/manager.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/mcp/manager.py) handles dynamic registration of external tool servers via [`extensions_config.json`](https://github.com/bytedance/deer-flow/blob/main/extensions_config.json)

## Configuration System

Deer-flow uses a single YAML-based configuration file ([`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml)) parsed by [`backend/src/config/app_config.py`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) structure organizes functionality into logical domains:

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

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

```

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

```yaml
tool_groups:
  - name: web
  - name: file:write

```

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

```yaml
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.

```yaml

# 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/`.

```yaml
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.

```yaml

# 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`](https://github.com/bytedance/deer-flow/blob/main/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.

```python
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.

```python
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.

```python

# 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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/app.py) | FastAPI entry point exposing `/api/*` endpoints |
| [`backend/src/agents/lead_agent/agent.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/agents/lead_agent/agent.py) | LangGraph agent construction and middleware chain |
| [`backend/src/tools/__init__.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/tools/__init__.py) | Tool discovery via `get_available_tools()` |
| [`backend/src/sandbox/local/local_sandbox_provider.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/sandbox/local/local_sandbox_provider.py) | Local development sandbox implementation |
| [`backend/src/community/aio_sandbox/aio_sandbox_provider.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/community/aio_sandbox/aio_sandbox_provider.py) | Docker-based production sandbox |
| [`backend/src/mcp/manager.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/mcp/manager.py) | MCP server registration and lifecycle management |
| [`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py) | Embedded Python client library |
| [`frontend/README.md`](https://github.com/bytedance/deer-flow/blob/main/frontend/README.md) | Frontend build and development instructions |
| [`backend/docs/ARCHITECTURE.md`](https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md) | Visual system architecture documentation |
| [`backend/docs/CONFIGURATION.md`](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md) | Complete configuration reference |
| [`docker/docker-compose-dev.yaml`](https://github.com/bytedance/deer-flow/blob/main/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**
   ```bash
   git clone https://github.com/bytedance/deer-flow.git
   cd deer-flow
   make install
   ```

2. **Generate configuration**
   ```bash
   make config
   ```

   This creates [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) from [`config.example.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml).

3. **Configure secrets**
   Add API keys to `.env` (never commit this file):
   ```bash
   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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/SKILL.md) file describing capabilities and implementation details. The loader at [`backend/src/skills/loader.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/skills/loader.py) automatically discovers and registers these skills at runtime.

### MCP Tools

Register external tool servers via [`extensions_config.json`](https://github.com/bytedance/deer-flow/blob/main/extensions_config.json). The MCP manager ([`backend/src/mcp/manager.py`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/agents/lead_agent/agent.py) and [`backend/src/gateway/app.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/app.py).
- **Embedded client** at [`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/extensions_config.json), and custom tools in [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/agents/memory/updater.py) manages this storage, ensuring conversation context persists across sessions while maintaining isolation between different user threads.