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

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:

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:

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

The repository root contains the Makefile, config.example.yaml template, and orchestration files referenced throughout this guide.

Generate the Configuration File

DeerFlow uses a root-level config.yaml file to wire together models, sandboxes, and skills. Generate it from the provided template:

make config

This copies config.example.yaml to 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:

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 using the $ prefix (e.g., api_key: $OPENAI_API_KEY). This pattern keeps sensitive data out of config.yaml while maintaining flexibility across environments.

Install Dependencies

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

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:

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:

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)

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 and exposes the UI at http://localhost:2026.

Option 2: Local Development

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:

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:

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 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 from 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:

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

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. 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. Reference them in 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 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.

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