# How to Build DeerFlow From Source: Complete Installation Guide

> Learn how to build DeerFlow from source with this complete installation guide. Clone the repository, configure, install dependencies, and start the development stack.

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

---

**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.

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

```

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

```bash
make config

```

This command copies [`config.example.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml) to [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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:

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

```bash
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:

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

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

```python
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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/pyproject.toml), while the web interface requires Node.js packages managed by `pnpm` in [`frontend/package.json`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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.