How to Build DeerFlow From Source: Complete Installation Guide

To build DeerFlow from source, clone the bytedance/deer-flow repository, run make config to generate configuration files, make install to install Python and Node dependencies via uv and pnpm, and make dev to start the local development stack.

DeerFlow is a super-agent harness built on LangGraph and LangChain that requires both Python and Node.js environments to run. Building the application from source involves compiling a multi-service architecture consisting of a LangGraph server, FastAPI gateway, Next.js frontend, and Nginx reverse proxy. This guide walks through the complete build process using the automation provided in the Makefile.

Prerequisites

Before you build DeerFlow from source, ensure your system meets these requirements:

• Python 3.12+ and uv (modern Python package manager)
• Node.js 22+ and pnpm (package manager for the frontend)
• Git and Make
• Docker (optional but recommended for sandbox isolation)

The backend uses uv for deterministic Python dependency resolution, while the frontend relies on pnpm for Node.js package management.

Clone and Configure

Start by cloning the repository and generating the required configuration files.

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

Run the configuration generator to create local config files from templates:

make config

This command copies config.example.yaml to config.yaml and .env.example to .env in the project root. You must edit these files to add your LLM API keys and tool credentials. DeerFlow reads config.yaml (or the file specified by the DEER_FLOW_CONFIG_PATH environment variable) to define model providers, sandbox settings, tool groups, and memory configuration.

Install Dependencies

The Makefile orchestrates installation across both backend and frontend environments.

Run the unified install command:

make install

This executes:

1. Backend installation: cd backend && uv sync to install Python dependencies using the uv lockfile
2. Frontend installation: cd frontend && pnpm install to fetch Next.js and React dependencies

The backend environment is managed by uv in backend/pyproject.toml, ensuring reproducible Python builds. The frontend is a standard Next.js application requiring Node.js packages.

Build and Run the Stack

DeerFlow supports two execution modes: local development for rapid iteration or Docker-based deployment for production parity.

Local Development Mode

For development on your host machine without containers:

make dev

This command starts four services in the correct order:

• LangGraph Server on port 2024 (handles the agent graph execution)
• Gateway API on port 8001 (FastAPI REST interface for models, memory, and uploads)
• Next.js Dev Server on port 3000 (React frontend with hot reloading)
• Nginx on port 2026 (reverse proxy routing /api/langgraph/* to the LangGraph server and /api/* to the gateway)

According to the Makefile at lines 52-66, this orchestration ensures the backend services initialize before the frontend attempts to connect.

Docker Deployment Mode

For isolated sandbox execution and production-like environments:

make docker-init
make docker-start

The make docker-init command builds a custom k3s image and pulls the sandbox container, while make docker-start launches the full stack using Docker Compose defined in docker/docker-compose-dev.yaml. This mode runs the Sandbox component in an isolated container rather than on the host filesystem, which is essential for secure code execution.

Alternatively, use the shell script directly:

./scripts/docker.sh init
./scripts/docker.sh start
./scripts/docker.sh logs --gateway

Architecture Overview

Understanding the runtime architecture helps debug build issues:

• Lead Agent: The central LangGraph agent that loads models, middleware chains, and tools
• Middleware Chain: Nine ordered middlewares (thread data, uploads, sandbox, summarization, todo-list, title, memory, image view, clarification) that process each turn
• Sandbox: Pluggable execution environment (local filesystem or Docker container)
• Sub-agents: Background workers supporting up to 3 concurrent tasks with 15-minute timeouts
• Memory: Persistent JSON store injecting facts into system prompts

This architecture is documented in backend/README.md and explains why the build process requires both Python (backend agents) and Node.js (frontend interface) environments.

Programmatic Access After Building

Once make dev completes, interact with the running services using the embedded Python client:

from src.client import DeerFlowClient

# Client automatically picks up config.yaml

client = DeerFlowClient()

print("Available models:", client.list_models())

response = client.chat(
    "Summarize the latest news about AI safety.",
    thread_id="demo-1"
)
print("Agent reply:", response)

The DeerFlowClient class in backend/src/client.py mirrors the HTTP Gateway API and provides a convenient interface for testing your build without using the web frontend.

Summary

• Clone the bytedance/deer-flow repository and run make config to generate config.yaml and .env from templates
• Install dependencies using make install, which runs uv sync for Python and pnpm install for Node.js
• Configure your LLM API keys in config.yaml before starting services
• Run locally with make dev for development (ports 2024, 8001, 3000, 2026) or use make docker-init && make docker-start for containerized deployment
• Verify the build by accessing the Nginx proxy at http://localhost:2026 or using the DeerFlowClient Python interface

Frequently Asked Questions

What are the system requirements to build DeerFlow from source?

You need Python 3.12 or higher with the uv package manager, Node.js 22 or higher with pnpm, and Git. Docker is optional but required if you want to run the sandbox in isolated containers rather than on the host filesystem.

Why does the build process use both uv and pnpm?

DeerFlow is a full-stack application where the backend agent system (LangGraph/LangChain) requires Python dependencies managed by uv in backend/pyproject.toml, while the web interface requires Node.js packages managed by pnpm in frontend/package.json. The Makefile coordinates both ecosystems.

How do I switch between local and Docker development modes?

For local development, use make dev which starts Python and Node processes directly on your host. For Docker mode, run make docker-init once to build images, then make docker-start to run containers. Docker mode is recommended for testing sandboxed code execution since it isolates the runtime environment.

Where does DeerFlow look for configuration files?

By default, DeerFlow reads config.yaml in the project root. You can override this by setting the DEER_FLOW_CONFIG_PATH environment variable to point to a custom configuration file location. The .env file stores sensitive API keys that should not be committed to version control.

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