NX
NXplace
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
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:
Before we begin, ensure your system meets these requirements:
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores | 8+ cores |
| RAM | 8 GB | 16+ GB |
| Disk | 20 GB free | 50+ GB SSD |
| Docker | 20.10+ | 24.0+ |
| Docker Compose | 2.0+ | 2.20+ |
| Node.js | 18+ | 22+ |
| Python | 3.10+ | 3.11+ |
This is the cleanest method for integrating with your go2apicli Docker environment.
#!/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
# 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))
# Generate local configuration files from templates
make config
# This creates:
# - config.yaml (main configuration)
# - .env (environment variables)
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
# 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
# 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
# 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
# Test API is running
curl http://localhost:2026/health
# Expected response:
# {"status": "ok", "version": "2.0.0"}
# Access the web interface
# http://localhost:2026
For development or testing without Docker.
#!/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
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
make check
# Should output:
# Checking Node.js... ✓ Node.js 22+
# Checking pnpm... ✓ pnpm installed
# Checking uv... ✓ uv installed
# Checking nginx... ✓ nginx installed
make install
make dev
# Access:
# http://localhost:2026
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:
/api/langgraph/* to LangGraph Server, other /api/* to Gateway APIThis is the real value for NXagents users. Here's how to integrate DeerFlow with your go2apicli Docker:
┌─────────────┐ REST ┌──────────────┐ CLI/Shell ┌──────────────┐
│ NXagents │ ────────────► │ go2apicli │ ─────────────► │ DeerFlow │
│ (Control │ │ (Execution │ │ (Task │
│ Plane) │ │ Layer) │ │ Executor) │
└─────────────┘ └──────────────┘ └──────────────┘
# 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
#!/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}"
# 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"]
}'
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}")
npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow| Command | Description |
|---|---|
make docker-init |
Initialize Docker environment (first time) |
make docker-start |
Start DeerFlow services |
make docker-stop |
Stop DeerFlow services |
make docker-logs |
View all logs |
make docker-logs-frontend |
View frontend logs |
make docker-logs-gateway |
View gateway logs |
make docker-rebuild |
Rebuild Docker images |
make config |
Generate configuration files |
make check |
Verify prerequisites |
make install |
Install dependencies (local) |
make dev |
Run in development mode (local) |
| Issue | Solution |
|---|---|
| Docker permission denied | Run sudo usermod -aG docker $USER and re-login |
| API returns 401 | Check API key in .env file |
| Sandbox timeout | Increase timeout in config.yaml |
| Port 2026 already in use | Change ports in docker-compose-dev.yaml |
| Model not responding | Verify model API key and quota |
| Frontend hot-reload not working | Check pnpm is installed correctly |
# 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
⚠️ DeerFlow has high-privilege capabilities including system command execution. The team recommends:
iptablesFor go2apicli integration, ensure DeerFlow runs inside the sandbox with restricted network access.
Once DeerFlow is running, explore:
skills/custom/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! 🚀