Skip to content
Get packs

Guide · Open source

How to use DeerFlow: install with Docker and run your first agent task

Updated · written with AI from the project's own documentation and checked against our catalogue data

DeerFlow is an open-source super agent harness from ByteDance. It runs a lead agent that can split work across sub-agents, keep long-term memory, and run code or tasks inside sandboxes, for jobs that may take minutes to hours. This guide walks through the prerequisites, the clone and Docker install path, and the configuration and security points the README asks you to review before you run it.

DeerFlowbytedance/deer-flow · ★ 84.9k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Python 3.12+, Node.js 22+, and Docker installed.
  2. 2Clone the repo. Run git clone https://github.com/bytedance/deer-flow.git to get the source.
  3. 3Read the Quick Start. Open the README's Quick Start and Configuration sections before running anything.
  4. 4Add your API keys. Configure your own LLM provider keys as described in the Configuration section.
  5. 5Run with Docker. Follow the recommended Docker option in the Quick Start to start the application.
  6. 6Review security. Read the Security Notice and recommendations before exposing any service.

What you need before you install DeerFlow

DeerFlow is a developer tool. The README lists Python 3.12 or newer, Node.js 22 or newer, and Docker, which it recommends. You also need your own LLM API keys, since the project expects you to configure your own model providers.

The README notes that setup involves configuration, Docker or local development, and API keys. If you want a ready-made chat app with no setup, DeerFlow is not that product.

  • Python 3.12+
  • Node.js 22+
  • Docker (recommended per the README)
  • Your own LLM API keys

Clone the DeerFlow repository

The first install step in the source is to clone the repository from GitHub. The project is MIT licensed and written in Python.

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

Install and run DeerFlow with Docker

The README lists Docker as the recommended path. After cloning, follow the Quick Start section in the repository for the Docker option, which covers configuration and running the application. The project's Install.md file is also referenced in the README as a guide for coding agents that bootstrap local development.

Configuration is part of the Quick Start. The README covers settings such as which model providers to use, and it has a section on using multiple providers. Read those sections in the repo before starting services.

  • Clone the repo, then open the Quick Start section in the README.
  • Choose the Docker option, which the README recommends.
  • Add your LLM API keys and provider settings as described in the Configuration section.
  • Start the application and confirm it runs before you give it real tasks.

Understand what DeerFlow does with tasks

DeerFlow combines sub-agents, memory, and sandboxes. The README describes the lead agent as able to delegate work to sub-agents, keep long-term memory, and execute code or tasks in sandboxes. It also describes extensibility through skills and tools.

The project is aimed at tasks that may take minutes to hours, such as research, coding, and content creation.

  • Sub-Agents: work is split across helper agents.
  • Long-Term Memory: context is kept across a long investigation.
  • Sandbox and File System: code and tasks run in isolated environments.
  • Skills and Tools: the harness is extended with new capabilities.

Review the security notice before you deploy

The README has a Security Notice that you should read before any deployment. It says that improper deployment may introduce security risks, and that the gateway admin role is equivalent to code execution.

For any security-sensitive setup, review the notice and its recommendations first. Do not expose the gateway without reading that section.

  • Read the Security Notice section in full.
  • Treat gateway admin access as code execution access.
  • Follow the Security Recommendations in the README.

What people use it for

  • Experimenting with multi-agent workflows on your own infrastructure
  • Running long, multi-step research that needs memory and sub-agents
  • Using DeerFlow as a reference agent harness alongside LangGraph or LangChain
  • Coding and content creation tasks that take minutes to hours

Frequently asked questions

Is DeerFlow free to use?

DeerFlow is released under the MIT licence, which the README states. You still need your own LLM API keys, and the source does not cover provider costs.

What do I need to install DeerFlow?

The README lists Python 3.12+, Node.js 22+, and Docker, which it recommends. You also need to configure your own LLM API keys.

How do I install DeerFlow?

Clone the repository with git clone https://github.com/bytedance/deer-flow.git, then follow the Quick Start section, using the Docker option the README recommends.

Is DeerFlow safe to run?

The README has a Security Notice saying improper deployment may introduce risks and that the gateway admin role is equivalent to code execution. Review that section before deploying.

How does DeerFlow compare to LangGraph or AutoGen?

The source lists LangGraph, AutoGen, CrewAI, and OpenHands as comparable projects. DeerFlow is positioned as a super agent harness with sub-agents, memory, and sandboxes. Check each project's docs to compare features for your use.

Can non-technical users use DeerFlow?

Not easily. The project is for developers and researchers comfortable with configuration, Docker or local development, and API keys. It is not a ready-to-use consumer app or a managed hosted service.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

DeerFlow suits developers and researchers who want to experiment with multi-agent, long-running workflows on their own infrastructure and are comfortable with API keys and Docker. If you need a managed hosted service, a polished consumer app, or a deployment you can run without reviewing security settings, pick a different tool.

Install options & downloads