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 ta

View source

🦌 DeerFlow - 2.0

English | 中文 | 日本語 | Français | Русский | Português | 한국어

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 (Deep Exploration and Efficient Research 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 — contributions there are still welcome. Active development has moved to 2.0.

Official Website

Learn more and see real demos on our official website. The landing-page case studies open as allowlisted, read-only showcases without requiring a sign-in.

Sister Projects

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
中国大陆地区的开发者请点击这里

InfoQuest

InfoQuest reader, web search, and image search use a 30-second HTTP connect/read inactivity timeout. The crawl timeout and navigation_timeout settings remain separate server-side options; they do not control the local HTTP timeout.

DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus — InfoQuest (supports free online experience)

🦌 DeerFlow - 2.0

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:

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

Configuration

With run_events.backend: db, caller-supplied ISO 8601 event timestamps are normalized to UTC before storage, preserving their instant when SQLite drops timezone information. Timestamps without an offset are treated as UTC. Previously stored timestamps are not rewritten.

Run event streams include run.terminal for the owning worker's confirmed final Run status, while run.end continues to describe each root graph completion. Terminal publication is best effort; event persistence failure does not undo the Run outcome or prevent stream completion. Recovery with built-in SQL Run and Event stores sharing an engine uses one pooled connection for each guarded event write, so it can publish with only one pool slot available. See Run Event Stream.

Operators can extend lead-agent, subagent, and DeerMem extraction prompts with literal prepend/append configuration without editing source templates. See prompt overlays.

Optional per-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. Enabling it disables exposed SDK retries and the Claude and Codex adapters' internal retry loops so middleware retries pass through request admission again. Middleware retries also cover HTTP 529 overload responses. A warning identifies retry_max_attempts values overridden by admission.

For Google's official Gemini OpenAI-compatible endpoint, use the Gemini reasoning profile.

For MindIE XML tool calls, see the argument parsing and newline compatibility guide. Both synchronous and asynchronous streams retain this compatibility: tool-enabled streams simulate chunks from a non-streaming response, while no-tool streams stay native. Newline compatibility preserves literal escapes inside backtick and tilde code fences, including unclosed fences, in complete and streamed replies.

Clone the DeerFlow repository

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

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.

Brave web search preserves valid entries in mixed result lists. Malformed response containers or lists containing no usable entries return a structured format error; missing, null, or empty results keep the existing "No results found" response. Format errors also log the malformed container's path and type, or the absence of usable result objects, without including search queries, credentials, or payload values.

GroundRoute web search and fetch contain malformed HTTP-success payloads the same way: a non-object payload, a results container that is not a list, or a non-empty list with no object entries returns the provider's format error, while non-object entries in an otherwise valid list are skipped in order. Missing, null, or empty results keep the existing "No results found" response.

DuckDuckGo web search distinguishes execution failures from empty results: rate limits, timeouts, blocked requests, client-setup failures, SDK errors, and a missing ddgs dependency return a structured DuckDuckGo search failed: ... error instead of "No results found", while a genuinely empty result set keeps the existing "No results found" response. The structured error text lets the harness classify an outage as transient or a configuration problem instead of a query that matched nothing.

Tavily web search and fetch contain malformed HTTP-success payloads the same way: a non-object payload, or a results/failed_results container that is not a list, returns the provider's format error, and non-object entries in an otherwise valid list are skipped in order. Missing, null, or empty results keep the existing response ([] for search, Error: No results found for fetch); missing or null search fields (title, url, content) normalize to empty text, and a non-string fetch raw_content is coerced to text before the truncation limit.

Sofya web search and fetch contain malformed HTTP-success payloads the same way: a non-object payload, a results container that is not a list, or a non-empty list with no object entries returns the provider's format error, while non-object entries in an otherwise valid list are skipped in order. Missing, null, or empty results keep the existing "No results found" response.

Serper web and image search preserve valid entries in mixed result lists. A malformed organic/images container, or a non-empty list holding no object entries, returns Serper's format error; missing, null, or empty containers keep the existing "No results found" / "No images found" response. Format errors log the container field name only, without queries, credentials, or payload values.

Unbrowse web fetch preserves the extracted text but prefixes a warning when the target page's HTTP status is 400–599, even when the scraping service itself returns a successful response. Empty-page errors retain that status too. Both messages include up to 500 characters of the reported final URL after removing any username and password; final URLs that cannot be parsed as HTTP(S) URLs with a host are omitted.

Tencent Cloud WSA web search contains malformed HTTP-success payloads the same way: a Pages container that is not a list, or a non-empty container holding no usable page, returns the provider's format error, while malformed page entries in an otherwise valid container are skipped so the valid rows survive. Missing, null, or empty Pages keep the existing "No results found" response.

Serply web search contains malformed HTTP-success payloads the same way in every vertical: a results/entries/articles container that is not a list, or a non-empty list with no object entries, returns the provider's format error, while non-object entries in an otherwise valid list are skipped in order. Missing, null, or empty containers keep the existing "No results found" response.

SearXNG web search contains malformed HTTP-success payloads the same way: a payload that is not an object, a body that is not JSON, a results container that is not a list, or a non-empty list holding no object entries returns the provider's format error, while non-object entries in an otherwise valid page are skipped in order, each skip logged with its entry position, so the valid rows survive and provider-side drift leaves a trace. Missing, null, or empty results keep the existing empty result ([]). This matters most for a self-hosted instance: one behind a reverse proxy or captive portal answers an HTML or plain-text error page with HTTP 200, and reading that as an empty search ends a research loop as "no hits".

InfoQuest web and image search contain malformed HTTP-success payloads the same way: a search_result envelope that is not an object, or an organic/top_stories.items/images_results container that is not a list or that holds no usable entry, returns the provider's format error, while malformed entries in an otherwise valid payload are skipped so the usable rows survive. Missing, null, or empty containers keep the existing empty result. Format errors log the container or entry position only, without queries or payload values.

InfoQuest web and image search screen result URLs through the shared public-URL policy and omit rejected rows. Responses without the required search_result envelope return a format error instead of exposing the raw provider payload.

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.

Self-hosted Browserless, Crawl4AI, Firecrawl, and fastCRW fetch backends require outbound isolation from private, loopback, link-local, and cloud-metadata networks before setting network_isolation_confirmed: true on each tool. DeerFlow rejects private or unverifiable backends by default because those services handle redirects, DNS resolution, and subresources themselves. allow_private_addresses permits intentional internal target URLs and does not bypass the backend check. See delegated fetch deployment; make doctor reports backend configurations that would be refused.

Jina fetches support opt-in bounded retries via max_retries (default 0) and retry_budget_seconds (default 30) in the tool configuration. Valid Retry-After hints set a minimum wait for HTTP 429/503; 429 without a valid hint stays terminal. Hints that cannot fit the remaining budget stop retries. Local backoff remains randomized. Retries may increase upstream requests and cost; see Jina fetch retries.

Jina also accepts an opt-in max_response_bytes tool setting (positive integer; omitted/null disables it). It stops oversized decoded responses before extraction, with no partial success or retry. This leaves the 4096-character output cap unchanged and does not bound HTTPX decompressor allocations or wire bandwidth; see response budget.

Jina can also bound concurrent HTTP attempts and FIFO waiting with the opt-in request_admission tool extra. One immutable budget is shared across clients and agent threads in each process; replicas have independent budgets. See Jina request admission.

Run make doctor at any time to verify your setup and get actionable fix hints. The setup wizard and health check support legacy terminal encodings, including Windows cp936, replacing unsupported characters so both commands can finish. 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. Subprocess diagnostics are captured as UTF-8, with Python helpers emitting UTF-8 even on non-UTF-8 hosts and escaping unencodable characters. Thread manifests follow the local launcher's runtime paths: checkout .env values override shell exports, and a project-root override alone still uses backend/.deer-flow first. Simple variable references such as DEER_FLOW_HOME="$PWD/backend/.deer-flow" use the checkout as PWD; single-quoted references remain literal. If the checkout .env cannot be read or decoded as UTF-8, thread diagnostics retain shell exports and default storage paths. For standalone Gateway launches using backend/.env or DEER_FLOW_ENV_FILE, export the effective DEER_FLOW_HOME when collecting the bundle and ensure the checkout .env does not override it. Doctor's internal tool probes also decode UTF-8 with replacement for invalid bytes so the remaining diagnostic output stays available.

When a thread manifest is requested, a nonempty DEER_FLOW_HOME selects the runtime data directory instead of stale checkout data. External data paths appear as {DEER_FLOW_HOME} in the report; file contents remain excluded. Runtime path settings also come from the checkout .env, with shell exports taking precedence. Relative paths resolve from the checkout as in make dev. Without an explicit home, a configured DEER_FLOW_PROJECT_ROOT selects its .deer-flow directory; external paths use that variable name in the report.

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). It checks an existing DEER_FLOW_CONFIG_PATH first, then DEER_FLOW_PROJECT_ROOT/config.yaml, before the checkout's default locations. Local startup also accepts the project-root configuration when the checkout has no config.yaml. 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. For older runs without a per-model usage breakdown, Console attributes the recorded total and input token counts to the run's model.

Administrators can open Settings → Models to select a provider and enter only its API Key and model ID. Endpoints, authentication and adapters are backend presets for OpenAI, Anthropic, DeepSeek, Alibaba Cloud Bailian/Qwen, Volcengine/Doubao, Moonshot/Kimi, Zhipu/Z.AI and MiniMax. Region and plan-specific entries are explicitly distinguished. Arbitrary model IDs are accepted; internal names are generated automatically and remain stable when a model ID changes. Newly saved models are enabled and immediately refresh existing chat and Agent model selectors, without editing YAML or restarting the Gateway.

Custom OpenAI-compatible still supports existing/custom base URLs and unauthenticated endpoints. Advanced settings retains display name, token limits and vision overrides; unknown IDs do not receive invented capabilities. Leave the key blank on edit to retain it for the same connection. Switching provider or custom endpoint requires a new key, and preset models must be disabled before clearing their key. YAML models remain read-only.

Connection testing uses the same model factory and protocol as chat, sends a bounded streaming tool-call request and never saves the draft. It may incur provider charges and does not verify every agent, vision or thinking workflow. Official DeepSeek custom endpoints retain their existing adapter; a proxy does not become DeepSeek merely because of its model ID. See the Web model registration reference for presets, compatibility, extension instructions and backup requirements.

DeepSeek regression tests run offline with the normal backend suite. To verify the real provider explicitly, set DEEPSEEK_TEST_API_KEY in your environment and run from backend/:
```
DEER_FLOW_RUN_LIVE_TESTS=1 uv run --no-sync pytest tests/test_managed_deepseek_live.py -q
```
These opt-in tests send short requests to DeepSeek and may incur charges; they use temporary state, never save credentials to the deployment catalog, and are skipped in CI. DEEPSEEK_TEST_MODEL optionally selects a different DeepSeek model ID (default: deepseek-flash). The same tests can be run on unfixed and fixed revisions; success is always the expected result.

YAML models remain read-only in this page and take precedence on name conflicts. Managed models are appended after YAML models; edits apply to new configuration snapshots, while active runs retain their existing snapshot. Disabling a model removes it from future selection/resolution, so update any custom-agent or scheduled task definitions that explicitly reference it before disabling it. Managed models are shared by the deployment, not personal API-key profiles, and remain subject to the existing model authorization policy.

The encrypted catalog and a generated local encryption key are stored in $DEER_FLOW_HOME/managed-models/ (default .deer-flow/managed-models/). Persist and back up the whole directory, restrict filesystem access, and share it across Gateway workers/replicas that should use the same catalog. The local key is protected by filesystem permissions; encryption does not protect against someone who can read both files. Losing the key requires restoring the backup. Reads and writes fail if the catalog cannot be decrypted, rather than replacing it. This storage is independent of the SQL backend and works with read-only YAML mounts.

When several models are configured, open either model picker and use the star beside a model to favorite it. Favorites appear first in both the main chat and Side Chat pickers without changing either chat's selected or default model. They are stored for the signed-in user in the current browser, so they do not sync to another browser or device and do not require a startup setting. The compact favorites picker intentionally omits search and only adds favorite ordering to the two-line model list.
Manual model configuration examples
```
models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY

  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

  - name: opper-claude-sonnet-4-6
    display_name: Claude Sonnet 4.6 (Opper)
    use: langchain_openai:ChatOpenAI
    model: claude-sonnet-4-6
    api_key: $OPPER_API_KEY
    base_url: https://api.opper.ai/v3/compat

  - name: api-route-gpt-6.1-sol
    display_name: GPT 6.1 Sol (API Route)
    use: langchain_openai:ChatOpenAI
    model: gpt-6.1-sol
    api_key: $API_ROUTE_API_KEY
    base_url: https://global.api-route.com/v1

  - name: gpt-5-responses
    display_name: GPT-5 (Responses API)
    use: langchain_openai:ChatOpenAI
    model: gpt-5
    api_key: $OPENAI_API_KEY
    use_responses_api: true
    output_version: responses/v1

  - name: qwen3-32b-vllm
    display_name: Qwen3 32B (vLLM)
    use: deerflow.models.vllm_provider:VllmChatModel
    model: Qwen/Qwen3-32B
    api_key: $VLLM_API_KEY
    base_url: http://localhost:8000/v1
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        chat_template_kwargs:
          enable_thinking: true
```
OpenRouter and similar OpenAI-compatible gateways should be configured with langchain_openai:ChatOpenAI plus base_url. If you prefer a provider-specific environment variable name, point api_key at that variable explicitly (for example api_key: $OPENROUTER_API_KEY).

API Route is also available in the setup wizard. It saves your key as API_ROUTE_API_KEY and uses the Chat Completions endpoint above. Model availability depends on your key's group and permissions; check the authenticated GET https://global.api-route.com/v1/models catalog before replacing the model in config.yaml, and use its returned ID unchanged without an upstream provider prefix.

The write_file tool's output-budget hint uses the active model's effective max_tokens. Missing or unusable limits, including YAML .inf, -.inf, .nan, and values too large for the character estimate, omit this hint without failing tool assembly; provider-specific model validation still applies.

To route OpenAI models through /v1/responses, keep using langchain_openai:ChatOpenAI and set use_responses_api: true with output_version: responses/v1.

The lead agent also recognizes Responses output-token caps (status: incomplete with incomplete_details.reason: max_output_tokens), including streaming responses. It suppresses tool execution, removes the suppressed calls from later model requests, and preserves text and reasoning. A capped tool-call response includes a visible notice; other incomplete reasons retain their existing handling.

When thinking is disabled on a legacy profile, blank extra_body, thinking, and nested extra_body.thinking keys in a when_thinking_enabled template are treated as absent during dialect inference. When thinking is enabled, template values are forwarded as configured.

Models whose provider contract differs from DeerFlow's generic thinking/effort assumptions can declare a per-model mapping-valued reasoning: block (thinking unsupported/optional/required, the accepted effort values with aliases and a default, the payload dialect, and the reasoning-history requirement). The setup wizard's Z.AI GLM-5.3-Flash profile uses it: thinking stays on for every foreground and background call, and the effort selector offers the model's own low/high/max levels. Ollama's existing boolean reasoning: true remains a native provider setting and is forwarded to ChatOllama. When migrating a profile to a custom effort path, remove any old reasoning_effort setting from the profile and thinking templates; configuration validation rejects the leftover key. The chat UI drops a remembered provider-specific effort when switching to a legacy model that does not advertise it. Profiles without the block keep their existing provider behavior. See config.example.yaml for the shape and the equivalent manual configuration.

For vLLM 0.19.0, use deerflow.models.vllm_provider:VllmChatModel. For Qwen-style reasoning models, DeerFlow toggles reasoning with extra_body.chat_template_kwargs.enable_thinking and preserves vLLM's non-standard reasoning field across multi-turn tool-call conversations. Legacy thinking configs are normalized automatically for backward compatibility, without modifying model defaults or caller-owned extra_body dictionaries; a reused dictionary can change the legacy switch between requests. If the endpoint reports a cumulative usage snapshot on every streaming chunk, set cumulative_stream_usage: true so DeerFlow converts those snapshots into per-chunk deltas; the option is disabled by default and leaves usage unchanged when a stable completion id is unavailable. Reasoning models may also require the server to be started with --reasoning-parser .... If your local vLLM deployment accepts any non-empty API key, you can still set VLLM_API_KEY to a placeholder value.

When prompt caching is enabled for a model configured with deerflow.models.claude_provider:ClaudeChatModel, DeerFlow preserves thinking and redacted-thinking history without placing cache breakpoints directly on those blocks. Extended-thinking tool follow-ups can keep using prompt caching.

CLI-backed provider examples:
```
models:
  - name: gpt-5.4
    display_name: GPT-5.4 (Codex CLI)
    use: deerflow.models.openai_codex_provider:CodexChatModel
    model: gpt-5.4
    supports_thinking: true
    supports_reasoning_effort: true

  - name: claude-sonnet-4.6
    display_name: Claude Sonnet 4.6 (Claude Code OAuth)
    use: deerflow.models.claude_provider:ClaudeChatModel
    model: claude-sonnet-4-6
    max_tokens: 4096
    supports_thinking: true
```
ClaudeChatModel normalizes manual extended-thinking budgets when auto_thinking_budget: true (the default). An omitted or null budget gets 80% of max_tokens, with a minimum of 1024 tokens. Explicit budgets must be integers of at least 1024 and, for ordinary thinking, strictly below max_tokens; output limits of 1024 or less fail locally. For supported manual interleaved thinking, configure tools and betas: ["interleaved-thinking-2025-05-14"]: the thinking budget may equal or exceed the positive output limit. See Anthropic's interleaved-thinking rules for supported models. auto_thinking_budget: false bypasses this normalization and validation; disabled and adaptive thinking are unchanged.
- Codex CLI reads ~/.codex/auth.json
- Codex function tools preserve explicit strict: true or strict: false in wrapped or flat dictionary definitions. Missing or null settings keep the provider default. bind_tools applies the same conversion to dictionaries and BaseTool schemas.
- Codex honors tool_choice in bind_tools and direct calls: auto, none, required, or a function name/selection. any and True mean required; None and False keep the provider default. Per-call choices override the bound policy. Bound choices are validated when binding; direct calls and overrides are validated before HTTP. required needs at least one function tool, and named selections must match a supplied function. auto and none also work without tools.
- Completed Codex responses still return their text and tool calls when token usage is null, omitted, or empty; usage metadata remains unavailable.
- The Codex model provider returns completed responses without waiting for the SSE connection to close. Failed or incomplete responses report the provider's error or reason; partial output is not returned as a successful answer. Non-object error details are reported as text.
- ClaudeChatModel honors integer-second and HTTP-date Retry-After hints in its provider retry loop. Dates use UTC; past dates retry immediately, while invalid hints or delays beyond 24 hours retain local backoff.
- Claude Code accepts CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_CREDENTIALS_PATH, or ~/.claude/.credentials.json
- CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR accepts a UTF-8 token handoff and reuses it for later model instances in the same process. Undecodable handoffs are skipped so Claude Code can still try its override or default credentials file.
- CLI credential JSON files accept UTF-8 with or without a BOM, independently of the host locale. make doctor accepts the same files when checking CLI authentication. Invalid text encoding is treated as an unreadable source; Claude Code can still try its default file after an invalid override.
- ACP agent entries are separate from model providers — if you configure acp_agents.codex, point it at a Codex ACP adapter such as npx -y @zed-industries/codex-acp
- A bare or absolute ACP agent command is resolved before the agent starts, so npm-installed launchers work on Windows too: npx or mcode is spawned as its npx.cmd/mcode.cmd shim instead of failing with a command-not-found error, and an absolute path such as C:\Users\me\AppData\Roaming\npm\mcode resolves to the mcode.cmd shim beside npm's extensionless shell script instead of failing with WinError 193. The lookup uses the PATH the agent subprocess will actually see (acp_agents.<name>.env.PATH when set, otherwise the Gateway's) and hands the spawn an absolute path, so a relative PATH entry cannot be re-interpreted inside the agent's own workspace. A relative command (for example bin/mcode) is used as configured, and a command that cannot be resolved is still reported with the install guidance below.
- Each ACP agent's timeout_seconds (default: 1800) is one shared budget for initialization, session creation, and the prompt, starting after the subprocess launches. On timeout, DeerFlow aborts the invocation and closes the subprocess before returning an error. Workspace/MCP preparation and subprocess cleanup are outside this budget. A TimeoutError raised by the SDK before this deadline expires retains its own error message.
- If an ACP agent exits before answering (for example because it is not authenticated or a configured argument is wrong), DeerFlow reports its exit code within a few seconds instead of waiting for timeout_seconds, and records the end of the agent's stderr in the Gateway log. Agent stderr is read continuously, so an agent that logs heavily cannot stall on a full pipe.
- MiniMax Code speaks ACP directly. Install and authenticate it, then add it as an ACP agent:
```
npm install --global @minimax-ai/code
mcode login
```
```
acp_agents:
  mcode:
    command: mcode
    args: ["acp"]
    description: MiniMax Code for implementation, refactoring, debugging, and repository tasks
    auto_approve_permissions: false
```
mcode must be on the Gateway process's PATH; installing it only on the Docker host does not make it available inside the Gateway container. DeerFlow invokes it through invoke_acp_agent in a per-thread ACP workspace and forwards enabled MCP servers. Keep auto_approve_permissions: false for untrusted tasks; enable it only when mcode must edit files or run commands and you trust the task.
- On macOS, export Claude Code auth explicitly if needed:
```
eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
```
The exporter rejects malformed credential containers and non-string or blank access tokens before printing a token, emitting a shell export, or writing a credentials file. Valid tokens are exported unchanged, and file exports preserve the full credential container.

API keys can also be set manually in .env (recommended) or exported in your shell:
```
OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key
```

For an explicit backend dotenv file, export DEER_FLOW_ENV_FILE before startup, alongside DEER_FLOW_CONFIG_PATH if needed. For example, from backend/:

DEER_FLOW_ENV_FILE=/srv/deer-flow/stage.env DEER_FLOW_CONFIG_PATH=/srv/deer-flow/stage.yaml make gateway

Relative dotenv paths use the backend process working directory; absolute paths work regardless of that directory. Existing process variables win. An unset selector preserves default dotenv discovery; a specified empty, missing, non-file or unreadable path fails startup. Explicit selection also fails when PYTHON_DOTENV_DISABLED disables dotenv loading. Restart after changing the file. This selects backend dotenv input only: shell launchers, Docker Compose and the frontend retain their own environment loading. Values they already export win. It does not select ENV profiles or isolate databases, storage or tenants. See backend dotenv selection.

Custom blob storage backends accept blob_storage.backend: module.Class or module:Class, including a single .py module importable by the Gateway. The selected class must implement BlobStore; backend options go under blob_storage.backend_config. See blob storage.

Running the Application

Deployment Sizing

Use the table below as a practical starting point when choosing how to run DeerFlow:

Deployment target	Starting point	Recommended	Notes
Local evaluation / `make dev`	4 vCPU, 8 GB RAM, 20 GB free SSD	8 vCPU, 16 GB RAM	Good for one developer or one light session with hosted model APIs. `2 vCPU / 4 GB` is usually not enough.
Docker development / `make docker-start`	4 vCPU, 8 GB RAM, 25 GB free SSD	8 vCPU, 16 GB RAM	Image builds, bind mounts, and sandbox containers need more headroom than pure local dev.
Long-running server / `make up`	8 vCPU, 16 GB RAM, 40 GB free SSD	16 vCPU, 32 GB RAM	Preferred for shared use, multi-agent runs, report generation, or heavier sandbox workloads.

These numbers cover DeerFlow itself. If you also host a local LLM, size that service separately.
Linux plus Docker is the recommended deployment target for a persistent server. macOS and Windows are best treated as development or evaluation environments.
If CPU or memory usage stays pinned, reduce concurrent runs first, then move to the next sizing tier.

Option 1: Docker (Recommended)

Requires Docker Desktop / Docker Engine and Docker Compose v2.24+ (docker compose version). Older Compose clients cannot parse the optional env_file syntax in docker/docker-compose.yaml and docker/docker-compose-dev.yaml.

Development (hot-reload, source mounts):

make docker-init    # Pull sandbox image (only once or when image updates)
make docker-start   # Start services (auto-detects sandbox mode from config.yaml)
make docker-logs    # View logs

make docker-start starts provisioner only when config.yaml uses provisioner mode (sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider with provisioner_url). Direct Compose users can add --profile provisioner to the dev command for the same mode; the default stack does not require Kubernetes. With USERDATA_PVC_NAME, sandbox data, extra mounts and Lark broker credentials share one user-data volume with separate subPath mounts, avoiding duplicate references to the same claim on NFS CSI drivers.

Docker builds use the upstream uv registry by default. The gateway image installs with uv sync --locked, and uv.lock pins https://pypi.org/simple, so UV_INDEX_URL has to keep that value: exporting a mirror such as https://pypi.tuna.tsinghua.edu.cn/simple fails the build with The lockfile at `uv.lock` needs to be updated, but `--locked` was provided (reproduce in an already-synced environment with cd backend && UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --locked --check; if the environment itself is stale, --check reports that instead for either index, so use uv lock --check to see it without syncing). Installing from a mirror requires regenerating the lock or dropping --locked, and both change what the image installs, so keep the default index for a checkout you intend to contribute back. NPM_REGISTRY=https://registry.npmmirror.com is independent of this: it applies to the frontend image's pnpm install and to the gateway image's Lark CLI install (@larksuite/cli, which backend/Dockerfile installs with npm).

Local AIO sandbox control traffic is always direct: loopback/private addresses, single-label cluster hosts, and Docker/Podman internal hostnames do not inherit HTTP_PROXY or HTTPS_PROXY. External sandbox FQDNs and public IPs still honor environment proxy settings.

After native runtime shutdown and MCP teardown, Gateway closes an initialized sandbox provider, including AIO sandboxes first created by a worker-thread tool call. It does not start an unused sandbox provider solely for cleanup.

Backend processes automatically pick up config.yaml changes on the next config access, so model metadata updates do not require a manual restart during development.

Gateway runs use the top-level recursion_limit in config.yaml when an API request does not provide one. The default is 100; valid per-request values take precedence, and max_recursion_limit (default 1000) caps both. Changes apply to the next run without restarting the Gateway. This top-level setting applies to Gateway API and IM channel runs. A recursion_limit in an IM channel's session.config takes precedence, and GitHub channel runs keep their own floor. Embedded DeerFlowClient runs retain their own defaults and per-call override paths.

A custom frontend can add an optional context.client to a Gateway run request: a client name, capabilities such as artifacts or charts, and display preferences. DeerFlow sanitizes it and passes the values to the agent as untrusted, request-scoped hints, so skills can pick an output shape the client can show. It is never an authorization or identity signal. See Create Run. Client hints are omitted from stored run configuration and must be sent again for each run; later runs, including server-started tasks, do not inherit them. The checkpoint storage settings database.checkpoint_channel_mode and database.checkpoint_delta.snapshot_frequency (default 10) are exceptions: both are frozen when the process first builds an agent (including through DeerFlowClient) and require a process restart to change safely.

In delta mode, a run selecting an older checkpoint reports an error before rewriting state if either the selected checkpoint or the current head has pending tool execution. For Command(resume=...), other pending graph nodes also prevent the rewrite, except for the synthetic input entry node. Resume pending work from the latest checkpoint; to regenerate completed work, submit new input there. Full-mode resumes and ordinary replay without pending execution keep their existing behavior.

The optional database.checkpoint_cache section (delta channel mode only) caches materialized checkpoint histories: type is memory (default) or redis, and max_entries: 0 disables the cache. The redis backend is Gateway/async-only; the sync TUI/embedded path supports memory only. The cache is performance-only — results are identical with it disabled — so it is never frozen and workers sharing one checkpoint database may safely run different cache settings. Returned state snapshots have independent nested values, so editing one cannot change later checkpoint reads. Redis thread cleanup treats a configured key_prefix as literal text, including glob metacharacters, so deletion stays within that namespace and thread. Redis rejects malformed write records on ingestion; malformed or wrong-channel cached histories are rebuilt in full from authoritative checkpoints. Seeds and write values remain opaque to the cache: these checks do not validate schema-specific state contents. Checkpoint reads, valid neighboring writes and optional-cache cleanup continue even if a warning handler fails.

Gateway checkpoint cleanup runs when the next run wins durable same-thread admission, before its first checkpoint read. It checks only the root head and its parent, removes at most one metadata-only duration leaf without pending writes, and preserves explicit checkpoint selections and delta replay state. See checkpoint operations for the retention constraints.

[!TIP] On Linux, if Docker-based commands fail with permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, add your user to the docker group and re-login before retrying. See CONTRIBUTING.md for the full fix.

Production (builds images locally, mounts runtime config and data):

make up     # Build images and start all production services
make down   # Stop and remove containers

Access: http://localhost:2026

make up waits for the Gateway /health endpoint before reporting success. If the Gateway does not become healthy within the startup window, deployment exits non-zero and prints the container status plus recent Gateway logs. The production image starts from its already-built environment and never resolves or installs Python dependencies at container startup.

If make up reports an unwritable runtime home or an unreadable persisted secret after make docker-start, run the printed sudo chown -R <uid>:<gid> '<home>' recovery command and retry. The check honors secret overrides from the shell or .env, accepts readable read-only secret files, and leaves make down available without reading or generating secrets.

Production Docker commands can select a root dotenv profile with DEER_FLOW_COMPOSE_ENV_FILE=/srv/deer-flow/stage.env make up. The same file feeds Compose interpolation, Gateway/provisioner variables, and deployment secret checks. YAML and runtime-state locations remain separate selectors; see production env files.

For persistent deployments, configure database.backend as sqlite or postgres. The selected backend is shared by the LangGraph checkpointer, LangGraph Store, and DeerFlow application data. The deprecated checkpointer section, when present, overrides the first two for backward compatibility.

Gateway startup automatically repairs the missing run-change schema affecting some existing databases (#5516). The repair preserves run history and existing change positions; downgrading the repair to its predecessor also retains the schema and positions required by that version.

For lightweight single-process event persistence, run_events.backend: jsonl keeps Unicode message content intact, including line and paragraph separators. Existing valid JSONL records remain readable without rewriting the files.

For per-call usage audits, an immediate LLM response replay with populated usage updates both nested usage and top-level token counters, even if initial usage was absent or zero. The original request, model, and status metadata stay intact; flushed events are not rewritten. See the run event contract.

The unified nginx endpoint is same-origin by default and does not emit browser CORS headers. If you run a split-origin or port-forwarded browser client, set GATEWAY_CORS_ORIGINS to comma-separated exact origins such as http://localhost:3000; the Gateway then applies the CORS allowlist and matching CSRF origin checks.

When fine-grained authorization is enabled, Live Browser connections require threads:write as well as ownership of the thread, even when only viewing frames: the same connection can control the browser. Permission checks run when connecting. Restart Gateway after upgrading to disconnect sessions admitted by older code.

The bundled Docker, local and Helm nginx configs proxy Live Browser WebSocket upgrades with a 600-second read timeout for quiet streams. Helm uses nginx's default connection and send timeouts for the in-cluster Gateway. Any additional Ingress or reverse proxy must also allow WebSocket upgrades.

Browser login uses HttpOnly session cookies. The login page offers a "keep me signed in" option that extends the browser session when the request is HTTPS (including trusted X-Forwarded-Proto: https) or localhost HTTP. The localhost exception uses the direct request Host and ignores forwarded host headers. Public HTTP deployments, including many temporary sandbox URLs, fall back to session cookies by default. DeerFlow never stores the password in browser storage; the UI may remember only the email address.

If an authentication refresh fails during a temporary network outage, a visible tab rechecks the unknown session when connectivity returns or on a later tab switch. Reconnects received in a background tab are remembered until it becomes visible, without waiting for the tab-switch throttle. Identity is restored only after a successful auth response; a confirmed expired session or explicit logout still requires signing in again.

Password forms accept non-ASCII email addresses and trim surrounding email whitespace. Sign-in requires at least six password characters; creating an account or choosing a new password requires eight. These checks run before sending a request. Passwords, including surrounding spaces, are submitted unchanged.

OIDC/SSO authorization endpoints may include provider query parameters such as ?prompt=login. DeerFlow preserves those parameters when adding the login request, including for configured authorization_endpoint overrides.

After an SSO sign-in, DeerFlow returns you to the page that asked you to sign in instead of the default workspace. Opening the login page while already signed in does the same for its next target.

Administrators can suspend and restore accounts from Settings → Users (admin-only; the section is hidden for ordinary users). The page lists each account's email, role, and status and exposes the same enable/disable operation as PATCH /api/v1/admin/users/{id}; the last remaining active admin cannot be disabled, and the Gateway's rejection detail is shown verbatim. A disabled account is rejected by every authentication surface, and its live sessions end on the next request with a login page that states the account has been disabled. Password login for a disabled account deliberately still answers "incorrect email or password" so the state is not disclosed to whoever holds the credentials.

DeerFlow still uses Forwarded / X-Forwarded-* headers to recover the browser-facing scheme and origin behind a proxy. The bundled nginx sets X-Forwarded-Proto, but preserves an upstream HTTPS value and does not overwrite every forwarded header. Configure the outer trusted proxy to replace or strip client-supplied forwarding headers before traffic reaches DeerFlow.

[!IMPORTANT] The Gateway still owns active run tasks in process, so production defaults to a single Gateway worker (GATEWAY_WORKERS=1). Multi-worker deployments require Postgres, the Redis stream bridge (stream_bridge.type: redis), run_ownership.heartbeat_enabled: true, and run_events.backend: db; process-local memory/JSONL event stores cannot enforce singleton delivery receipts across workers. Kubernetes replicas run one worker per Pod, which the worker count cannot see: declare them with deployment.multi_instance: true (or DEER_FLOW_MULTI_INSTANCE=1, which deploy tooling such as a Helm chart can set from its replica count) so the startup gate enforces the same prerequisites instead of staying inert. Declared instances that store credentials (channel_connections, or MCP servers using the OAuth refresh_token grant, whose rotating tokens they share through the database) must also share one at-rest DEER_FLOW_CREDENTIALS_KEY (the Helm chart and make up generate it; back it up, see backend/docs/CONFIGURATION.md). The bridge shares SSE delivery and bounded Last-Event-ID replay across workers. When a trimmed reconnect cursor cannot be verified for complete replay, or a subscriber that already established an empty-stream wait falls behind before its first delivery, Memory and Redis emit a machine-readable SSE gap event instead of silently returning a partial replay; the Web UI reloads durable thread/event state and resumes from the retained tail. The Memory bridge can replay without recovery when the cursor is its exact last evicted event: every successor is still retained. Older or unverifiable evicted cursors still trigger recovery. An already-observed Redis stream removed during replay also signals a gap, so slow subscribers reload durable state instead of heartbeating forever after cleanup. Redis also tracks terminal stream producers with a short lease: if a worker dies after committing a terminal run status but before publishing END, SSE and /wait finish after the lease expires instead of waiting for the retained stream's TTL. Lease reconciliation marks runs from dead workers as errors, persists their delivery receipts, publishes the terminal stream marker, schedules retained-stream cleanup, and updates the affected thread status. Redis END publication is atomic and idempotent: owner and recovery retries confirm an existing marker without appending another, events cannot be appended once END is the stream tail, and an unowned recovery retry after cleanup does not recreate the stream. Legacy streams with an earlier END followed by late data can still accept data. The Redis compatibility scan (stream_bridge.legacy_end_scan_enabled: true) also runs on first END publication; disable it only after old writers stop and all legacy replay buffers expire or are removed, then restart every Gateway to use tail-only END detection. SSE, /wait, and internal stream consumers use stream_bridge.heartbeat_interval_seconds (default 15) for idle liveness checks; changing it requires a Gateway restart. Malformed Redis reconnect IDs live-tail new events instead of replaying the retained buffer, and the rolling retained-buffer TTL (stream_ttl_seconds) remains a cleanup safety net rather than a run timeout. Failed-login counters and lockouts for POST /api/v1/auth/login/local (auth.local.max_login_attempts / lockout_seconds) are kept in the shared login_throttle table whenever the application database is SQLite or Postgres (auth.local.throttle_storage: auto, the default), so every replica enforces one lockout per client IP; memory keeps the historical per-process counter, which under N replicas hands an attacker N × max_login_attempts guesses and logs a startup warning. IM chat-to-thread bindings live in the shared channel_thread_bindings table whenever the application database is SQLite or Postgres (an existing channels/store.json is imported once at startup and renamed store.json.migrated); IM bot credentials entered in the web UI live in the shared channel_runtime_configs table, encrypted with DEER_FLOW_CREDENTIALS_KEY (an existing channels/runtime-config.json is imported once and then deleted), so a save on any instance reaches the provider's connection within one lease renewal; each provider's platform connection is held by one instance through the shared channel_leases table — channels.leader_lease (default auto, on wherever the multi-process signal is) hands it to another instance when the holder dies, and the startup gate refuses enabled: false while an IM channel other than GitHub is enabled (see IM channel leader lease); follow-up buffers still need their own multi-worker coordination. To try this topology on one machine, make dev-multi starts two Gateways on shared Postgres, Redis and DEER_FLOW_HOME, and make dev-multi-check runs the cross-instance checks; see the local two-Gateway harness in backend/docs/CONFIGURATION.md.

The producer-lease recovery behavior above is gated by stream_bridge.producer_lease_recovery_enabled. Keep it disabled while old Gateway binaries or their runs remain; enable it on every instance only after the writer rollout and drain complete.

With run ownership heartbeats enabled, terminal success requires acknowledgment from that worker's own durable write. A matching database row alone cannot confirm success, and completion metadata cannot retry a rejected terminal transition. Each run renews independently, so a stalled store operation does not delay other runs. If acknowledgment remains unavailable when the last confirmed lease expires, the worker stops conservatively even if its commit actually reached the database. Expired leases cannot be renewed. Interrupt-and-replace admission acknowledges only the old runs actually claimed by its atomic transaction. Rollback keeps renewing its acknowledged interrupted row until restoration and the separate final error commit finish. An active-only renewal that raced that admission gets one bounded retry after the interrupted acknowledgment, without weakening the owner or live-lease checks. A failed renewal leaves a local expiry guard armed. Shutdown bounds its wait for orphan recovery, but cancellation-resistant storage may still be using its resources.

The local two-Gateway harness disables IM providers under both channels and channel_connections by default. DEERFLOW_MI_KEEP_CHANNELS=1 preserves them; channels.leader_lease stays as configured.

Cleaning up an in-memory run stream, or closing its bridge, releases retained payloads and signals a rep