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.
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
Markdown
[](/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
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.
- English | [中文](README_zh.md) | [日本語](README_ja.md) | [Français](README_fr.md) | [Русский](README_ru.md) | [Português](README_pt.md) | [한국어](README_ko.md)
- [](backend/pyproject.toml)
- [](Makefile)
- [](LICENSE)
- <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>
- > 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! 💪🔥
- 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**.
- https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
- > [!NOTE]
- > **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.
- ## Official Website
- Learn more and see **real demos** on our [**official website**](https://deerflow.tech).
- The landing-page case studies open as allowlisted, read-only showcases without requiring a sign-in.
- ## Sister Projects
- <img width="446" height="280" alt="image" align="middle" src="https://github.com/user-attachments/assets/077edef4-d560-41af-bb0d-d0a5f14fcc20" />
- - [**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.
- ## Coding Plan from ByteDance Volcengine
- - We strongly recommend using Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5 to run DeerFlow
- - [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)
- - [中国大陆地区的开发者请点击这里](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
- ## InfoQuest
- 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)
- <a href="https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest" target="_blank">
- <img
- src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/hubseh7bsbps/20251208-160108.png" alt="InfoQuest_banner"
- />
- </a>
- ---
- ## One-Line Agent Setup
- If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence:
- ```text
- Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md
- ```
- 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.
- ## Quick Start
- ```bash
- git clone https://github.com/bytedance/deer-flow.git
- cd deer-flow
- make setup # interactive wizard: writes config.yaml and .env (about 2 minutes)
- ```
- Then start DeerFlow with Docker (recommended) or run it locally:
- ```bash
- # Docker
- make docker-init # pull the sandbox image (once, or when the image updates)
- make docker-start # start services
- ```
- ```bash
- # Local development
- make check # verifies Node.js 22+, pnpm, uv, nginx
- make install
- make dev
- ```
- The local commands use the pnpm version pinned in `frontend/package.json`. If a
- different global pnpm is on `PATH`, they use Corepack when available; otherwise
- they report the version mismatch before installing frontend dependencies.
- Run `make doctor` after setting model credentials. It reports obvious placeholder
- API keys as incomplete configuration; replace them with real keys before testing
- model calls.
- Open http://localhost:2026.
- - All configuration options, providers and manual setup: [Configuration](docs/guide/configuration.md)
- - Docker details, sizing, upgrades, startup modes and production deployment: [Running the Application](docs/guide/deployment.md)
- - Running on a server or exposing it beyond localhost: read the [Security Notice](docs/guide/security.md) first
- ## From Deep Research to Super Agent Harness
- 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.
- 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.
- So we 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 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.
- Use it as-is. Or tear it apart and make it yours.
- ## Guides
- Each guide is the full reference for its topic. Open the one you need.
- | Topic | Guide |
- | --- | --- |
- | Models, providers, `config.yaml`, environment variables | [Configuration](docs/guide/configuration.md) |
- | DeepSeek web search, thinking mode and citation excerpts | [DeepSeek Web Search](backend/docs/CONFIGURATION.md#deepseek-web-search) |
- | Docker, local development, upgrades, production deployment | [Running the Application](docs/guide/deployment.md) |
- | Sandbox modes, file system, uploads and outputs | [Sandbox](docs/guide/sandbox.md) |
- | boxd machines, bounded output copies and cleanup retries | [boxd sandbox provider](backend/packages/harness/deerflow/community/boxd_sandbox/README.md) |
- | Skills, built-in tools, script workflows, Claude Code integration | [Skills & Tools](docs/guide/skills-and-tools.md) |
- | MCP servers | [MCP Server](docs/guide/mcp.md) |
- | Sub-agents, task delegation and optional SQLite checkpoint history | [Sub-Agents](docs/guide/subagents.md), [Tool restrictions](docs/guide/subagents.md#tool-restrictions) |
- | Long-term memory | [Long-Term Memory](docs/guide/memory.md) |
- | Session goals, context compaction, task notes, evidence-based decisions | [Context, Goals and Agent Decisions](docs/guide/context.md) |
- | Private knowledge retrieval (RAGFlow) | [Private Knowledge Retrieval](docs/guide/knowledge-retrieval.md) |
- | Agentic browser control | [Agentic Browser Control](docs/guide/browser-control.md) |
- | Projects, instructions, document shelf | [Projects](docs/guide/projects.md) |
- | Scheduled tasks | [Scheduled Tasks](docs/guide/scheduled-tasks.md) |
- | Feishu, Slack, Telegram, Discord, DingTalk and other IM channels | [IM Channels](docs/guide/im-channels.md) |
- | File attachments, downloads and Office previews | [File Previews](docs/guide/file-previews.md) |
- | Token usage dashboard, workspace, chat archive | [Workspace UI](docs/guide/workspace.md) |
- | Terminal workbench | [Terminal Workbench (TUI)](docs/guide/tui.md) |
- | Personal access tokens, stream actions, embedded Python client | [API Access and Python Client](docs/guide/api-and-client.md) |
- | Trace correlation, LangSmith, Langfuse, Monocle | [Tracing and Observability](docs/guide/observability.md) |
- | Deployment risks, admin model, security recommendations | [Security Notice](docs/guide/security.md) |
- ## Recommended Models
- DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:
- - **Long context windows** (100k+ tokens) for deep research and multi-step tasks
- - **Reasoning capabilities** for adaptive planning and complex decomposition
- - **Multimodal inputs** for image understanding and video comprehension
- - **Strong tool-use** for reliable function calling and structured outputs
- ## More Documentation
- - [Install.md](Install.md) - Setup instructions written for coding agents
- - [Configuration Reference](backend/docs/CONFIGURATION.md) - Every `config.yaml` option
- - [Backend Architecture](backend/README.md) - Backend architecture and API reference
- - [Conversation Sharing](docs/guide/sharing.md) - Expiring read-only snapshots, artifact previews and workspace copies
- - [Architecture Overview](docs/ARCHITECTURE.md) - How the services fit together
- - [Contributing Guide](CONTRIBUTING.md) - Development environment, workflow and tests
- - [Changelog](CHANGELOG.md) - Release notes
- ## ⚠️ Security Notice
- 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).
- ## Contributing
- We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and guidelines.
- ## License
- This project is open source and available under the [MIT License](LICENSE).
- ## Acknowledgments
- 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.
- We would like to extend our sincere appreciation to the following projects for their invaluable contributions:
- - **[LangChain](https://github.com/langchain-ai/langchain)**: Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality.
- - **[LangGraph](https://github.com/langchain-ai/langgraph)**: Their innovative approach to multi-agent orchestration has been instrumental in enabling DeerFlow's sophisticated workflows.
- These projects exemplify the transformative power of open-source collaboration, and we are proud to build upon their foundations.
- ### Key Contributors
- A heartfelt thank you goes out to the core authors of `DeerFlow`, whose vision, passion, and dedication have brought this project to life:
- - **[Daniel Walnut](https://github.com/hetaoBackend/)**
- - **[Henry Li](https://github.com/magiccube/)**
- 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.
- ## Star History
- [](https://star-history.dera.page/#bytedance/deer-flow&Date)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.