# How to Set Up a Development Environment for DeerFlow: Complete Setup Guide

> Easily set up your DeerFlow development environment. Clone the repository run make commands for configuration and installation and launch services with docker-start or dev. Get started now.

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

---

**To set up a DeerFlow development environment, clone the bytedance/deer-flow repository, generate a local configuration with `make config`, install dependencies via `make install`, configure your API keys in `.env`, and launch services using `make docker-start` or `make dev`.**

DeerFlow 2.0 is a super-agent harness built on LangGraph and LangChain that coordinates sub-agents, memory, and sandboxed execution. Setting up a local development environment requires configuring three main components: a Python backend (API gateway and agent engine), a Next.js frontend (chat interface), and an isolated execution sandbox.

## Prerequisites

Before cloning the repository, ensure your system meets these minimum requirements. The `make check` command can verify these automatically.

| Tool | Minimum Version | Purpose |
|------|-----------------|---------|
| **Git** | any | Version control |
| **Node.js** | 22+ | Frontend runtime |
| **pnpm** | latest | Frontend package manager |
| **Python** | 3.11+ (managed by `uv`) | Backend runtime |
| **Docker** | Engine 23+ | Sandbox containerization |
| **Make** | any | Build automation |

Install `uv` (the Python package manager) with:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

```

## Step-by-Step Installation

### Clone the Repository

Start by cloning the official repository and entering the project directory:

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

```

The repository root contains the `Makefile`, [`config.example.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml) template, and orchestration files referenced throughout this guide.

### Generate the Configuration File

DeerFlow uses a root-level [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) file to wire together models, sandboxes, and skills. Generate it from the provided template:

```bash
make config

```

This 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). The file is automatically added to `.gitignore` to prevent committing secrets.

### Configure API Keys

Create a `.env` file at the repository root to store provider credentials outside of source control:

```bash
cat > .env <<EOF
OPENAI_API_KEY=your-openai-key
TAVILY_API_KEY=your-tavily-key
INFOQUEST_API_KEY=your-infoquest-key
EOF

```

Reference these variables in [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) using the `$` prefix (e.g., `api_key: $OPENAI_API_KEY`). This pattern keeps sensitive data out of [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) while maintaining flexibility across environments.

### Install Dependencies

Run the installation target to set up both backend and frontend environments:

```bash
make check   # Verify prerequisites

make install # Install Python and Node.js dependencies

```

The `make install` command executes `uv sync` for the Python backend and `pnpm install` inside the `frontend/` directory, ensuring both the FastAPI server and Next.js 14 application have their required packages.

### Configure the Sandbox Mode

DeerFlow supports three sandbox providers configured in the `sandbox:` section of [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml):

1. **LocalSandboxProvider** – Executes tools directly on the host (simplest for quick tests)
2. **AioSandboxProvider** – Docker-based isolation (recommended for development)
3. **AioSandboxProvider + provisioner_url** – Kubernetes-based orchestration (production scale)

For Docker-based development (the default), use this configuration in [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml):

```yaml
sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  auto_start: true
  container_prefix: deer-flow-sandbox
  port: 8080  # Optional; auto-chosen if omitted

```

This configuration leverages the `AioSandboxProvider` class in `backend/src/community/aio_sandbox` to manage container lifecycle automatically.

### Start the Development Server

Choose between Docker-based or pure local development:

**Option 1: Docker (Recommended)**

```bash
make docker-init  # Pull the sandbox Docker image (one-time)

make docker-start # Start backend, frontend, and sandbox containers

```

This reads from [`docker/docker-compose-dev.yaml`](https://github.com/bytedance/deer-flow/blob/main/docker/docker-compose-dev.yaml) and exposes the UI at **http://localhost:2026**.

**Option 2: Local Development**

```bash
make dev

```

This launches the FastAPI backend and Next.js frontend processes directly on your host machine. If using `LocalSandboxProvider`, tools execute in the same process space.

## Verify Your Setup

Open **http://localhost:2026** in your browser. You should see the DeerFlow chat interface.

Test the API connectivity using the embedded Python client defined in [`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py):

```python
from src.client import DeerFlowClient

client = DeerFlowClient()
print(client.list_models())

```

A successful response confirms that the backend, configuration parsing, and model registration are functioning correctly.

## Development Configuration Examples

### Minimal config.yaml for Docker Sandbox

This complete example configures a GPT-4 model and Docker sandbox:

```yaml
models:
  - name: gpt-4
    display_name: GPT-4
    use: langchain_openai:ChatOpenAI
    model: gpt-4
    api_key: $OPENAI_API_KEY
    max_tokens: 4096
    temperature: 0.7

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  auto_start: true
  container_prefix: deer-flow-sandbox

```

Reference the full template in [`config.example.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.example.yaml) for additional options including skill configurations and memory settings.

### Essential Makefile Targets

The root `Makefile` provides these convenience commands:

- **`make check`** – Validates Node.js, pnpm, uv, and Docker installations
- **`make install`** – Runs `uv sync` and `pnpm install`
- **`make config`** – Generates [`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)
- **`make docker-init`** – Pulls the required sandbox Docker image
- **`make docker-start`** – Launches the full Docker Compose stack
- **`make dev`** – Starts backend and frontend locally with hot-reloading

### Using the Embedded Python Client

For programmatic testing during development, use the `DeerFlowClient` class:

```python
from src.client import DeerFlowClient

client = DeerFlowClient()  # Automatically reads config.yaml

# List available capabilities

print("Models:", client.list_models())
print("Skills:", client.list_skills())

# Execute a chat interaction

response = client.chat("Explain the repository structure.")
print("Agent:", response["content"])

```

This client handles authentication, request routing, and response parsing against the local FastAPI backend.

## Summary

- **Prerequisites**: Install Git, Node.js 22+, pnpm, Python 3.11+ (via `uv`), Docker 23+, and Make before starting.
- **Configuration**: Run `make config` to generate [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml), then populate `.env` with API keys using the `$VAR` syntax.
- **Dependencies**: Execute `make install` to synchronize Python packages with `uv` and Node.js packages with `pnpm`.
- **Sandbox Selection**: Choose `AioSandboxProvider` for Docker isolation (recommended) or `LocalSandboxProvider` for direct execution.
- **Launch**: Use `make docker-start` for containerized development or `make dev` for local process execution.
- **Verification**: Access the UI at `http://localhost:2026` and test with `DeerFlowClient` from [`backend/src/client.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py).

## Frequently Asked Questions

### What are the minimum system requirements for DeerFlow?

DeerFlow requires Python 3.11 or higher for the backend, Node.js 22 or higher for the frontend, and Docker Engine 23 or higher if using containerized sandboxes. The `make check` command verifies all prerequisites automatically before installation begins.

### How do I switch between local and Docker sandbox modes?

Modify the `sandbox.use` field in [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml). Set it to `src.community.aio_sandbox:AioSandboxProvider` for Docker-based isolation (with `auto_start: true`), or change it to `LocalSandboxProvider` for direct execution on the host. Restart the services using `make docker-start` or `make dev` after changing this configuration.

### Where are API keys stored in DeerFlow?

API keys should be stored in a `.env` file at the repository root, never in [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml). Reference them in [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) using the syntax `$ENV_VAR_NAME`. The `.env` file is listed in `.gitignore` by default to prevent accidental commits of sensitive credentials.

### How do I add custom skills to my development environment?

Custom skills are registered in [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) under the `skills:` section, pointing to Python modules that implement the skill interface. Place your skill code in the `backend/src/skills/` directory (or a custom path), then reference the module path in the configuration. The backend dynamically loads these on startup according to [`backend/docs/CONFIGURATION.md`](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md).