How to Install DeerFlow: Complete Setup Guide for the Bytedance Super-Agent

Install DeerFlow by cloning the repository, running make config to generate configuration files, and executing make docker-init && make docker-start to launch the full stack on localhost:2026.

DeerFlow is ByteDance's open-source super-agent harness combining a Python/LangGraph backend with a Next.js frontend. This guide covers how to install DeerFlow from the bytedance/deer-flow repository using either Docker (recommended) or local development workflows.

Prerequisites

Before you install DeerFlow, ensure your system has the toolchain listed in the top-level Makefile and frontend README. You will need:

• Node.js ≥22 – Required for the Next.js frontend runtime per the frontend README.
• pnpm – The package manager for frontend dependencies.
• uv – The Python dependency manager required by the backend; the Makefile checks for its presence.
• nginx – Used as a reverse proxy; optional for local development but required for the Docker workflow.

Step-by-Step DeerFlow Installation

Clone the Repository and Generate Configuration

Start by cloning the repository and using the central Makefile to create default configuration files. The make config target, defined at line 23 of the Makefile, copies config.example.yaml to config.yaml and .env.example to .env while aborting if files already exist to protect your custom settings.

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

Choose Your Installation Method

DeerFlow supports two installation paths: Docker (recommended for consistency and sandbox execution) or local development (for active code modification).

Docker Installation (Recommended)

The Docker workflow builds a custom k3s image and orchestrates the backend, gateway, frontend, and nginx behind a reverse proxy. Execute the predefined Makefile targets:

make docker-init    # Builds the custom k3s image and pulls the sandbox container (Makefile line 70)

make docker-start   # Starts backend, gateway, frontend and nginx (Makefile line 75)

After containers finish initializing, access the DeerFlow UI at http://localhost:2026.

Local Development Installation

For local hacking without containers, the Makefile installs backend and frontend dependencies separately. The install rule runs uv sync for Python packages (lines 9–11) and pnpm install for Node modules (lines 12–14).

make install        # Installs backend and frontend dependencies

make dev            # Launches LangGraph server, Gateway API, Next.js dev server, and nginx (lines 64–71)

Configure API Keys

DeerFlow requires model and tool credentials to function. Populate the generated .env file (copied from .env.example) with keys such as OPENAI_API_KEY, TAVILY_API_KEY, or INFOQUEST_API_KEY as documented in README.md lines 84–95.

# Example: append your OpenAI key

echo "OPENAI_API_KEY=sk-..." >> .env

Verify Your Installation

Confirm the installation by navigating to http://localhost:2026 to view the DeerFlow chat interface. The backend health endpoint is available at http://localhost:8001/health via the nginx reverse proxy, confirming the Gateway API and LangGraph server are responsive.

Using the Embedded Python Client

If you prefer programmatic access without running the full server stack, import the embedded client from backend/src/client.py. This client loads config.yaml automatically and mirrors the HTTP Gateway API.

from src.client import DeerFlowClient

client = DeerFlowClient()                 # Loads config.yaml from the project root

print(client.list_models())               # Displays available LLM configurations

response = client.chat("Summarize the latest AI news")
print(response)                           # Returns the final agent reply

Summary

• Prerequisites: DeerFlow requires Node.js ≥22, pnpm, uv, and nginx before installation begins.
• Configuration: Run make config to generate config.yaml and .env from the repository's example templates.
• Docker Method: Execute make docker-init and make docker-start for a containerized stack reachable at localhost:2026.
• Local Method: Use make install followed by make dev to run services directly on your host.
• Secrets: Store API keys in .env (copied from .env.example) to enable LLM and tool access.
• Verification: Access the web UI at port 2026 or check the health endpoint at port 8001.

Frequently Asked Questions

What version of Node.js is required to install DeerFlow?

DeerFlow requires Node.js 22 or higher for the Next.js frontend, as specified in the frontend README.md. You must also install pnpm as the package manager; the Makefile does not support npm or yarn for the frontend workflow.

Can I install DeerFlow without Docker?

Yes. Use the local development workflow by running make install to sync Python dependencies with uv and install Node packages with pnpm, then execute make dev to start the LangGraph server, Gateway API, and Next.js development server. However, Docker is recommended because it includes the sandbox execution environment required for certain agent tools.

Where does DeerFlow store its configuration files?

After running make config, the main configuration files reside in the repository root: config.yaml (application settings, models, and tool definitions) and .env (secrets and API keys). These are copied from config.example.yaml and .env.example respectively, with the Makefile protecting existing files from accidental overwrites.

How do I add API keys to DeerFlow?

Edit the .env file in the project root (created by make config) and add your provider keys such as OPENAI_API_KEY, TAVILY_API_KEY, or INFOQUEST_API_KEY. The README.md lines 84–95 detail the specific environment variables required for each integrated model and search provider.

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