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

> Install DeerFlow with our comprehensive guide. Clone the repo, configure, and launch the Bytedance Super-Agent stack locally in minutes.

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

---

**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](https://github.com/bytedance/deer-flow/blob/main/Makefile#L23), 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` while aborting if files already exist to protect your custom settings.

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

```bash
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](https://github.com/bytedance/deer-flow/blob/main/Makefile#L9)) and `pnpm install` for Node modules ([lines 12–14](https://github.com/bytedance/deer-flow/blob/main/Makefile#L12)).

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

```bash

# 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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py). This client loads [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) automatically and mirrors the HTTP Gateway API.

```python
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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) (application settings, models, and tool definitions) and `.env` (secrets and API keys). These are copied from [`config.example.yaml`](https://github.com/bytedance/deer-flow/blob/main/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](https://github.com/bytedance/deer-flow/blob/main/README.md#L84) detail the specific environment variables required for each integrated model and search provider.