This guide walks through installing DeerFlow, configuring your first model, and running the application for the first time. By the end of this page, you will have a working DeerFlow instance accessible at http://localhost:2026.
DeerFlow is a LangGraph-based AI super agent system with a full-stack architecture backend/pyproject.toml4 For detailed architecture information, see Architecture. For production deployment options, see Deployment.
DeerFlow requires the following tools installed on your system for local development.
| Tool | Minimum Version | Purpose |
|---|---|---|
| Node.js | 22+ | Frontend application runtime CONTRIBUTING.md159 |
| pnpm | Latest | Frontend package manager Makefile83 |
| uv | Latest | Python package manager and workspace orchestrator backend/pyproject.toml62 Makefile81 |
| Python | 3.12+ | Backend runtime backend/pyproject.toml6 |
| nginx | Latest | Unified reverse proxy entry point Makefile123 |
| Docker | Latest | Container runtime for sandbox and Docker-based dev Makefile141-142 |
Verify prerequisites:
This command runs scripts/doctor.py to ensure all required tools and configurations are available in your environment Makefile56-57
Sources: backend/pyproject.toml6-62 Makefile56-142 CONTRIBUTING.md159
This launches an interactive wizard (scripts/setup_wizard.py) that guides you through choosing an LLM provider, web search, and safety preferences Makefile53-54 It generates a minimal config.yaml and writes keys to .env README.md122-123
This command performs a full synchronization of the workspace Makefile79-87:
uv sync in the backend/ directory Makefile81pnpm install in the frontend/ directory Makefile83uv tool install pre-commit Makefile85-86Optional: Pre-pull Sandbox Image
If you plan to use container-based sandbox execution, pre-pull the execution image to speed up the first run Makefile98-99:
For a detailed walkthrough of the installation process, see Prerequisites and Installation.
Sources: Makefile53-99 README.md122-123 CONTRIBUTING.md20-28
DeerFlow requires at least one LLM model configured to function.
You can run make config to copy the template config.example.yaml to config.yaml Makefile68-69 DeerFlow supports environment variable substitution for values in config.yaml using keys from .env .env.example1-25
Example .env configuration .env.example1-25:
The config.yaml file defines the models and tools available to the agent. It supports various providers like OpenAI, Anthropic, Gemini, and DeepSeek backend/packages/harness/pyproject.toml17-20
For a full guide on model providers and tool setup, see Configuration Quickstart.
Sources: Makefile68-69 .env.example1-25 backend/packages/harness/pyproject.toml17-20
You can run DeerFlow either directly on your host machine or within a Docker-managed environment.
Runs services directly on your host with hot-reloading enabled for the Gateway and Frontend.
This command executes scripts/serve.sh --dev, which starts the following services Makefile102-104:
For production-grade Docker orchestration, use make up to build and start production services Makefile169-170
Sources: Makefile102-170 docker/docker-compose-dev.yaml86-142
This diagram maps user interactions to the specific code entities and service ports defined in the system.
Sources: docker/docker-compose.yaml29-122 docker/docker-compose-dev.yaml86-142
The following table bridges high-level concepts to their primary code definitions.
| Concept | Code Entity | Path |
|---|---|---|
| Gateway App | app | backend/uvicorn[standard]>=0.34.0 docker/docker-compose.yaml98 |
| Harness Core | deerflow-harness | backend/packages/harness/pyproject.toml2 |
| Unified CLI | Makefile | Makefile1-51 |
| Stream Bridge | DEER_FLOW_STREAM_BRIDGE_REDIS_URL | docker/docker-compose.yaml122 |
Sources: Makefile1-51 backend/packages/harness/pyproject.toml2 docker/docker-compose.yaml98-122
Once the services are running, verify the installation:
http://localhost:2026 in your browser.http://localhost:2026/api/docs.make docker-logs or looking in the logs/ directory Makefile133-153To shut down all processes:
This command executes scripts/serve.sh --stop to terminate background services Makefile126-127
Sources: Makefile126-153
Refresh this wiki