DeerFlow logo
Agents Orchestration Frameworks · Academic Research

DeerFlow

DeerFlow is an open-source SuperAgent harness published under the MIT licence. It gives self-hosting teams a Python runtime where agents plan, research, write code and produce files across tasks that run from minutes to hours.

Beta Free plan Free API available Verified by Guidaio
Overview

What is DeerFlow?

DeerFlow is an open-source SuperAgent harness distributed under the MIT licence from the bytedance/deer-flow repository, with BytePlus credited as a partner on the home page. The project is deliberate about its vocabulary: not a framework, but a harness — an opinionated runtime that ships the infrastructure an agent needs rather than only the abstractions.

It comes in two inseparable layers. DeerFlow Harness is the Python SDK and runtime on which you build your own agent system. DeerFlow App is a reference application built on that runtime, self-hostable and complete with a browser workspace, thread management and artefact handling. One is the foundation; the other shows what a production-oriented assembly of it looks like.

The project began as a deep research agent, and that origin still shows. What changed is its status: research became one skill among many rather than the definition of the system, once teams started adapting it for data analysis, report generation, internal automation and operations workflows. The architecture followed, moving away from fixed multi-agent graphs towards a lead agent with middlewares and dynamically invoked subagents.

Seven concepts carry the design: harness, long-horizon agent, skill, sandbox, subagent, context engineering, memory and artefact. Context engineering deserves attention, since DeerFlow leans on summarisation, scoped context for subagents and the file system as external working memory to keep long tasks tractable.

Version 2.0, announced as a Release Candidate in an April 2026 blog post, adds long- and short-term memory, planning and sub-tasking that runs sequentially or in parallel, interchangeable skills and tools, a sandbox with a real file system, and multi-model support spanning Doubao, DeepSeek, OpenAI and Gemini. For isolation the documentation recommends AIO Sandbox, a single Docker container bundling browser, shell, file, MCP and VSCode Server.

The home page shows six worked examples: forecasting 2026 agent trends, generating a video from Pride and Prejudice, a Doraemon strip explaining MOE architecture, exploratory analysis of the Titanic dataset, deep research from a Y Combinator video, and a synthesis of Fei-Fei Li's podcast appearances. One caveat matters: the pip package is announced but not yet published.

What it does

  • Run multi-source deep research and return a structured report
  • Execute code and shell commands inside an isolated Docker sandbox
  • Read, write and edit files with ls, read_file, glob, grep, write_file, str_replace and bash
  • Delegate subtasks to subagents, running them sequentially or in parallel
  • Load task-specific skills on demand from /mnt/skills/
  • Connect external Model Context Protocol servers and expose their tools to the lead agent
  • Produce downloadable artefacts such as reports, charts, code, images and video
Audience

When to use DeerFlow / When not to

A quick filter to help you decide if DeerFlow is the right fit.

When to use DeerFlow

  • Engineering teams that want to build their own agent product on an existing runtime instead of starting from scratch
  • Organisations that require full self-hosting and keep control of infrastructure, data and configuration
  • Python developers who are comfortable with Docker, Kubernetes and YAML configuration files
  • Research, analysis and reporting workflows that span many steps and several hours
  • Teams standardising on the Model Context Protocol who need OAuth-capable MCP tooling

When not to use DeerFlow

  • Non-technical users looking for a ready-to-use hosted service, because no SaaS version exists
  • Anyone who needs the Python SDK today, since the deerflow package is still marked Coming Soon
  • Organisations that require a published privacy policy, terms of service or DPA before adoption
  • Mobile-first users, as there is no iOS or Android application
  • Buyers who need a stable release, because version 2.0 is still a Release Candidate
Get started

How to use DeerFlow

A typical end-to-end flow, from setup to results.

  1. Clone the deer-flow repository and place a config.yaml at its root
  2. Create a .env file with your model provider key, DEER_FLOW_ROOT and a strong BETTER_AUTH_SECRET of at least 32 characters
  3. Choose a sandbox provider: LocalSandboxProvider for single-user work, AioSandboxProvider under Docker for several users, or the Kubernetes provisioner for production
  4. Run make dev to start the Gateway API on port 8001, the Next.js frontend on port 3000 and nginx on port 2026
  5. Open the workspace at http://localhost:2026 and start a new thread
  6. Pick a model in the input bar, and switch on thinking mode if that model supports it
  7. Select a skill when you want the agent to follow a specific methodology, such as deep research
  8. Toggle Plan Mode for objectives of three steps or more, to get a live task list
  9. Attach PDFs, text files, spreadsheets or images; they land in /mnt/user-data/uploads/
  10. Collect results from the Artifacts panel, and check logs/gateway.log if something misbehaves
Quick read

Pros & Cons

Pros

  • MIT licence with complete source code and full self-hosting
  • No licence fee and no paid tier of any kind
  • Model portability across Doubao, DeepSeek, OpenAI, Gemini and any provider you configure
  • Search and extraction backends are swappable, and two of them need no API key
  • Native MCP support with OAuth and on-demand tool loading
  • Three documented deployment paths, from a laptop to Kubernetes
  • Documentation splits cleanly into a builder track and an operator track

Cons

  • The deerflow pip package is not published yet and is still marked Coming Soon
  • Version 2.0 is a Release Candidate rather than a stable release
  • No privacy policy, terms of service or legal notice anywhere on the site
  • No contact email address, so support runs through GitHub issues
  • No postal address and no named legal entity beyond a copyright line in the footer
  • No hosted service, which makes every deployment the user's responsibility
  • The Model providers reference page was empty when the site was reviewed
Pricing

Pricing & Plans

DeerFlow is free of charge. The software is distributed under the MIT licence and self-hosted, and the site publishes no pricing page, no paid tier and no monetary amount in any currency, so there is no lowest price point to report. The costs are indirect and fall entirely on the operator: model provider tokens, optional API keys for Tavily, Exa, InfoQuest, Firecrawl or Jina AI, and the Docker or Kubernetes infrastructure needed to run the application. DuckDuckGo search and anonymous Jina AI extraction operate without an API key.

Prices and plans listed above may evolve. Always check the official pricing page before subscribing.
Trust & Privacy

Data, GDPR & hosting

A consolidated view of how DeerFlow handles your data.

GDPR overview

There is no GDPR information of any kind on the site. A search across every collected page, in rendered text and in archived HTML alike, returned no occurrence of GDPR, RGPD or CCPA. No Data Processing Agreement is offered, no subprocessor list is published, no Article 27 EU representative is designated, no data protection officer is named and no privacy contact address exists. No SOC 2 or ISO 27001 certification is claimed. This silence is not automatically a compliance failure: DeerFlow is self-hosted software rather than a service, so the organisation that deploys it acts as controller and carries the obligations itself. European teams should plan on writing their own record of processing activities, and note that authentication is theirs to configure through BETTER_AUTH_SECRET.

Who owns the data?

No terms of service and no privacy policy are published on the site, so the project makes no contractual claim over user data at all. In practice, ownership follows the deployment. DeerFlow is self-hosted: conversation threads are written to backend/.deer-flow/threads/ on infrastructure the operator controls, and Docker deployments bind-mount that directory into the gateway container. Uploaded files sit in the thread sandbox under /mnt/user-data/uploads/. The organisation that installs DeerFlow therefore holds the data and also carries the responsibility a vendor agreement would normally allocate. Anyone who needs a written data-ownership commitment from the publisher will not find one here.

Reuse rights

Because no terms of service exist, the project neither restricts nor authorises what an operator does with the data its own deployment produces: nothing is written down. What the documentation does make clear is that data leaves the deployment as soon as external services are configured. Prompts and content are sent to whichever model provider the operator wires up through config.yaml and the .env file. Community tools add further recipients: Tavily, Exa, InfoQuest, Firecrawl and Jina AI all take operator-supplied API keys, while DuckDuckGo search and anonymous Jina AI extraction work without one. Uploaded PDFs are converted to Markdown before reaching the model. Each of those third parties applies its own terms, which the operator has to review separately.

Data retention & training

Retention summary
No retention policy is published. A search of every collected page, in text and in archived HTML, found no privacy policy, terms of service or legal notice, and therefore no stated duration, no anonymisation rule and no deletion procedure. Retention is decided by whoever runs the deployment. Conversation threads persist on disk in backend/.deer-flow/threads/ until that operator removes them, and artefacts are tracked in ThreadState.artifacts and survive page reloads. The only retention-adjacent warning in the documentation runs the other way: it cautions that recreating containers without a stable volume destroys thread data. Nothing in DeerFlow expires or deletes data automatically, so any retention schedule has to be designed and enforced by the organisation deploying it.

Hosting summary

DeerFlow hosts nothing on the user's behalf: it is self-hosted software, so the jurisdiction that applies is the one where the operator chooses to run it. Conversation threads are written to backend/.deer-flow/threads/, which Docker deployments bind-mount into the gateway container. The documentation recommends replacing that bind-mount with a named volume or a PersistentVolumeClaim in production, precisely because recreating containers otherwise destroys the data. Session files live in the sandbox under /mnt/user-data/uploads/ and generated outputs under /mnt/user-data/outputs/. No hosting country or region is declared anywhere on the site, and none could be, since the publisher operates none of it. For completeness, the marketing site itself resolves to 101.47.172.234, located in Singapore on AS150436, Byteplus Pte. Ltd. That address describes where the brochure is served and says nothing about where a user's data would sit. Operators who need a documented jurisdiction should treat it as a question they answer themselves when they choose a cluster.

Watch-outs

Things to keep in mind

Risks and trade-offs to weigh before adopting DeerFlow.

  • The documentation warns that BETTER_AUTH_SECRET ships with a publicly known default, so deploying without replacing it leaves authentication wide open
  • Thread data can be lost when containers are recreated if DEER_FLOW_ROOT is not a stable host path or the threads/ and skills/ mounts are wrong
  • Adding an MCP filesystem server is explicitly discouraged, because DeerFlow does not publish per-thread MCP roots and the path semantics can clash
  • Enabling allow_host_bash lets the agent run shell commands on the host itself, which should stay confined to trusted environments
  • LocalSandboxProvider offers little isolation and is intended for single-user, trusted workflows only
  • Displayed token totals can differ from your provider's bill because of retries, cached input tokens, reasoning tokens and internal calls
  • With no published retention policy, privacy contact or DPA, the operator inherits every governance question raised by an agent that reads files and browses the web
Setup

Setup & Integrations

Technical difficulty

Moderate to high, and unmistakably aimed at developers. The fastest route is make dev, which starts the services natively and serves the application on http://localhost:2026, but it still assumes a cloned repository, a config.yaml, a .env file and a model provider key. Docker Compose adds a container runtime to the prerequisites. Production means a Kubernetes provisioner, nginx configuration and persistent volumes. There is no installer, no hosted signup and, for now, no pip install path. Comfort with YAML, containers and the shell is required rather than optional.

Deployment

Web appAPI

Integrations

DuckDuckGo Tavily Exa InfoQuest Firecrawl Jina AI Docker Kubernetes Nginx LangChain LangGraph Model Context Protocol OpenAI DeepSeek Gemini Doubao SQLite

Supported languages

EnglishChinese
Company

Behind DeerFlow

Company name
DeerFlow
Founded
11/05/2025
Country of origin
🇨🇳 China
UBO
INFORMATION_NOT_FOUND
UBO country
INFORMATION_NOT_FOUND
Domain registrar country
🇨🇳 China
Official links

Resources

All the official URLs gathered for verification and reference.

FAQ

Frequently asked questions

Is DeerFlow free?
Yes. DeerFlow is distributed under the MIT licence and self-hosted, with no paid tier and no pricing page. The costs you will meet are indirect: model provider tokens, optional third-party API keys, and the infrastructure you run it on.
Is there a hosted version I can sign up for?
No. The workspace on the DeerFlow site is a demonstration only, and its settings panel reports that it is not available in demo mode. Every real deployment is self-hosted by the user.
How do I install it?
Three paths are documented: make dev for local development, Docker Compose for a production-like setup, and Kubernetes-managed sandboxes for production. In each case the application is served on http://localhost:2026 by default.
Can I install the Python SDK today?
Not yet. The package name will be deerflow and the documentation shows pip install deerflow, but the install page states that it is not released and marks it Coming Soon.
Which models does DeerFlow support?
The home page names Doubao, DeepSeek, OpenAI and Gemini among others. Models are declared in config.yaml, and users pick one per message from the model selector in the workspace.
Does DeerFlow support the Model Context Protocol?
Yes. MCP servers are declared in extensions_config.json with command, args, enabled and env fields. OAuth-protected servers are handled transparently, and configuration changes take effect without restarting the server.
What is a skill in DeerFlow?
A skill is a task-oriented capability package of instructions, workflows and supporting resources, loaded from /mnt/skills/ only when it is relevant. Deep research is one skill among several rather than the shape of the whole system.
Is generated code executed safely?
Code and shell commands run inside a Docker-based sandbox. Three providers are documented: LocalSandboxProvider for single-user trusted work, AioSandboxProvider for moderate multi-user isolation, and a Kubernetes provisioner for production.
Does the site publish a privacy policy or terms of service?
No. Neither exists, and no legal notice, postal address, contact email or GDPR statement appears anywhere on the site. As self-hosted software, the compliance obligations fall to the organisation that deploys it.
Is there a mobile app?
No. DeerFlow ships as a self-hosted web application with a Gateway API. No iOS or Android application is referenced anywhere on the site.
Conclusion

Should you pick DeerFlow?

DeerFlow is best understood as a runtime for long-horizon agents rather than a chat product. It assumes that useful work takes many steps, several tool calls and somewhere to park intermediate state, and it ships the sandbox, memory, skill and subagent machinery that assumption requires. For an engineering team that wants to build an agent system without rebuilding the infrastructure underneath it, that is a substantial head start.

The licence is the second argument. MIT, complete source, full self-hosting: no licence fee, no seat count and no vendor in a position to change the terms later. What you pay instead is operational, in model tokens, in third-party API keys where you pick paid backends, and in the Docker or Kubernetes footprint. That trade works well for organisations that already run infrastructure and want their data to stay inside it.

The reservations are just as clear. Version 2.0 is a Release Candidate and the Python package is announced but not yet installable, so anyone planning to depend on pip install deerflow is waiting on a date the site does not give. More awkward for a procurement conversation, the site publishes no privacy policy, no terms of service, no legal notice, no postal address and no contact email, and the footer names no legal entity. That is unremarkable for a GitHub project and difficult for a regulated buyer, because there is no document to hold anyone to.

The honest reading is that DeerFlow is a serious piece of agent infrastructure at an intermediate stage of maturity, aimed squarely at technical teams. If you can read Python, run containers and write your own compliance record, it repays the effort. If you were hoping to sign up and start typing, this is not it.