Quick Start

⚡

Get DeerFlow App running locally in about 10 minutes. You need a machine with Python 3.12+, Node.js 22+, and at least one LLM API key.

This guide walks you through starting DeerFlow App on your local machine using the make dev workflow. All four services (LangGraph, Gateway, Frontend, nginx) start together and are accessible through a single URL.

Prerequisites

Check that all required tools are installed:


make check

Required:

Tool	Minimum version
Python	3.12
uv	latest
Node.js	22
pnpm	10
nginx	any recent version

On macOS, install with brew install python uv node pnpm nginx. On Linux, use your distribution’s package manager.

Steps

Clone the repository


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

Install dependencies


make install

This installs both backend Python dependencies (via uv) and frontend Node.js dependencies (via pnpm).

Create your config file


cp config.example.yaml config.yaml

Then edit config.yaml to add at least one model. The minimum change is adding a model under the models: section:


models:
  - name: gpt-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    supports_vision: true

Set the corresponding environment variable before starting:


export OPENAI_API_KEY=sk-...

See the Application Configuration page for examples with other model providers.

Start all services


make dev

This starts:

LangGraph server on port 2024
Gateway API on port 8001
Frontend on port 3000
nginx reverse proxy on port 2026

Open http://localhost:2026 in your browser.

Stop all services


make stop

What happens when you run `make dev`

Existing service processes are stopped first (safe to run after an interrupted start).
Each service is started in the background and writes logs to the logs/ directory.
nginx proxies all traffic through port 2026, so you only need one URL.

Log files:

Service	Log file
LangGraph	`logs/langgraph.log`
Gateway	`logs/gateway.log`
Frontend	`logs/frontend.log`
nginx	`logs/nginx.log`

If something is not working, check the log files first. Most startup errors (missing API keys, config parsing failures) appear in logs/langgraph.log or logs/gateway.log.

Deployment Guide Configuration