Local Development

Run DeerFlow services locally without Docker for maximum control

Overview

Local development runs all services directly on your machine, giving you maximum control and flexibility. This is ideal for:

• Deep debugging and development
• Working with local development tools
• Environments where Docker isn’t available
• Maximum performance on your hardware

Local development requires installing Node.js, Python, uv, pnpm, and nginx on your machine. If you prefer a simpler setup, see Docker Setup.

Prerequisites

Verify all required tools are installed:

make check

Required:

• Node.js 22+
• pnpm
• uv (Python package manager)
• nginx

See Installation Guide for setup instructions.

Architecture

Local development runs these services:

nginx (port 2026) ← Unified entry point
  ├→ Frontend (port 3000) ← Next.js dev server
  ├→ Gateway API (port 8001) ← FastAPI application
  └→ LangGraph Server (port 2024) ← Agent runtime

Quick Start

1. Configure Application

   Ensure config.yaml is configured with your model and API keys:

   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
   

   See Installation Guide for details.

2. Install Dependencies

   Install frontend and backend dependencies:

   make install
   

   This runs:

   • cd backend && uv sync - Python dependencies
   • cd frontend && pnpm install - Node.js dependencies
3. Start All Services

   Start all services with nginx reverse proxy:

   make dev
   

   This starts:

   1. LangGraph server (port 2024)
   2. Gateway API (port 8001)
   3. Frontend (port 3000)
   4. nginx reverse proxy (port 2026)

   All services start automatically and run in the background. Press Ctrl+C to stop all services.

4. Access Application

   Open your browser to:

   • Web Interface: http://localhost:2026
   • API Gateway: http://localhost:2026/api/*
   • LangGraph: http://localhost:2026/api/langgraph/*

Running Services Individually

For more control, start each service in a separate terminal:

All Services

Terminal 1 - LangGraph Server:

cd backend
make dev

Terminal 2 - Gateway API:

cd backend
make gateway

Terminal 3 - Frontend:

cd frontend
pnpm dev

Terminal 4 - nginx:

make nginx
# Or directly:
nginx -c $(pwd)/docker/nginx/nginx.local.conf -g 'daemon off;'

Backend Only

Start backend services without frontend:

# Terminal 1 - LangGraph
cd backend
uv run langgraph dev --no-browser --allow-blocking

# Terminal 2 - Gateway
cd backend
uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001 --reload

Access:

• LangGraph: http://localhost:2024
• Gateway: http://localhost:8001

Frontend Only

Start frontend in development mode:

cd frontend
pnpm dev

Access: http://localhost:3000

Configure API endpoint in frontend/.env if backend is running elsewhere.

Service Details

LangGraph Server (Port 2024)

The core agent runtime that executes agent logic, tools, and manages conversation state.

Entry Point: backend/src/agents/lead_agent/agent.py

Start Command:

cd backend
uv run langgraph dev --no-browser --allow-blocking

Features:

• SSE streaming for real-time responses
• Thread state management
• Middleware chain execution
• Tool orchestration

Configuration: backend/langgraph.json

Gateway API (Port 8001)

FastAPI application providing REST endpoints for models, skills, MCP, uploads, and artifacts.

Entry Point: backend/src/gateway/app.py

Start Command:

cd backend
uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001 --reload

Endpoints:

• /api/models - Model management
• /api/mcp - MCP server configuration
• /api/skills - Skills management
• /api/threads/{id}/uploads - File uploads
• /api/threads/{id}/artifacts - Artifact serving

Frontend (Port 3000)

Next.js application providing the web interface.

Start Command:

cd frontend
pnpm dev

Features:

• React-based chat interface
• Real-time SSE streaming
• File upload support
• Artifact rendering

nginx (Port 2026)

Reverse proxy that unifies all services under a single port.

Configuration: docker/nginx/nginx.local.conf

Start Command:

nginx -c $(pwd)/docker/nginx/nginx.local.conf -g 'daemon off;'

Routing:

• / → Frontend (3000)
• /api/langgraph/* → LangGraph (2024)
• /api/* → Gateway (8001)

Development Workflow

Hot Reload

All services support hot reload:

Frontend

Changes to frontend/src/** trigger automatic browser reload

Backend

Changes to backend/src/** automatically restart services (with --reload flag)

Config

Changes to config.yaml require manual service restart

Skills

Changes to skills/** are loaded dynamically by the agent

Logs

View logs in separate terminal windows or check log files:

# View logs (when using make dev)
tail -f logs/langgraph.log
tail -f logs/gateway.log
tail -f logs/frontend.log
tail -f logs/nginx.log

Testing

Backend Tests

cd backend
uv run pytest

# Run specific test
uv run pytest tests/test_config.py

# Run with coverage
uv run pytest --cov=src

Frontend Tests

cd frontend
pnpm test

# Watch mode
pnpm test:watch

Debugging

1. Backend Debugging

   Add breakpoints using Python debugger:

   import pdb; pdb.set_trace()
   

   Or use VS Code debugger with launch configuration.

2. Frontend Debugging

   Use browser DevTools:

   • Console for logs
   • Network tab for API requests
   • React DevTools for component inspection
3. API Debugging

   Use curl or tools like Postman:

   # Test Gateway API
   curl http://localhost:8001/api/models
   
   # Test LangGraph
   curl http://localhost:2024/threads
   

Stopping Services

Stop All (make dev)

# Press Ctrl+C in the terminal running make dev
# Or run:
make stop

Project Structure

Understanding the codebase:

deer-flow/
├── config.yaml              # Main configuration
├── .env                     # Environment variables
├── Makefile                 # Build and dev commands
├── backend/
│   ├── src/
│   │   ├── agents/          # LangGraph agent logic
│   │   ├── gateway/         # FastAPI Gateway
│   │   ├── tools/           # Built-in tools
│   │   ├── sandbox/         # Sandbox execution
│   │   ├── models/          # Model factory
│   │   ├── skills/          # Skills system
│   │   └── mcp/             # MCP integration
│   ├── tests/               # Backend tests
│   └── pyproject.toml       # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── app/             # Next.js app router
│   │   ├── components/      # React components
│   │   └── lib/             # Utility functions
│   └── package.json         # Node dependencies
├── skills/
│   ├── public/              # Built-in skills
│   └── custom/              # User-created skills
└── docker/
    └── nginx/               # nginx configurations

Troubleshooting

Services fail to start

Check if ports are already in use:

lsof -i :2026  # nginx
lsof -i :3000  # frontend
lsof -i :8001  # gateway
lsof -i :2024  # langgraph

Stop conflicting processes:

make stop

Module not found errors

Reinstall dependencies:

make install

Or individually:

cd backend && uv sync
cd frontend && pnpm install

nginx fails to start

Check nginx configuration:

nginx -t -c $(pwd)/docker/nginx/nginx.local.conf

Ensure nginx is installed:

which nginx

Hot reload not working

For backend, ensure --reload flag is used:

cd backend
uv run uvicorn src.gateway.app:app --reload

For frontend, check file watcher limits:

# macOS/Linux
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Next Steps

Docker Setup

Try Docker development for easier environment management

Creating Skills

Extend DeerFlow with custom skills

Custom Tools

Add custom tools to the agent

File Uploads

Implement file upload functionality