Skip to content
BSWEN
Blog

How to Set Up and Run DeerFlow Locally in 5 Minutes

Cowrie
Cowrie
Dev @ Bswen

Purpose

This post shows how to set up and run DeerFlow locally. The key point is using Docker deployment for the fastest path to a working system.

Problem

I wanted to try DeerFlow, ByteDance’s open-source AI agent framework. I cloned the repository and got stuck.

Here’s what I tried first:

my-first-attempt.sh
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make install
make dev

I got this error:

error-output.txt
ERROR: Node.js version 18.17.0 is not supported. Please use Node.js 22+.
ERROR: Python version 3.10.0 is not supported. Please use Python 3.12+.

My local environment was outdated. I didn’t want to upgrade my system Node.js and Python versions just for one project.

I tried using nvm and pyenv to manage versions. It worked, but then I hit dependency conflicts with my existing projects.

I needed a cleaner approach that wouldn’t mess up my development environment.

Environment

  • macOS or Linux (Windows via WSL2)
  • Docker Desktop or Docker Engine
  • At least one LLM API key (OpenAI, Anthropic, or compatible)
  • 8GB RAM minimum, 16GB recommended

Solution: Docker Deployment

DeerFlow provides a Docker-based deployment that isolates all dependencies. This approach solved my environment issues completely.

Step 1: Check Prerequisites

Before starting, I ran the prerequisite check:

check-prereqs.sh
make check

I got this output:

prerequisite-check.txt
Checking prerequisites...
[OK] Docker: 24.0.7
[OK] Docker Compose: 2.23.0
[OK] Git: 2.43.0
[OK] Make: 3.81
[MISSING] Node.js 22+ (required for local dev only)
[MISSING] Python 3.12+ (required for local dev only)
[MISSING] pnpm 10.26.2+ (required for local dev only)
[MISSING] uv (required for local dev only)


Docker deployment: READY
Local development: MISSING DEPENDENCIES

The check confirmed Docker deployment was ready. I could skip local development setup entirely.

Step 2: Clone and Configure

I cloned the repository and generated configuration files:

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

This command generated three configuration files:

config-files.txt
Created: config.yaml         # Main application configuration
Created: .env                 # Environment variables (API keys)
Created: extensions_config.json  # MCP servers and skills

Step 3: Configure Your Model

I opened config.yaml to define my LLM provider. The default template looked like this:

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

I use multiple providers, so I configured them all:

config.yaml
models:
  # OpenAI GPT-4o
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    supports_vision: true


  # Anthropic Claude
  - name: claude-3-5-sonnet
    display_name: Claude 3.5 Sonnet
    use: langchain_anthropic:ChatAnthropic
    model: claude-3-5-sonnet-20241022
    api_key: $ANTHROPIC_API_KEY


  # OpenRouter (OpenAI-compatible API)
  - name: gemini-flash
    display_name: Gemini 2.5 Flash
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

The use field specifies which LangChain integration to use. DeerFlow supports any LangChain-compatible provider.

Step 4: Set API Keys

I edited .env to add my API keys:

.env
# Required: At least one LLM API key
OPENAI_API_KEY=sk-proj-your-key-here


# Optional: For web search tools
TAVILY_API_KEY=tvly-your-key-here


# Optional: For Claude models
ANTHROPIC_API_KEY=sk-ant-your-key-here


# Optional: For OpenRouter
OPENROUTER_API_KEY=sk-or-your-key-here

I made a mistake here. I initially put the key directly in config.yaml:

wrong-config.yaml
# WRONG: Hardcoded key
api_key: sk-proj-xxxxx


# CORRECT: Environment variable reference
api_key: $OPENAI_API_KEY

The $VARIABLE syntax is important. It reads from your .env file instead of hardcoding secrets.

Step 5: Pull and Start Docker

I pulled the sandbox image and started all services:

docker-start.sh
# Pull sandbox image (one-time setup)
make docker-init


# Start all services
make docker-start

I got this output:

docker-start-output.txt
Pulling deer-flow-sandbox...
latest: Pulling from bytedance/deer-flow-sandbox
Digest: sha256:abc123...
Status: Downloaded newer image


Starting services...
[+] Running 4/4
  Network deer-flow_default    Created
  Container deer-flow-frontend  Started
  Container deer-flow-gateway   Started
  Container deer-flow-backend   Started
  Container deer-flow-sandbox   Started


DeerFlow is running at http://localhost:2026

Step 6: Access the Application

I opened http://localhost:2026 in my browser. The interface loaded successfully.

I verified the installation with curl:

verify-installation.sh
# Check if services are running
curl http://localhost:2026/health


# List available models
curl http://localhost:2026/api/models


# List available skills
curl http://localhost:2026/api/skills

I got this output:

health-response.json
{
  "status": "healthy",
  "services": {
    "frontend": "running",
    "gateway": "running",
    "backend": "running",
    "sandbox": "running"
  }
}

Architecture Overview

DeerFlow’s architecture looks like this:

architecture-diagram.txt
User → http://localhost:2026
              │
              ▼
         ┌─────────┐
         │  Nginx  │     ← Reverse proxy on port 2026
         └────┬────┘
              │
    ┌─────────┼─────────┐
    ▼         ▼         ▼
Frontend  Gateway   LangGraph
(3000)    (8001)    (2024)       ← Internal ports
    │         │         │
    │         │         ▼
    │         │    ┌─────────┐
    │         │    │ Sandbox │ ← Isolated code execution
    │         │    │ Docker  │
    │         │    └─────────┘
    │         │
    ▼         ▼
┌─────────────────┐
│   LLM Providers │ ← OpenAI, Anthropic, etc.
└─────────────────┘

Understanding this helped me debug issues later. Each component runs in its own container:

  • Nginx (port 2026): Entry point, routes requests
  • Frontend (port 3000): React-based UI
  • Gateway (port 8001): API gateway for frontend
  • LangGraph (port 2024): Backend agent runtime
  • Sandbox: Docker-based code execution

Common Issues

Issue 1: Port Conflicts

I got this error when port 2026 was already in use:

port-conflict-error.txt
Error: bind: address already in use
  Port 2026 is occupied by another process

I checked what was using the port:

check-port.sh
lsof -i :2026

I got this output:

port-usage.txt
COMMAND   PID   USER   FD   TYPE   DEVICE SIZE/OFF NODE NAME
nginx    12345  user   6u  IPv4   123456      0t0  TCP *:2026 (LISTEN)

I killed the process:

kill-port-process.sh
kill -9 12345

Alternatively, I could modify the port in the Docker Compose file:

docker-compose.override.yml
services:
  nginx:
    ports:
      - "2027:2026"  # Use 2027 externally

Issue 2: Missing Provider Modules

When I added a new provider, I got this error:

missing-module-error.txt
ERROR: ModuleNotFoundError: No module named 'langchain_google_genai'

The error message suggested the fix:

install-provider.sh
cd backend && uv add langchain-google-genai

After installing the missing module, I restarted:

restart-services.sh
make docker-start

Issue 3: Sandbox Image Pull Fails

On slow networks, the sandbox image pull timed out:

pull-timeout-error.txt
ERROR: failed to register layer: write /var/lib/docker/overlay2/...: no space left on device

I cleaned up Docker and retried:

docker-cleanup.sh
# Clean up unused Docker resources
docker system prune -a


# Manually pull the image
docker pull ghcr.io/bytedance/deer-flow-sandbox:latest


# Try again
make docker-init
make docker-start

Issue 4: API Key Not Found

I forgot to add my API key to .env. I got this error:

missing-api-key-error.txt
ERROR: OpenAI API key not found
  Please set OPENAI_API_KEY in your .env file

I checked my .env file:

check-env.sh
cat .env | grep API_KEY

The key was missing. I added it:

add-api-key.sh
echo "OPENAI_API_KEY=sk-proj-your-key-here" >> .env

Then I restarted the services:

restart-after-env.sh
make docker-start

Local Development Alternative

If you prefer running without Docker, you need to install the prerequisites:

local-prerequisites.sh
# Install Node.js 22+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs


# Install pnpm
npm install -g [email protected]


# Install Python 3.12+
pyenv install 3.12.0
pyenv global 3.12.0


# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Then install and run:

local-dev.sh
make install
make dev

I found Docker deployment much simpler. It isolates all dependencies and works consistently across different machines.

Sandbox Modes

DeerFlow supports three sandbox modes for code execution:

config.yaml
sandbox:
  # Local mode: Run code directly (fastest, least secure)
  mode: local


  # Docker mode: Run in Docker container (balanced)
  mode: docker


  # Kubernetes mode: Run in K8s pod (most secure)
  mode: kubernetes
  provisioner: k8s

I use Docker mode for local development. It provides good isolation without Kubernetes complexity.

Summary

In this post, I showed how to set up and run DeerFlow locally. The key points are:

  • Use Docker deployment to avoid environment conflicts
  • Configure at least one LLM provider in config.yaml
  • Store API keys in .env using $VARIABLE references
  • Run make docker-init && make docker-start for quick setup
  • Check port availability before starting

DeerFlow’s setup is streamlined with Make commands and sensible defaults. The Docker deployment provides a complete environment with minimal configuration. For production deployments, customize config.yaml with your preferred models, sandbox mode, and optional MCP servers.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: