DeerFlow 2.0 Quick Start Guide: From Zero to Multi-Agent Super Harness on Ubuntu 24.04

If you've been following the AI agent space in 2026, you've probably heard the buzz: DeerFlow 2.0 just hit #1 on GitHub Trending with 50.7k stars and counting. This isn't just another research tool—it's a complete super agent harness that gives your AI agents their own computer: sandboxed execution, persistent memory, skills that load on demand, and the ability to spawn sub-agents for tasks that take minutes to hours.

For NXagents users, integrating DeerFlow 2.0 into your go2apicli Docker environment unlocks serious multi-agent orchestration power. In this guide, I'll walk you through a complete zero-to-hero setup on Ubuntu 24.04.

GitHub: bytedance/deer-flow | Stars: 50.7k | Forks: 6.1k | License: MIT

Why DeerFlow 2.0? The "Super Agent Harness" Explained

DeerFlow started as a deep research framework. But the community pushed it way beyond that—data pipelines, slide decks, dashboards, content automation. The team realized: DeerFlow wasn't just a research tool. It was a runtime that gives agents the infrastructure to actually get work done.

So they rebuilt it from scratch.

DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness—batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs:

• A filesystem — each task runs in an isolated Docker container
• Memory — builds user profiles across sessions
• Skills — modular workflows that load progressively
• Sandboxed execution — plan and spawn sub-agents for complex, multi-step tasks
• IM channels — Telegram, Slack, Feishu/Lark integration

System Requirements for Ubuntu 24.04

Before we begin, ensure your system meets these requirements:

Installation Method 1: Docker (Recommended for go2apicli)

This is the cleanest method for integrating with your go2apicli Docker environment.

Step 1.1: Install Docker on Ubuntu 24.04

#!/bin/bash
# install-docker-ubuntu-24.sh

# Update package index
sudo apt update

# Install prerequisites
sudo apt install -y ca-certificates curl gnupg lsb-release

# Add Docker GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add current user to docker group
sudo usermod -aG docker $USER

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

# Verify installation
docker --version
docker compose version

Step 1.2: Clone DeerFlow Repository

# Navigate to go2apicli sandbox directory
cd /opt/go2apicli/sandbox

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

# Verify latest version
git fetch origin
git checkout $(git describe --tags $(git rev-list --tags --max-count=1))

Step 1.3: Generate Configuration

# Generate local configuration files from templates
make config

# This creates:
# - config.yaml (main configuration)
# - .env (environment variables)

Step 1.4: Configure Models

Edit config.yaml with your preferred model(s). Here are tested configurations:

# config.yaml - Example configurations

models:
  # DeepSeek V3 (Recommended - best value)
  - name: deepseek-v3
    display_name: DeepSeek V3 (Thinking)
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: deepseek-reasoner
    api_key: $DEEPSEEK_API_KEY
    max_tokens: 8192
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        thinking:
          type: enabled

  # GPT-4o (Production)
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    max_tokens: 4096
    temperature: 0.7
    supports_vision: true

  # Claude 3.5 Sonnet (Reliable)
  - 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
    max_tokens: 8192
    supports_vision: true
    when_thinking_enabled:
      thinking:
        type: enabled

  # Gemini 2.5 Flash (Fast, via OpenRouter)
  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENAI_API_KEY
    base_url: https://openrouter.ai/api/v1
    max_tokens: 8192
    temperature: 0.7

Step 1.5: Set API Keys

# Edit .env file
nano .env

Add your API keys:

# .env

# DeepSeek (Recommended)
DEEPSEEK_API_KEY=sk-your-deepseek-api-key

# OpenAI (Alternative)
OPENAI_API_KEY=sk-your-openai-api-key

# Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# Search Tools (optional - DuckDuckGo is free)
TAVILY_API_KEY=your-tavily-api-key
JINA_API_KEY=your-jina-api-key

# LangSmith Tracing (optional)
# LANGSMITH_TRACING=true
# LANGSMITH_ENDPOINT=https://api.smith.langchain.com
# LANGSMITH_API_KEY=your-langsmith-key
# LANGSMITH_PROJECT=deerflow-nxagents

Step 1.6: Initialize Docker Environment

# First-time only: Build Docker images and install dependencies
make docker-init

# This will:
# 1. Build custom Docker images
# 2. Install frontend dependencies (pnpm)
# 3. Install backend dependencies (uv)
# 4. Share pnpm cache with host for faster builds

Step 1.7: Start DeerFlow

# Start development services
make docker-start

# Verify containers are running
docker ps | grep deerflow

# View logs
docker logs -f deerflow-web
docker logs -f deerflow-api

Step 1.8: Verify Installation

# Test API is running
curl http://localhost:2026/health

# Expected response:
# {"status": "ok", "version": "2.0.0"}

# Access the web interface
# http://localhost:2026

Installation Method 2: Local Development

For development or testing without Docker.

Step 2.1: Install Prerequisites

#!/bin/bash
# install-deerflow-local.sh

# Install system dependencies
sudo apt update
sudo apt install -y \
    python3.11 \
    python3.11-venv \
    python3-pip \
    build-essential \
    libssl-dev \
    libffi-dev \
    libxml2-dev \
    libxslt-dev \
    zlib1g-dev \
    nodejs \
    npm \
    nginx

# Install pnpm
npm install -g pnpm

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

# Install nvm (Node version manager - recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

Step 2.2: Clone and Configure

cd /opt/go2apicli/sandbox
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make config
# Edit config.yaml and .env as shown above

Step 2.3: Check Prerequisites

make check

# Should output:
# Checking Node.js... ✓ Node.js 22+
# Checking pnpm... ✓ pnpm installed
# Checking uv... ✓ uv installed
# Checking nginx... ✓ nginx installed

Step 2.4: Install Dependencies

make install

Step 2.5: Start Development Server

make dev

# Access:
# http://localhost:2026

Docker Architecture (What Gets Deployed)

When you run make docker-start, DeerFlow deploys this architecture:

Host Machine (Ubuntu 24.04)
    ↓
Docker Compose (deer-flow-dev)
├→ nginx (port 2026) ← Reverse proxy, unified entry point
├→ web (port 3000) ← Frontend with hot-reload
├→ api (port 8001) ← Gateway API with hot-reload
├→ langgraph (port 2024) ← LangGraph server with hot-reload
└→ provisioner (optional, port 8002) ← Started only in provisioner/K8s sandbox mode

Services:

• nginx: Unified entry point on port 2026, routes /api/langgraph/* to LangGraph Server, other /api/* to Gateway API
• web: Frontend with hot-reload
• api: Gateway API for thread management, skills, MCP
• langgraph: LangGraph server for agent interactions

go2apicli Integration: NXagents ↔ DeerFlow

This is the real value for NXagents users. Here's how to integrate DeerFlow with your go2apicli Docker:

Architecture Overview

┌─────────────┐     REST      ┌──────────────┐   CLI/Shell   ┌──────────────┐
│  NXagents   │ ────────────► │  go2apicli   │ ─────────────► │   DeerFlow   │
│  (Control   │               │  (Execution  │                 │   (Task      │
│   Plane)    │               │    Layer)    │                 │   Executor)  │
└─────────────┘               └──────────────┘                 └──────────────┘

Step 1: Add DeerFlow to go2apicli Whitelist

# go2apicli config/integrations.yaml
integrations:
  deerflow:
    enabled: true
    endpoint: http://localhost:2026
    timeout: 3600000  # 1 hour max for long-horizon tasks
    sandbox:
      enabled: true
      memory_limit: 4GB
      cpu_limit: 2
      network_enabled: true

Step 2: Create go2apicli CLI Wrapper

#!/bin/bash
# /usr/local/bin/deerflow-cli
# Wrapper script for go2apicli to call DeerFlow

DEERFLOW_HOST="${DEERFLOW_HOST:-http://localhost:2026}"

# Parse arguments
TASK=""
MODEL=""
STREAM="false"

while [[ $# -gt 0 ]]; do
  case $1 in
    --task)
      TASK="$2"
      shift 2
      ;;
    --model)
      MODEL="$2"
      shift 2
      ;;
    --stream)
      STREAM="$2"
      shift 2
      ;;
    *)
      break
      ;;
  esac
done

# Execute via DeerFlow REST API
curl -s -X POST "${DEERFLOW_HOST}/api/v1/tasks" \
  -H "Content-Type: application/json" \
  -d "{\"task\": \"$TASK\", \"model\": \"${MODEL:-deepseek-v3}\", \"stream\": $STREAM}"

Step 3: Test Integration

# Test 1: Health check
curl http://localhost:2026/health

# Test 2: Simple task via API
curl -X POST http://localhost:2026/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "task": "What is 2+2? Answer in one sentence.",
    "model": "deepseek-v3"
  }'

# Test 3: Research task
curl -X POST http://localhost:2026/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Research the latest developments in AI agents. Provide a summary.",
    "model": "deepseek-v3",
    "tools": ["web_search", "web_fetch"]
  }'

Step 4: NXagents Python Client Example

from deerflow.client import DeerFlowClient

# Initialize client
client = DeerFlowClient(base_url="http://localhost:2026")

# Chat (blocking)
response = client.chat(
    "Research AI startups in 2026",
    thread_id="nxagents-research-001",
    model="deepseek-v3"
)
print(response)

# Streaming (for real-time updates)
for event in client.stream("Create a Python web server"):
    if event.type == "messages-tuple":
        content = event.data.get("content", "")
        print(content, end="", flush=True)

# List available models
models = client.list_models()
print(f"Available models: {models}")

# Upload files for analysis
result = client.upload_files(
    thread_id="nxagents-analysis-001",
    files=["./report.pdf", "./data.csv"]
)
print(f"Uploaded: {result}")

Key Features for NXagents Use Cases

For Research Tasks

• Progressive skill-loading: DeerFlow activates capabilities only when needed
• Extensible skills system: Markdown-based workflows for research, reports, slides
• Persistent memory: Builds user profiles across sessions

For Coding Tasks

• Docker-based sandboxing: Built-in, essential for safe code execution
• Sub-agent parallel execution: Multiple coding agents can work simultaneously
• Isolated contexts: Each sub-agent can't corrupt others' work

For Production

• Claude Code integration: npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow
• LangSmith tracing: Full observability for LLM calls and agent runs
• IM channels: Telegram, Slack, Feishu/Lark for task routing

Quick Reference: Make Commands

Troubleshooting

Debug Mode

# Enable debug logging
# In config.yaml:
log_level: debug

# View detailed logs
docker logs -f deerflow-langgraph --tail 200

# Test network connectivity
docker exec -it deerflow-api ping google.com

Security Considerations

⚠️ DeerFlow has high-privilege capabilities including system command execution. The team recommends:

1. Deploy in a local trusted network (accessible only via 127.0.0.1)
2. Use IP allowlisting with iptables
3. Configure authentication gateway with nginx
4. Enable network isolation with dedicated VLAN

For go2apicli integration, ensure DeerFlow runs inside the sandbox with restricted network access.

What's Next?

Once DeerFlow is running, explore:

1. Skills System: Add custom Markdown-based skills in skills/custom/
2. MCP Servers: Integrate Model Context Protocol servers for extended capabilities
3. IM Channels: Connect Telegram/Slack for mobile task routing
4. LangSmith: Enable tracing for production observability
5. Sub-agents: Test multi-agent orchestration for complex workflows

Conclusion

DeerFlow 2.0 represents a fundamental shift in AI agent architecture. It's no longer about chatbots with tool access—it's about agents with their own computer: sandboxed execution, persistent memory, and the ability to plan complex multi-step tasks.

For NXagents users, integrating DeerFlow into your go2apicli Docker environment gives you the best of both worlds: NXagents as the control plane with DeerFlow as the task execution harness. Simple tasks stay in NXagents; complex, long-horizon tasks route to DeerFlow's multi-agent orchestration.

GitHub: bytedance/deer-flow
Official Site: deerflow.tech
License: MIT

Happy hacking! 🚀