Skip to content
Back to search

deer-flow

An open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bytedance/deer-flow with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bytedance/deer-flow'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bytedance-deer-flow/badge.svg)](/listings/bytedance-deer-flow)

HTML

<a href="/listings/bytedance-deer-flow"><img src="/api/listings/bytedance-deer-flow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Configuration

Operators can extend lead-agent, subagent, and DeerMem extraction prompts with literal prepend/append configuration without editing source templates. See [prompt overlays](backend/docs/CONFIGURATION.md#prompt-overlays).

Optional per-model [`request_admission`](backend/docs/CONFIGURATION.md#model-request-admission) paces requests to help stay within provider request-per-minute limits. It is disabled by default; see the linked guide to enable it.

For Google's official Gemini OpenAI-compatible endpoint, use the [Gemini reasoning profile](backend/docs/CONFIGURATION.md#gemini-via-googles-openai-compatible-endpoint).

1. **Clone the DeerFlow repository**

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

2. **Run the setup wizard**

From the project root directory (`deer-flow/`), run:

   make setup

This launches an interactive wizard that guides you through choosing an LLM provider, optional web search, and execution/safety preferences such as sandbox mode, bash access, and file-write tools. It generates a minimal `config.yaml` and writes your keys to `.env`. Takes about 2 minutes.

The wizard also lets you configure an optional web search provider, or skip it for now.

Jina, Browserless, and InfoQuest web fetches resolve relative links and image sources using the requested page URL (or a usable HTML base URL), so returned Markdown includes complete destinations. Link resolution preserves the surrounding HTML source, including malformed-page formatting.

Jina fetches support opt-in bounded retries via `max_retries` (default `0`) and `retry_budget_seconds` (default `30`) in the tool configuration. Retry waits are randomized within the time budget. Retries may increase upstream requests and cost; see [Jina fetch retries](backend/docs/CONFIGURATION.md#jina-fetch-retries).

Run `make doctor` at any time to verify your setup and get actionable fix hints. If you are opening a GitHub issue about a local setup or runtime problem, run `make support-bundle`. The command prints reporter next steps, writes a `*-issue-summary.md` file to paste into the issue, a `*-issue-draft.md` file for AI-assisted issue filing, and an optional evidence zip under `.deer-flow/support-bundles/`. If an AI assistant files the issue, start from the draft and replace every REQUIRED placeholder instead of inventing missing facts. Attach the zip only if a maintainer asks for it, or if the summary alone is not enough. Maintainers and AI triage tools can start with `triage.json`; the bundle includes redacted diagnostics and file manifests only, and does not include `.env`, raw conversation messages, or user file contents.

> **Advanced / manual configuration**: If you prefer to edit `config.yaml` directly, run `make config` instead to copy the full template. Optional dependency auto-detection accepts UTF-8 configuration files with or without a byte-order mark (BOM). See `config.example.yaml` for the complete reference including CLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, Responses API, subagent runtime caps such as `subagents.max_total_per_run`, and more.

Optional per-model pricing must use one currency across all priced models. DeerFlow disables Console cost estimates when currencies are mixed rather than presenting an invalid aggregate.

Administrators can also open **Settings → Models** to add, edit, test, and enable/disable shared OpenAI-compatible Chat Completions models without editing `config.yaml`. Enter a unique name, base URL, model ID, and optional API key; saving refreshes the chat model list. Connection testing sends a short streaming tool-call request and may incur provider charges. It does not save the draft or verify image support; set image support and token limits from provider documentation. Official DeepSeek models at `https://api.deepseek.com` or

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 186 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. English | [中文](README_zh.md) | [日本語](README_ja.md) | [Français](README_fr.md) | [Русский](README_ru.md) | [Português](README_pt.md) | [한국어](README_ko.md)
  2. [![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](backend/pyproject.toml)
  3. [![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](Makefile)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  5. <a href="https://trendshift.io/repositories/14699" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14699" alt="bytedance%2Fdeer-flow | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
  6. > On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥
  7. DeerFlow (**D**eep **E**xploration and **E**fficient **R**esearch **Flow**) is an open-source **super agent harness** that orchestrates **sub-agents**, **memory**, and **sandboxes** to do almost anything — powered by **extensible skills**.
  8. https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
  9. > [!NOTE]
  10. > **DeerFlow 2.0 is a ground-up rewrite.** It shares no code with v1. If you're looking for the original Deep Research framework, it's maintained on the [`1.x` branch](https://github.com/bytedance/deer-flow/tree/main-1.x) — contributions there are still welcome. Active development has moved to 2.0.
  11. ## Official Website
  12. Learn more and see **real demos** on our [**official website**](https://deerflow.tech).
  13. The landing-page case studies open as allowlisted, read-only showcases without requiring a sign-in.
  14. ## Sister Projects
  15. <img width="446" height="280" alt="image" align="middle" src="https://github.com/user-attachments/assets/077edef4-d560-41af-bb0d-d0a5f14fcc20" />
  16. - [**LLM Space**](https://github.com/deer-flow/llm-space) - Meet our secret weapon behind DeerFlow — one desktop tool to prototype agent ideas, inspect each harness step, replay failures, and benchmark performance.
  17. ## Coding Plan from ByteDance Volcengine
  18. - We strongly recommend using Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5 to run DeerFlow
  19. - [Learn more](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
  20. - [中国大陆地区的开发者请点击这里](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
  21. ## InfoQuest
  22. DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus — [InfoQuest (supports free online experience)](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest)
  23. <a href="https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest" target="_blank">
  24. <img
  25. src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/hubseh7bsbps/20251208-160108.png" alt="InfoQuest_banner"
  26. />
  27. </a>
  28. ---
  29. ## One-Line Agent Setup
  30. If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence:
  31. ```text
  32. Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md
  33. ```
  34. That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide.
  35. ## Quick Start
  36. ```bash
  37. git clone https://github.com/bytedance/deer-flow.git
  38. cd deer-flow
  39. make setup # interactive wizard: writes config.yaml and .env (about 2 minutes)
  40. ```
  41. Then start DeerFlow with Docker (recommended) or run it locally:
  42. ```bash
  43. # Docker
  44. make docker-init # pull the sandbox image (once, or when the image updates)
  45. make docker-start # start services
  46. ```
  47. ```bash
  48. # Local development
  49. make check # verifies Node.js 22+, pnpm, uv, nginx
  50. make install
  51. make dev
  52. ```
  53. The local commands use the pnpm version pinned in `frontend/package.json`. If a
  54. different global pnpm is on `PATH`, they use Corepack when available; otherwise
  55. they report the version mismatch before installing frontend dependencies.
  56. Run `make doctor` after setting model credentials. It reports obvious placeholder
  57. API keys as incomplete configuration; replace them with real keys before testing
  58. model calls.
  59. Open http://localhost:2026.
  60. - All configuration options, providers and manual setup: [Configuration](docs/guide/configuration.md)
  61. - Docker details, sizing, upgrades, startup modes and production deployment: [Running the Application](docs/guide/deployment.md)
  62. - Running on a server or exposing it beyond localhost: read the [Security Notice](docs/guide/security.md) first
  63. ## From Deep Research to Super Agent Harness
  64. DeerFlow started as a Deep Research framework — and the community ran with it. Since launch, developers have pushed it far beyond research: building data pipelines, generating slide decks, spinning up dashboards, automating content workflows. Things we never anticipated.
  65. That told us something important: DeerFlow wasn't just a research tool. It was a **harness** — a runtime that gives agents the infrastructure to actually get work done.
  66. So we rebuilt it from scratch.
  67. 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 out of the box: a filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.
  68. Use it as-is. Or tear it apart and make it yours.
  69. ## Guides
  70. Each guide is the full reference for its topic. Open the one you need.
  71. | Topic | Guide |
  72. | --- | --- |
  73. | Models, providers, `config.yaml`, environment variables | [Configuration](docs/guide/configuration.md) |
  74. | DeepSeek web search, thinking mode and citation excerpts | [DeepSeek Web Search](backend/docs/CONFIGURATION.md#deepseek-web-search) |
  75. | Docker, local development, upgrades, production deployment | [Running the Application](docs/guide/deployment.md) |
  76. | Sandbox modes, file system, uploads and outputs | [Sandbox](docs/guide/sandbox.md) |
  77. | boxd machines, bounded output copies and cleanup retries | [boxd sandbox provider](backend/packages/harness/deerflow/community/boxd_sandbox/README.md) |
  78. | Skills, built-in tools, script workflows, Claude Code integration | [Skills & Tools](docs/guide/skills-and-tools.md) |
  79. | MCP servers | [MCP Server](docs/guide/mcp.md) |
  80. | Sub-agents, task delegation and optional SQLite checkpoint history | [Sub-Agents](docs/guide/subagents.md), [Tool restrictions](docs/guide/subagents.md#tool-restrictions) |
  81. | Long-term memory | [Long-Term Memory](docs/guide/memory.md) |
  82. | Session goals, context compaction, task notes, evidence-based decisions | [Context, Goals and Agent Decisions](docs/guide/context.md) |
  83. | Private knowledge retrieval (RAGFlow) | [Private Knowledge Retrieval](docs/guide/knowledge-retrieval.md) |
  84. | Agentic browser control | [Agentic Browser Control](docs/guide/browser-control.md) |
  85. | Projects, instructions, document shelf | [Projects](docs/guide/projects.md) |
  86. | Scheduled tasks | [Scheduled Tasks](docs/guide/scheduled-tasks.md) |
  87. | Feishu, Slack, Telegram, Discord, DingTalk and other IM channels | [IM Channels](docs/guide/im-channels.md) |
  88. | File attachments, downloads and Office previews | [File Previews](docs/guide/file-previews.md) |
  89. | Token usage dashboard, workspace, chat archive | [Workspace UI](docs/guide/workspace.md) |
  90. | Terminal workbench | [Terminal Workbench (TUI)](docs/guide/tui.md) |
  91. | Personal access tokens, stream actions, embedded Python client | [API Access and Python Client](docs/guide/api-and-client.md) |
  92. | Trace correlation, LangSmith, Langfuse, Monocle | [Tracing and Observability](docs/guide/observability.md) |
  93. | Deployment risks, admin model, security recommendations | [Security Notice](docs/guide/security.md) |
  94. ## Recommended Models
  95. DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:
  96. - **Long context windows** (100k+ tokens) for deep research and multi-step tasks
  97. - **Reasoning capabilities** for adaptive planning and complex decomposition
  98. - **Multimodal inputs** for image understanding and video comprehension
  99. - **Strong tool-use** for reliable function calling and structured outputs
  100. ## More Documentation
  101. - [Install.md](Install.md) - Setup instructions written for coding agents
  102. - [Configuration Reference](backend/docs/CONFIGURATION.md) - Every `config.yaml` option
  103. - [Backend Architecture](backend/README.md) - Backend architecture and API reference
  104. - [Conversation Sharing](docs/guide/sharing.md) - Expiring read-only snapshots, artifact previews and workspace copies
  105. - [Architecture Overview](docs/ARCHITECTURE.md) - How the services fit together
  106. - [Contributing Guide](CONTRIBUTING.md) - Development environment, workflow and tests
  107. - [Changelog](CHANGELOG.md) - Release notes
  108. ## ⚠️ Security Notice
  109. DeerFlow can execute commands and read and write files. It is designed to run in a local trusted environment, and a Gateway admin account is equivalent to code execution on the host. Before you deploy it on a server or expose it to a network, read the full [Security Notice](docs/guide/security.md) and [SECURITY.md](SECURITY.md).
  110. ## Contributing
  111. We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and guidelines.
  112. ## License
  113. This project is open source and available under the [MIT License](LICENSE).
  114. ## Acknowledgments
  115. DeerFlow is built upon the incredible work of the open-source community. We are deeply grateful to all the projects and contributors whose efforts have made DeerFlow possible. Truly, we stand on the shoulders of giants.
  116. We would like to extend our sincere appreciation to the following projects for their invaluable contributions:
  117. - **[LangChain](https://github.com/langchain-ai/langchain)**: Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality.
  118. - **[LangGraph](https://github.com/langchain-ai/langgraph)**: Their innovative approach to multi-agent orchestration has been instrumental in enabling DeerFlow's sophisticated workflows.
  119. These projects exemplify the transformative power of open-source collaboration, and we are proud to build upon their foundations.
  120. ### Key Contributors
  121. A heartfelt thank you goes out to the core authors of `DeerFlow`, whose vision, passion, and dedication have brought this project to life:
  122. - **[Daniel Walnut](https://github.com/hetaoBackend/)**
  123. - **[Henry Li](https://github.com/magiccube/)**
  124. Your unwavering commitment and expertise have been the driving force behind DeerFlow's success. We are honored to have you at the helm of this journey.
  125. ## Star History
  126. [![Star History Chart](https://star-history.dera.page/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.dera.page/#bytedance/deer-flow&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.