Self-host deer-flow
v2.2.0- Stars
- 85 366
- Ports
- 2026 (nginx reverse proxy entry point (configurable via PORT env var)), 8001 (Gateway API (FastAPI) internal port), 3000 (Frontend Next.js production server internal port)
- Requires
- Python
What is deer-flow?
DeerFlow is an open-source super agent harness developed by ByteDance that enables long-horizon autonomous task execution. It orchestrates sub-agents, persistent memory (DeerMem), and isolated sandbox environments with filesystem access to handle complex, multi-step tasks that can take minutes to hours. The system is built on LangGraph and LangChain, providing a web UI, terminal workbench (TUI), and embedded Python client. Key capabilities include: extensible skill system with built-in skills for research, report generation, slide creation, and media generation; MCP server integration for custom tools; agentic browser control via Playwright; scheduled tasks with cron/interval/one-time triggers; RAGFlow integration for private knowledge retrieval; multi-channel IM support (Telegram, Slack, Discord, Feishu/Lark, WeCom); and personal access tokens for API access. It can be deployed via Docker Compose (production), local development with hot-reload, or run as a standalone TUI. The default deployment binds to localhost only for security, with documented hardening steps for network exposure. Licensed under MIT.
Should you self-host deer-flow?
deer-flow scores 86/100 on selfhost.directory (how scoring works) and ranks #4 of 208 in AI Agents. It has 85 366 GitHub stars, +1 660 in the last 30 days.
It shipped 3 stable releases in the past year. The latest, v2.2.0, came out on 4 November 2026. New versions land roughly every 2 months.
Setup is advanced: plan for several services and some ongoing maintenance. It is MIT-licensed and written mostly in Python.
Its closest alternative on selfhost.directory is Orca (91/100, 125 495 stars). It scores higher overall, so compare the two before you pick. See deer-flow vs Orca side by side.
Features
- Agentic Browser ControlOptional extra, requires `uv sync --extra browser` and `playwright install chromium`
- Extensible Skill System
- MCP Server Integration
- Multi-Channel IM Support
- Persistent Memory (DeerMem)
- Personal Access Tokens
- RAGFlow Integration
- Sandbox Execution Environments
- Sub-agents
- Super Agent Harness
- Terminal Workbench (TUI)
deer-flow README
How to install deer-flow
Install deer-flow with Docker Compose
BIND_HOST, PORT, BETTER_AUTH_SECRET, DEER_FLOW_INTERNAL_AUTH_TOKEN, DEER_FLOW_CREDENTIALS_KEY, LANGSMITH_TRACING, LANGSMITH_API_KEYmake 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
Production deployment with nginx, frontend, gateway, redis, optional provisioner
Install deer-flow with Build from Source
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup
make dev
Hot-reload development with interactive setup wizard
How to configure deer-flow
LANGSMITH_TRACING=falseEnable LangSmith tracingvalues: true/false
LANGSMITH_API_KEYLangSmith API key when tracing enabledvalues: API key string
DEER_FLOW_INTERNAL_AUTH_TOKENShared internal Gateway auth token for multi-worker IM channelsvalues: Random string
BIND_HOST=127.0.0.1Host interface for nginx to bind to (default 127.0.0.1)values: IP address or 0.0.0.0
PORT=2026Published port for nginx (default 2026)values: Port number
deer-flow releases & version history
DeerFlow 2.2.0
DeerFlow 2.2 turns the 2.1 super-agent harness into a deployment-grade platform
with a focus on operating at scale and delegating with trust: scheduled
tasks grow into goal-driven workflows with fair multi-owner execution, every
subsystem from IM channels to workflows runs across multiple Gateway
instances, the extension platform ships full-stack plugins, knowledge
retrieval becomes provider-independent with verifiable citations, and models,
memory and channels gain production-grade management — hardened by fail-closed
defaults, at-rest credential encryption, and a much stricter uploads and paths
layer.
This release closes the 2.2.0 milestone
with 1068 merged PRs since the 2.1.0 release.
📖 Full notes: CHANGELOG.md · 中文版
⚠️ Breaking changes
- Local dev binds loopback —
make dev/make startno longer listen on
all interfaces; ports 2026/8001/3000 and/setupstay off LAN/VPN. Set
BIND_HOST=0.0.0.0in.envto expose the stack, and note that values
nginx would misread (0,1.2.3, bracketed IPv6) are now rejected before
any service stops. ([#6587], [#6635]) - Stored credentials are encrypted at rest — a new env-only
DEER_FLOW_CREDENTIALS_KEY(Fernet, comma-separated for rotation) protects
IM channel credentials and MCP OAuth refresh tokens; multi-instance
deployments withchannel_connectionsor refresh-token OAuth refuse to
start without it. IM bot credentials move from plaintext
channels/runtime-config.jsoninto the sharedchannel_runtime_configs
table — existing bots are imported once on first start, and a downgrade must
re-enter UI-configured bots. ([#6611], [#7207], [#6988]) - The multi-process gate is stricter —
GATEWAY_WORKERS > 1(or
deployment.multi_instance: true, orWEB_CONCURRENCY) now requires the
Redis stream bridge; the memory bridge no longer starts multi-process. The
newchannels.leader_leasesection must stay enabled when a non-GitHub IM
channel is configured. ([#6328], [#6746], [#6252]) - Scheduler contracts change —
/api/scheduled-tasks*errors return a
structured{"detail": {"code", "message", "params"}}envelope (read
detail.message); a newscheduler.max_concurrent_runs_per_user(default
2) caps one owner's concurrent scheduled runs; IM notices are honest,
localized, and sent at most once per occurrence; DST-skippedoncewall
times are rejected with 422. ([#6378], [#6393], [#7281]) - Thread deletion cascades — deleting a thread now also removes its runs,
run events and feedback, so deleted threads can no longer be read or
inherited by recreated thread ids. ([#5535]) - Model-bound history stays append-only — superseded
write_filepayload
elision becomes opt-in (tool_output.elide_superseded_writes, default
false) because elision rewrote earlier request segments and invalidated
provider prompt caches; skillallowed-toolsis compatibility metadata only
and no longer hides or blocks tools. ([#7319], [#7455], [#6935]) - Tool authorization covers middleware tools — plan-mode
write_todosand
extension middleware tools now pass Layer-1 authorization like any other
tool; deployments with an explicittoolspolicy that omitted them stop
binding them. ([#6105]) - Fail-closed security defaults — delegated
web_fetch/web_capture
backends (Browserless, Crawl4AI, Firecrawl, fastCRW) screen their base URL
and refuse loopback/private defaults until confirmed; the SSRF guard refuses
the CGNAT range100.64.0.0/10(tailnets need
allow_private_addresses: true); IMallowed_usersparse fail-closed on
Slack, DingTalk, QQ and Telegram (an invalid list now denies everyone
instead of silently allowing); externalsystem/developermessages are
rejected with 400; permission checks now cover routes that previously had
authentication only, andUSER.mdis scoped per user.
([#6531], [#6202], [#6230], [#6742], [#6730], [#5651], [#4989]) - Uploads and paths get strict — Windows reserved device names (including
superscriptCOM¹–COM³andCONIN$/CONOUT$) are rejected across
uploads, sandbox writes and skill files; same-name uploads claim the next
_Nsuffix instead of truncating; converted Markdown companions never
replace an existing file; rejected attachments are recorded in
skipped_filesandsuccessmeans at least one file stored; outline/preview
records missing timestamps are rejected — re-upload to restore conversion.
([#6102], [#6148], [#6279], [#6149], [#7388], [#7054], [#7165], [#6165]) - The composer slash menu is reduced —
/now lists only the built-in
/goaland/compact; select skills as inline@references instead.
([#6154]) - API shapes tighten — malformed run bodies return 422/400 instead of 500;
waitendpoints return an SDK-compatible error envelope for completed
failed runs; an explicit emptyevent_typesfilter matches nothing; keyed
resume fails closed (503) for RunStores that can't persist request identity;
web-editor MCP connections become per-user; SQLitefile:URIs are
rejected; integer config fields reject YAML booleans;gpt-6family models
default to the Responses API;--print/--jsonexit 1 on LLM-error
fallback. ([#7362], [#6217], [#7352], [#6571], [#6499], [#5966], [#6069],
[#6017], [#6171], [#6863], [#6056])
✨ Highlights
- Scheduled tasks grow into goal-driven workflows — conversation tools
create and manage owner-bound schedules with per-run goals, stop conditions
and safety caps ([#6229], [#6378]); lifecycle and limits are at parity
across page, REST and chat, with a live task card in the web chat ([#6378]);
fair execution slots cap each owner (max_concurrent_runs_per_user) and the
waiting queue drains owner by owner ([#6393]); lifecycle events are recorded
durably in the creating chat ([#6393]); IM notices are honest, localized and
self-contained ([#6393]); tasks are searchable by title or prompt ([#5355]),
and agent stops, auto-pauses and goal misses are explained in plain language
with links to the deciding run. ([#6326]) - Multi-instance readiness — IM channels run on several Gateway instances
via per-provider leader leases with fencing epochs and automatic failover
([#6843], [#6746]); Helm and compose gain a multi-replica story with a shared
JWT secret, surge-then-drain rollouts and PodDisruptionBudgets ([#6347]);
provisioner replicas keep sandbox creation alive through restarts ([#6543]);
the workflows extension coordinates across Gateways over shared Postgres
with anExecutionFence([#7138]) and authenticated restart recovery
([#7075]); andmake dev-multiboots a two-Gateway cluster locally.
([#6613]) - The extension platform matures — full-stack plugins register browser
pages, conversation actions and model tools in one namespace ([#5647]) with
versioned manifests and credentialed ES-module graphs ([#5685]); plugins can
contribute composer@mention providers ([#6189]) and drive full Agent
runs through the Gateway's normal admission ([#6190]); packaged extensions
can invoke host models under operator-granted limits ([#5796]); agent-teams
lets Custom Agents collaborate as a team via@mentions, with a shared
activity feed and durable team state ([#6243], [#7611]); a default-disabled
Script workflows extension sequences and branches Agent runs in a
capability-restricted QuickJS subprocess ([#6858], [#6920]); new Jev example
plugins prune stale context, classify texts and flag injected instructions
([#5731], [#5735], [#5833]); the extension API advances 0.2.2 → 0.2.7 with
run-evidence readers, structuredPluginToolResultartifacts and guarded
skill-evolution host APIs ([#5727], [#6861], [#5645]); and the Capability
Center gallery ships a bundled extension catalog. ([#6188]) - Knowledge retrieval goes provider-independent — read-only provider
catalogs are decoupled from RAGFlow through extension-API registration
([#6904]); retrieval results, capabilities and source evidence are unified
across LightRAG and RAGFlow, and citations survive budgets, delegation and
replay ([#6716]); RAGFlow results carry verifiable inline citations backed
by bounded native excerpts ([#5551]); custom-agent chats can scope retrieval
per message with fail-closed allowlists ([#5238]); and new WeKnora and
knowledge-platform extensions add managed ingestion plus hierarchical
logical spaces with inherited roles. ([#6950], [#7293], [#7417]) - Models come under management — administrators manage shared models from
Settings → Models with an encrypted catalog, optimistic revision checks and
provider presets ([#5596], [#6757]); a declarative reasoning capability
contract (thinking,dialect, effort maps) normalizes thinking policy
across lead agent, subagents and helpers and drives the frontend effort menu
([#5780]); scoped model controls resolve natural-language model selection
per task/turn/conversation, with up to 16 aliases per model and per-child
overrides ([#7249]); and new presets and providers arrive: Kimi K3.1
([#7566]), Opper ([#6399]), API Route ([#6579]), You.com ([#6515]), Webz
News ([#5880]), Unbrowse ([#5981]), plus Exa-compatible endpoints via
EXA_BASE_URL. ([#7306]) - Channels become operations-grade — a new QQ channel runs over Tencent's
official Open Platform WebSocket with no public callback URL ([#6081]);
WeChat pairs by scanning a QR code from the web UI ([#5582]); proactive
notifications generalize to Feishu, QQ and WeCom with opt-in run-completion,
failure and human-input notices from a durable outbox ([#6903], [#6850],
[#4843]); Feishu renders clarifications as interactive button cards ([#6670]);
/modelswitches an IM conversation's model in place ([#6534]);/connect
bindings move to a persistent dialog with copyable codes ([#7591]); and IM
runs survive Gateway restarts withon_disconnect: continueand idempotent
redeliveries. ([#6876], [#7104]) - Memory sharpens —
user.cognitiveStylestores collaboration preferences
separately from personal context ([#3182]); opt-in lexical relevance ranking
blends IDF-weighted query coverage with confidence using a CJK bigram
tokenizer ([#5251]); tolerant Markdown storage recovers corrupt or partially
written files instead of crashing the agent ([#5545]); the management API
and a newmemory_gettool work per agent bucket ([#5565], [#6443]); opt-in
TypeSafe pre-screening can skip extraction calls and classify
reinforcement/correction signals ([#5906]); and extraction watermarks
persist across restarts so already-extracted turns don't re-run. ([#7205]) - Workspace — the Capability Center unifies MCP, plugins, Lark CLI and
skills into a searchable catalog with configuration forms ([#5497]); the
composer gains inline@references to skills, project documents and other
conversations, up to 16 per message ([#6063]); tool-produced paths, URLs and
task ids become short stableart_xxxartifact handles that survive context
compaction ([#4929]); the answer toolbar shows which skills a run loaded,
with inspectable snapshots ([#5758]); Custom Agents export/import as portable
packages ([#6127]); and projects gain a budgetedsearch_project_documents
tool ([#7286]) and opt-in LLM summaries on the document shelf. ([#6581]) - Runtime & observability — an authoritative
run.terminaltrace event
seals completed runs ([#7134]); run events carry per-LLM-call telemetry —
caller category, provider, model, stop reason, token counts ([#6236]);
inspect_run_statusgives agents a content-free usage and context-fill
snapshot ([#7297]); client context hints and the web UI locale travel into
runs as sanitized request-only context ([#7051], [#7294]); and subagent
batches gain browser result review with cited evidence ([#7006]),
read_batch_resultinspection ([#6416]), RAG evidence snapshots ([#6413]),
andcsv-columns/json-validacceptance criteria. ([#6714], [#5947]) - Persistence — a checkpoint retention service prunes trailing
duration-only leaves while protecting the resume head ([#5308]); a
content-addressed blob store (sha256-verified, opt-in) lets load-balanced
Gateways restore externalized tool results and viewed images from shared
bytes instead of hitting broken local paths. ([#5361], [#6159], [#6160]) - Auth & guardrails — account suspension is enforced at every auth surface
with a new admin Users page ([#6566], [#6641]); custom RBAC roles are
assignable through the admin API ([#6382]); theskillspolicy governs
visibility on listing surfaces without an existence oracle ([#5489]); opt-in
deterministic PII redaction rewrites model-bound context with stable
placeholders ([#5527]); an opt-in TypeSafe risk gate denies tool calls at a
configurable threshold ([#5712]); and plugin actions and management routes
are authorization-gated. ([#5842])
🚀 Performance
- Compaction skips the summarizer LLM call when the exact rendered prompt
previously produced the unchanged summary. ([#6318]) - Opt-in sandbox prewarm overlaps authorized acquisition with the first model
response for managed async runs and native subagents. ([#6998]) - MCP tools are cached per unchanged server and only missing/changed configs
are rediscovered ([#6795]); config edits retire only the affected stdio
sessions via connection fingerprints. ([#6487]) - Community tools stop blocking the event loop: You.com, GroundRoute,
InfoQuest, Tavily, Firecrawl and DuckDuckGo image search become coroutines
or offload to workers ([#7186], [#7183], [#5782], [#5784], [#5786],
[#5788]); config reads, auth routes and route-permission resolution load in
workers instead of stat+sha256 per request. ([#7580], [#7576], [#7557]) - Channels: DingTalk AI cards use the channel's bounded token instead of a
blocking SDK call that stalled every stream ([#7597]); Feishu stores thread
aliases once per reply instead of rewriting the store per chunk ([#7593]);
channelstop()tears down SDK threads off the loop. ([#6134]) - Gateway: run creation resolves the agent factory via the assembly pool so a
cold import no longer stalls all requests ([#6206]); subagent batch export
reads 10 rows per page and item lists return previews, cutting hundreds of
MB per request ([#6706], [#6781]); skills, user-profile and thread-deletion
routes offload directory scans and rmtree to workers. ([#5945], [#5935],
[#6319]) - SSE responses send
Cache-Control: no-cache, no-transformso compressing
proxies stop buffering run streams into bursts. ([#6393]) view_imagere-injection caps at four images / 28 MiB per request, so
re-viewing an older image no longer resends the whole image history.
([#6828], [#6829])- Document conversion offloads at every source size ([#6924], [#5830]); lazy
shelf-document conversion writes outside the SQLite write lock. ([#6305]) - Linear algorithms and bounded payloads:
strip_think_blocks([#5854]) and
skill-review link extraction ([#5884]) lose their quadratic paths;
structured tool-output previews respect excerpt budgets ([#6422]); one-shot
chat models build off-loop ([#7484]); memory pre-summary saves run in a
worker ([#7530]); E2B reconciliation stopsconnect()-probing warm pools
([#5562]); thread skill-view freshness fingerprints end a full NFS recopy
per acquire. ([#7333])
🔒 Security
- SSRF screening everywhere — every
web_searchprovider screens result
URLs through the shared public-URL policy ([#7037]); InfoQuest organic,
news and image results are screened ([#7031]); image search shares one
policy across DuckDuckGo, Brave and Serper with Unicode-host, NAT64 and
multicast coverage ([#6740], [#6819]); the CGNAT range100.64.0.0/10is
refused across web tools, browser and MCP ([#6202]); the agentic browser
routes TCP through a per-session SOCKS5 proxy that resolves DNS under SSRF
policy, defeating rebinding ([#6201]); and Unbrowse redacts authenticated
finalUrls from error responses. ([#7399]) - Authorization gaps closed — permission checks now cover routes that had
authentication only, andUSER.mdis scoped per user ([#4989]); Live
Browser WebSockets requirethreads:write([#5621]);view_imagerequires
sandbox:execute([#5799]); the suggestions endpoint enforcesmodel:use
([#5816]); skill activation is authorized at assembly, including via
read_fileof aSKILL.md([#4541]); viewed-image blobs require
owner-checkedthreads:read([#7604]); and middleware-declared tools join
Layer-1 tool authorization. ([#6105]) - Server-owned state can't be steered — restored sandbox references are
scoped to the authenticated user and thread, and externalinput.sandboxis
rejected ([#5736]); viewed-image host reads are scoped to the current thread
([#5824]); externalsystem/developermessages are rejected before
checkpoint writes ([#5651]); client uploads no longer write through symlinks
and document conversion reads private descriptor-backed copies ([#5578],
[#5611]); and Redis checkpoint purge escapes glob metacharacters so a custom
prefix can't delete another namespace. ([#6709]) - Credentials & egress — modern
sk-tokens, GitHub fine-grained PATs and
Google API keys are detected in SkillScan and scrubbed from outgoing IM
notifications ([#6394], [#6423]); MCP logs stop emitting credentials
([#6794]); 500 details no longer echo host paths for uploads, skills,
custom agents and scheduled tasks ([#7217], [#7255], [#7155]); urllib3
retry/header dumps redact signed URLs ([#5745]); and IM channel credentials
gain at-rest encryption keyed byDEER_FLOW_CREDENTIALS_KEY. ([#6611]) - SkillScan matches shapes, not spellings — fork bombs are matched by
structure ([#6689]); the.builtin is treated as asourceexecution
context, including process-substitution forms ([#7247]);curl | sudo -u
variants are caught ([#6372], [#6312]); binary magics are sniffed past up to
63 bytes of padding and a BOM across preflight, extraction guard, scan and
nested-zip checks ([#7081]); executable-content classification uses the
sharedis_code_filerule ([#7088]); Windows script suffixes count
everywhere ([#6321]); secret rules parse Python via AST, cutting false
positives ([#5648], [#6297], [#6428], [#6247], [#6276]); a planted 300 MB
file can no longer OOM the scanner ([#6359]); and tool-discovery regexes are
bounded against ReDoS. ([#6676]) - Fail-closed configuration — IM
allowed_usersparse strictly on
Telegram, Slack, DingTalk, QQ and Buzz ([#6230], [#6742], [#6730], [#6811]);
PII redaction covers the queued memory payload,invalid_tool_calls, and
the/goalevaluator's inputs ([#5577], [#6387], [#6556]); first-admin
claiming is atomic under concurrency ([#5776]);image/svgis classified as
active content ([#5594]); and model-writtenms-msdt:-style tool-step links
are gated by a scheme allowlist. ([#5526])
🐛 Notable fixes
- Runs & streaming — cross-worker cancel takeover synthesizes END via an
orphan_recoveredstop reason ([#6674]); consumers recover when a producer
dies between terminal persistence and stream END ([#7093]); disappeared
Redis streams and ahead-of-retention cursors signal a replay gap instead of
heartbeating forever ([#6951], [#6605], [#6812]); shutdown drains runs with
staged-but-uncommitted terminal status ([#6620]); heartbeats keep leases
through deferred terminal writes ([#6263]); interrupted runs persist their
streamed assistant text ([#7153]); delta-mode resume refuses while
checkpoints hold pending execution ([#7441]); JSONL stores survive torn
final lines and remember deleted sequence watermarks ([#6520], [#6546]);
Gateway-issued message ids let rejoining clients dedupe ([#7349]); and a
per-thread event high-water mark prevents sequence reuse. ([#6477]) - Sandbox providers — provider shutdown is retryable across AIO, E2B,
BoxLite, Tenki and OpenSandbox ([#6231], [#6244], [#6317], [#6283],
[#7001]);sandbox.bash_command_timeoutis enforced with server-side hard
timeouts ([#5634], [#5662], [#6782]); ambiguous AIO session creation is
tombstoned instead of replayed ([#5711]); AIO probe scripts run in a
subshell so they can't wedge the persistent shell ([#5546]); remote
glob/grep/read reach LocalSandbox parity — newline-only records,-F
literal patterns, quoted--include, exact-cap probing ([#6585], [#6573],
[#6952], [#6529], [#6969], [#5534]); the local path guard closes
$HOME-prefix and awk-program bypasses ([#6930], [#7023]); PowerShell path
escaping survives spaces,$and quotes ([#7245]); CRLF/LF and UTF-8
fidelity hold on Windows and Git Bash ([#6343], [#6548], [#5905], [#6727]);
E2B restores persisted workspace before exposure and releases slots when
VMs vanish ([#6824], [#6547]); and OpenSandbox mirrors outputs before warm
parking. ([#6699]) - Channels — DingTalk card/token paths stop stalling the event loop
([#7597]); channel stops surfaceChannelStopTimeoutand retain live
workers instead of orphaning them ([#6798], [#6215], [#6333]); lifecycle
mutations serialize per channel with epoch-versioned updates ([#6304],
[#6503], [#6521]); multi-worker saves no longer overwrite each other's bots
([#6844]); IM redeliveries carry idempotency keys ([#7104]); Slack admits
file_sharemessages and Discord admits file-only messages ([#6855],
[#6857]); Telegram splits by UTF-16 code units so emoji replies don't 400
([#6067], [#6174]); Slack entity decoding is restored ([#6045]); concurrent
attachment uploads claim filenames withO_EXCL([#6476]); and
Feishu/DingTalk inbound files get sandbox-readable permissions. ([#5998]) - Models — Claude prompt-caching markers are placed on copies and exclude
thinking blocks, fixing HTTP 400 thread death ([#5892], [#6339]);
extended-thinking budgets validate against real constraints ([#6060]);
Retry-After handling is unified, including HTTP-date parsing and
status-less streaming errors ([#7295], [#7151], [#6455], [#6897]);
DeepSeek/Moonshot cache-write usage is restored ([#7428]); MiniMax keeps
reasoning_content([#6071]); Codex completes onresponse.completedand
tolerates null usage and empty tool-call ids ([#6155], [#6335], [#6234]);
MindIE extracts XML tool calls before decoding escaped newlines ([#6334],
[#6030], [#6478]); vLLM falls back to legacy reasoning fields ([#6048]);
credential loading tolerates malformed sources instead of losing valid
fallbacks ([#7140], [#6323], [#5591], [#5601], [#6277]); and the circuit
breaker fences settlements by generation with monotonic recovery. ([#5602],
[#6806]) - MCP — persistent sessions tear down on thread deletion and Gateway
shutdown ([#5956], [#5961]); notification launches are atomic with
dead-lettering for deterministic rejections ([#5965], [#6693]); durable-task
claims renew via heartbeat and fence stale writers ([#6780], [#6859],
[#4966]); stdio bindings carry epochs and ownership domains so equal server
names can't reuse the wrong session ([#6435], [#6133]); cache invalidation
fires only on effective config changes, and error logs drop credentials
([#5750]); workspace-relative path correlation handles whitespace and
Windows separators ([#5819], [#5815], [#5522]); andResourceLinkresults
become gated placeholders with read-time healing of poisoned threads.
([#6606]) - Scheduler — a reconciliation pass finalizes occurrences whose run rows
are already terminal, so a failed completion hook no longer stalls schedules
([#7269]); manual trials no longer consume the recurring cursor or clear
claim leases ([#7209], [#6512]); DST fall-back runs fixed-hour cron once and
one-time edits preserve the saved instant ([#6066], [#6756], [#5330]);
dispatch and lease races are closed under database locks ([#5860], [#5777],
[#6975]); and only real conflicts retry — plain 409s fail the occurrence
with the reason persisted. ([#7196]) - Frontend — message order stays stable across long runs and reconnects
via journal-sequence re-anchoring ([#6128], [#6074]); failed sends keep the
draft, quotes and attachments ([#6412], [#6407]); reconnect rejoins the live
run and replays gaps safely ([#5536], [#6400], [#6662], [#6800]); HTML
previews honor only a real<base>element ([#6176]); CSV/TSV samples
splitting a CRLF no longer reject complete rows ([#6180]); artifact saves
key on file identity so same-size replacements refresh ([#6195]);
Dockerfile/Makefileopen as editable source ([#6091]); unsaved drafts
persist per account, conversation and path ([#6700]); isolated HTML previews
get authenticated static resources ([#6701]); docs search ships a pinned
pagefind index ([#6715]); truncation counts code points so emoji survive
([#7503], [#7452], [#7474]); and Escape/Enter stay with the IME during
composition. ([#5741], [#6768]) - Memory — malformed Mem0/Honcho payloads follow the configured read
policy instead of crashing runs ([#7561], [#7307], [#7202]); planning text
carrying tool-call intent no longer becomes memory content ([#6379]); free
form fact categories likepersonalare preserved ([#6733]); explicit
confidence: 0.0ranks below the default ([#5586]); reads of
deleted-since-listed facts no longer 500 ([#6255]); jieba tokenization drops
punctuation-only tokens ([#6388]); quarantined summaries preserve the
original bytes ([#7076]); and BOM-prefixed facts and summaries load.
([#7084], [#7116]) - Skills — malformed custom skills surface diagnostics in the Capability
Center instead of vanishing ([#6623]); symlink cycles no longer cause
multi-second rescans ([#5921]); managed skill discovery stops at
SKILL.mdpackage boundaries ([#5890]); skill toggles work without an
existingextensions_config.jsonand reset caches on every replica
([#7048], [#6495], [#7099]); ppt-generation fixes EXIF orientation and
alpha backgrounds ([#7193], [#7312]); data-analysis exports handle bare
filenames, NaN, duplicate columns and Markdown escaping ([#7132], [#7456],
[#7163], [#7305]); podcast, video and chart CLIs exit non-zero with stderr
diagnostics ([#7236], [#7340], [#7395]); and github-research filters PRs out
of issue listings and paginates fully. ([#7516]) - Persistence & stores — Gateway writes drain through cancellation so a
disconnected client can't silently drop a commit, across agents, managed
models, subagents, memory, MCP, projects and channels ([#6023], [#6024],
[#6087], [#6092], [#6093], [#6198]); Postgres bootstrap survives
duplicate-database races and preserves DSN query bytes ([#7489], [#5978]);
advisory locks poll so long migrations don't time out ([#6306]); staged temp
files register for cleanup before content is written ([#7504], [#7485]);
schema-drift warnings compare the connected database's spellings ([#6865]);
concurrent first ratings upsert instead of 500 ([#6852]); and integer
metadata filters match without overflow. ([#6000]) - Goal — the active goal is exposed to the agent capped and escaped
([#5917]); evaluator evidence includes assistant tool calls, tool results
and Human Input Card answers ([#6068], [#6082]); a satisfied goal survives
failed artifact delivery ([#5980]);loop_cappedstops continuations while
preserving the goal ([#7167]); no-progress fingerprinting keys on observed
operations instead of evaluator text ([#7271]); evaluator failures persist
reasons ([#6073]); and invalid goal writes are rejected with 400. ([#6685]) - TUI & CLI — the composer becomes a multiline editor preserving pasted
code ([#6168]); refused messages stay in the composer for editing ([#6666],
[#6219]); each run owns its cancellation flag and delivery identity ([#6302],
[#6249]);/threadsand/modelpicker labels render as written ([#7631]);
headless--print/--jsonfailures print errors instead of tracebacks
([#5963]); and streamed deltas append as sent so repeated tokens render
correctly. ([#7325]) - Extensions & workflows — QuickJS idle waits stop exchanging poll frames
that exhausted the turn limit after ~209 s ([#7024]); agent-teams locks and
workers isolate per team ([#6754], [#6298]); lark skill, launcher and shim
publishes are atomic ([#6683], [#6671], [#6618]); and failed extension
rollbacks restorepyproject.toml/uv.lock/config.yamlatomically with
captured permission bits. ([#6366])
📦 Deploy & ops
- Docker — nginx is pinned to
nginx:1.31.2-alpinein both compose files,
dodging a musl 1.2.6pwritev2seccomp denial that restart-looped
containers on older Docker releases ([#7643]); hosts without IPv6 start
([#5900]); project-document uploads get their own 100 MB streamed location
([#5934]); the/api/catch-all and skills routes allow 600 s ([#5524]);
env_fileentries are optional so fresh checkouts runmake upwithout a
.env([#6370]);DEER_FLOW_COMPOSE_ENV_FILEselects the root dotenv
explicitly ([#6522]); and production launch pathsexecthe server so
SIGTERM shuts down gracefully. ([#6836]) - Kubernetes — Helm and compose gain a multi-replica story: shared
AUTH_JWT_SECRET,DEER_FLOW_MULTI_INSTANCE, surge-then-drain rollouts and
PodDisruptionBudgets ([#6347]);provisioner.replicaskeeps sandbox
creation alive through provisioner restarts ([#6543]); adatabaseUserSecret
helper unifies Secret-name precedence ([#7291]); the provisioner receives
DEER_FLOW_HOST_BASE_DIRfor shared-PVC skill projections ([#5625]); lark-cli
images are configurable ([#5835]); and the userdata PVC is declared once per
sandbox pod and reused via subPaths. ([#7274]) - Health & readiness —
/health/readyreports 503 while the Redis stream
bridge is unreachable. ([#6447]) - Configuration —
DEER_FLOW_ENV_FILEselects one explicit dotenv file
([#6227]); blank env vars are treated as unset instead of crashing startup
([#5840], [#5801]);make config-upgradeandmake doctorhonor
DEER_FLOW_CONFIG_PATHand.envoverrides ([#5991], [#5987], [#6934]);
every Gateway sharing oneextensions_config.jsonsees other processes'
MCP/skill changes ([#6386]); numeric config fields gain range bounds and
boolean rejection ([#6026], [#6009], [#6172]); and operator configs tolerate
a leading UTF-8 BOM. ([#5983], [#7112]) - Upgrades — new migrations carry channel thread bindings, encrypted
channel credentials, MCP OAuth tokens, resume-request identity, account
suspension, per-thread event sequences, scheduled stop conditions and
workflow execution leases ([#6558], [#6988], [#7207], [#6499], [#6566],
[#6477], [#6378], [#7138]); Windows read-only files no longer wedge thread
deletion or trash purge ([#7446], [#7499]); andmigrate_user_isolation.py
reads owners from the configured database. ([#6450]) - CI & tooling — a
skill-testsCI job runs the public skill regression
suite independently of package review ([#7350]); CI checks bundled extension
packaging ([#6788]);make testruns four duration-balanced shards
([#6324]);verify_versions.shrejects a staleuv.lock([#6588]);make dev/startparse.envdotenv-style so values can't execute commands
([#7606]);make cleanrefuses to run while a live Docker Gateway mounts
backend/.deer-flow([#6351]); dev ports are reclaimed across sibling
worktrees with spaces in their paths ([#5856]);make doctorvalidates real
CLI credentials ([#5567]); and the setup wizard defaults Anthropic to
claude-sonnet-5-5, replacing the retired model id. ([#7585])
🙌 Thanks
Huge thanks to the 213 contributors who landed 1068 merged PRs in the 2.2.0
milestone, and to everyone who filed issues, tested builds, and shared
feedback. DeerFlow 2.2 wouldn't exist without you.
In alphabetical order:
- @0xzkslr-ai
- @2017955725 — jiujiu
- @67-luck — Luck
- @97Three — creed
- @ajayr
- @alanhuangyoo
- @Aldenshile — BaiHeng Peng
- @Aling33
- @Amazingjun-j — Jun
- @AnnaSuSu — Wenchao An
- @Aoisop — Dragon ze
- @asts-top — asts
- @auge2u — Agustin M.
- @axsapronov — Aleksandr Sapronov
- @bbudaedu — TAI-YUAN GUO
- @Bdysj — Bob
- @bieh — Paul Hunkin
- @BlueX888 — 哈基米
- @BXL1015 — Bxl
- @camcalaquian — Carl Calaquian
- @cangen185-sudo
- @Carrot-Ve — Fake1new
- @ChaoDiDiaoAA — chaodidiao
- @Chaoqi31 — Chaoqi
- @chauvuusvn — Chau Vu
- @CodeAlex52
- @conghua1013
- @Cordis798
- @CorgiBoyG — RongJie G
- @CSXizhang
- @dakjdakd — Lucien
- @DaoyuanLi2816 — Daoyuan Li
- @dcaldr — Dan Caldr
- @DennyHo0917
- @DerrickJc — derrickLzw
- @destire-mio
- @drakeo338 — Younes Beriane
- @Eilen6316 — Eilen Shin
- @fallintoplace — Minh Vu
- @fancyboi999 — Xinmin Zeng
- @FanouZeng-TT
- @Felixkw12 — Felix
- @gdut4140 — 一片一片
- @ggnnggez — Nan Gao
- @gmll-star — Gusanity
- @GodBlf — Xuehao Xu
- @Gujiassh — Ryanba
- @Gumayusy
- @Guo-Yixin
- @hackermengzhi — BUG设计工程师
- @haomint — haochen
- @haotianqi666
- @hata33 — hataa
- @he-yufeng — Yufeng He
- @hehe764 — ShiYuan Xiong
- @heranliu — Heran Liu
- @Huang-404-Q
- @huangzz
- @Hugo-DDT — DDT
- @huidongchen148 — easT-T
- @huiq777 — Jin
- @huyengiang101086-spec
- @hyeonsang010716 — Hyeonsang Cho
- @inchang-ing
- @indexGin — ChengFa
- @Inference1 — Inference_
- @Insecshin
- @jamespud — spud
- @JasonBuildAI — Jason Cat
- @jasontd92 — Jason Draper
- @Jaxon1216 — EastonJiang
- @Jay0130-a — lukyturnflow
- @jayfeng7 — jay
- @Jerry2003826 — Jiarui Li
- @Jholly2008 — Jholly
- @jiangjiang248
- @jianyx1
- @Jinzhengxu — Zhengxu (Joshua) Jin
- @jswSpace
- @Jun516 — Qiu
- @JY-M666
- @kassdinzheng123 — Zheng Haoran
- @kbkb628
- @KennyMcSimpson — KennySimpson
- @KevinAndrewDong — Kevin Dong
- @Kiko0301
- @kunkun403
- @kwsYegar — Yeager0204
- @lachy3433 — Lachlan Allen
- @lakers-abing
- @LancerLee428 — 李靖
- @lau0708
- @laundry2 — laundry
- @lekt9
- @Lesereingrape — Grapette.L
- @lester076
- @Li-john1021
- @lihongyuan99
- @lin-nan366 — N
- @LingYi-Liang — LingYi
- @Linxiushen — 林SO
- @lisir202446 — 李刚 / Bryan Li
- @lisry-1
- @litescraper
- @liu584
- @liunianxuxie
- @liwenjie200543 — kuse
- @llb555
- @louisss1016 — Louisss
- @Lts1sds
- @luckiest-draw
- @LuckVd
- @McgAtom — SumEn
- @mikamikasuki — mika
- @mmhh256 — Wang Xinming
- @MsNBBc3R
- @nanhanq1 — NanHan Qing
- @ningkexin96
- @nothingyuancando — Tsai Yuan
- @ooiuuii
- @OUAO-FRANK — zhouh
- @pclin1212 — pclin
- @PeaceMaker-best
- @PerryLink
- @poijygfdyy — NanPan
- @ppdiedie — pp
- @pwd11 — wd_pan
- @quifox
- @ranjianghong526-hash
- @roli-lpci — Roli Bosch
- @ruirui6946 — yang rui
- @RXQ6 — XuRuuuy
- @RykerFeng — Ryker_Feng
- @saddddboi — Jie Ji
- @sclfcz — IronMurphy
- @ShallAbby
- @ShaoLOWu
- @ShenAC-SAC — AochenShen99
- @sherxlg-gif — NEEDI
- @shi-felix — Felix Shi
- @ShitK
- @simpleqt — 陈志谦
- @sisyfy-Zhang — sisyfyZhang
- @siye566 — 四野
- @Smilewithoutfalling
- @stanGSA
- @Starchaser1024
- @Stella-xixi
- @StormTian — Storm
- @subhash7476
- @sun-sh — Sun Shihao
- @sun04222
- @SuperSgdk — Linyao Du
- @sxh313 — sxh
- @sxl-lucky7
- @Theater-ahyeon — theater
- @tiammomo
- @TINGyu123644
- @tomyan007
- @Tong-bit-art — ordinary being
- @tonydzi — Anton Dziatkovskii
- @torrresagus — Agustin Torres
- @Totoro-qaq — Totoro
- @transparent21 — yijun Lin
- @treasuresyq
- @trent87
- @Tsubaki-01 — Weng Qiang
- @TYY-2005
- @uhhgxg
- @Undermoon1412
- @valueadd-lgtm — Value Add
- @Vanzeren — Zeren Wang
- @vency-799
- @vicfei
- @wannT-1
- @wcy12378 — Kris
- @wgwfn3
- @WillemJiang — Willem Jiang
- @Winoren
- @wjl8636 — 万家良
- @wswsadadbaba123 — zzr
- @wuwenbo0626 — WuWenbo
- @wuyi-github
- @wxhking — Fish
- @wyi184246-creator — 王一帆
- @wzxsdf — 杰尼龟
- @X77seven — X77
- @xbzz1018 — kuku
- @xiaodu55
- @xiaoyuCR7 — Evan
- @xihongshichaojidan8 — lilei
- @xjsns346 — illusion
- @XY-code1 — XY
- @xyi74976-del — yi-coding
- @XZQ173 — X
- @yang0228 — JasonH
- @yangfucheng123
- @yc2bgr8
- @yetuge
- @yinx65588-boop
- @YongxinFu
- @yu-xin-c — Stellar鱼
- @yu1128-L
- @YxinMiracle
- @zaoshangduziteng — 早上肚子疼
- @zeng-bohan
- @zhangbububu — Keswyk Cheung
- @zhangwei-way
- @zHaooJ — zenghao
- @Zhouyang66639 — ZHOU YANG
- @Zhuo2021
- @Zicheng-Xie — Zicheng (Axelsen) Xie
- @ZJPex
See the full author and PR list on the
milestone page.
DeerFlow 2.1.0
DeerFlow 2.1 builds on the 2.0 super-agent harness with a focus on trust,
scale, and operability: verifiable agent execution, durable batch delegation,
pluggable memory backends, four new sandbox providers, an out-of-tree extension
system, and enterprise-grade authentication and authorization — wrapped in a
much richer workspace with projects, conversation branching, and referenced
conversations.
This release closes the 2.1.0 milestone
with 772 merged PRs since the 2.0.0 release.
📖 Full notes: CHANGELOG.md · 中文版
⚠️ Breaking changes
- Trace ids are unconditional — every Gateway HTTP response carries an
X-Trace-Idheader, andlogging.enhance.enablednow controls log output
only. Client-supplieddeerflow_trace_idvalues in run metadata are
overwritten so header, logs, and the persisted run cannot disagree — send
theX-Trace-Idrequest header to pin a correlation id. ([#5119]) /mnt/skillsis reserved for managed enabled-only skill projections.
DEER_FLOW_HOST_SKILLS_PATH/SKILLS_HOST_PATHare no longer used, and
E2B operator mounts targeting that path are skipped with a warning.
([#4178])sandbox.replicasis enforced for E2B as a capacity limit; the default
waitpolicy can now fail the agent turn instead of growing past the cap.
([#4391])- A
SKILL.mddirectory is a runtime package boundary — nestedSKILL.md
files are supporting data, no longer registered as independent skills.
([#4098]) - Memory is pluggable (
memory.manager_class): DeerMem-private settings
move intomemory.backend_config(auto-migrated with a warning),
/memory/configchanged shape,storage_pathis now a root directory
(legacy file-style values are dropped with a warning), custom storage classes
move to a new path and takeconfigin__init__, and a backend without
search()fails fast intoolmode. ([#4122], [#4023], [#4324]) database.checkpoint_delta_snapshot_frequencymoved to
database.checkpoint_delta.snapshot_frequencyand its default changed from
1000to10— set it explicitly to keep the old cadence. ([#4516])- Docker binds loopback by default — the published entry port binds
127.0.0.1in both compose files, matching the documented local-trust
deployment model; setBIND_HOSTto expose the stack on other interfaces.
([#4618])
✨ Highlights
- Verifiable agent execution — every tool call carries a tamper-evident,
runtime-stamped receipt and a bounded receipt ledger reaches the model
context; subagent reports must cite tool receipts with verifiable deliverable
handles that the lead agent cross-checks; andacceptance_criteriaon
delegations are checked deterministically parent-side (file existence,
recorded test-command exit status), with anything undecidable reported
UNVERIFIED. ([#4659], [#5076], [#5090], [#5109], [#4365]) - Subagents at scale — a system-maintained delegation ledger prevents
redundant re-delegation and a total cap bounds fan-out ([#3877], [#4115]);
one process-wide capacity controller governs concurrency, and the opt-in
batch_tasktool runs large collections of independent items as durable,
resumable SQL-backed batches with leases, retries, pause/resume/cancel, and
a chat progress panel ([#4998], [#5289]);task(context_mode="snapshot")
carries a dispatch-time copy of the parent conversation ([#5367]); and
subagent step history is persisted and displayed in the thread. ([#3845]) - Scheduled tasks grow up —
intervalschedules joinonceandcron
([#5291]); upcoming cron occurrences can be previewed before saving
([#5381]); run history filters server-side by status and pages backwards in
the UI ([#5384], [#5363]); tasks can pinlead_agentor a custom agent
([#5286], [#5288]); busy occurrences queue durably across restarts
([#4918]); and multi-instance recovery no longer interrupts live runs.
([#4713]) - Pluggable memory — new OpenViking, mem0, and Honcho backends over HTTP
([#4509], [#4528], [#4730]); a built-in FTS5/BM25 retrieval adapter
([#4360]); LLM-assisted consolidation and staleness pruning ([#3996],
[#3860], [#4143]); incremental per-agent fact storage ([#4279]); a hybrid
eviction policy ([#4789]); guaranteed correction-fact injection ([#3592]);
and opt-in write-side fact dedup. ([#5254]) - More sandboxes, tighter control — new E2B, BoxLite (micro-VM with warm
pool), Tenki, and OpenSandbox providers ([#3883], [#3940], [#3951], [#4382],
[#4877]); opt-inisolated/ domain-allowlistnetwork egress for local
Docker sandboxes, with denied domains approvable through the Human Input
card ([#5152]); and hardened local containers — bridge-gateway port binds,
default seccomp, dropped capabilities. ([#4986]) - Out-of-tree extensions — Python extensions contribute middleware,
lifecycle and system-model observers, Gateway services, and HTTP routers,
managed withdeerflow extensions install/upgrade/enable/disable/remove
([#4636], [#4684], [#4780], [#5347]); a 0.2 extension API lets extensions
observe what the agent did ([#4863]); and a newRunEvidenceReadercontract
drives durable, cursor-based changed-run discovery. ([#5405]) - Enterprise auth & authorization — generic OIDC/SSO with Keycloak support
([#3506]); personal access tokens with scoped route policies ([#5041]); a
built-in RBAC provider with tool, model, and sandbox authorization enforced
at both assembly and runtime ([#4260], [#4370], [#4540], [#4911], [#4439]);
local self-registration can be closed to SSO-only provisioning ([#4311]);
and account preferences survive a cleared browser. ([#5397]) - MCP as production infrastructure — a durable task runtime survives
Gateway restarts and reports progress in the chat UI ([#4665], [#4690],
[#4833]); shared servers can inject per-user credentials or map
request-scoped secrets to headers ([#4868], [#5010]); servers are managed
from Settings ([#5022]); and a hung stdio server can no longer stall the
Gateway or agent assembly. ([#4657], [#5217]) - Richer runtime — per-run token budgets shared additively across the lead
agent and subagents ([#3412]); goal continuations with a tracked, capped
count ([#3858]); dual-mode checkpoint storage cuts long-run thread storage
from O(N²) to near-linear ([#4292], [#4638]); durable context survives
summarization ([#3556], [#3887], [#3906]); opt-in task notes and
compacted-history recall ([#5382]); a run can read referenced earlier
conversations, grantable from the SDK and the composer ([#5399], [#5463],
[#5465]); structured clarification form fields ([#4406]); and configurable
recursion limits for Gateway and scheduled runs. ([#5390], [#4848]) - Models & knowledge — per-agent model and generation settings ([#4347]);
an optional request-admission limiter paces calls per provider ([#5432]);
per-user model favorites ([#5441]); a Z.AI GLM-5.3-Flash profile and MiniMax
Code ACP support ([#5074], [#4846]); opt-inknowledge_searchover RAGFlow
or LightRAG ([#4955], [#5209]); Playwright-backed agentic browser control
([#4187]); and new search providers — Serply, Tencent Cloud WSA, Sofya,
GroundRoute, Crawl4AI, fastCRW, and Parallel — with native recency filters.
([#5023], [#5057], [#5099], [#5239], [#3675], [#3821], [#3585], [#3881],
[#3866], [#5028]) - Workspace — Projects organize chats, with per-project instructions, a
document shelf, and two-way file promotion ([#5265], [#5443]); assistant
turns branch into side conversations with distinguishing titles ([#3950],
[#3934], [#4983]); the latest answer regenerates and user turns edit and
rerun in place ([#3637], [#4377]); chats archive, restore, and pin
([#5236], [#4442]); a conversation outline navigates long chats ([#5025]);
CSV/TSV artifacts preview as tables ([#5284]); text artifacts stream over
byte ranges and a run's files download as one zip ([#5056], [#5117]);
MCP servers, integrations, and skills move into a dedicated Capability
Center ([#5468]); and Custom Agents get display names, a deployment-level
subagent catalog, and statelessmemory_enabled: falsemode. ([#5324],
[#4887], [#5167]) - Channels — a new Buzz (Nostr) connector ([#4649], [#4727]);
/agent list//agent useIM commands switch a conversation to the owner's
Custom Agents ([#5168]); Postgres-backed webhook dedup lets several pods
serve the same channel ([#4210]); and DingTalk gains file/image
attachments. ([#4423])
🚀 Performance
- Dual-mode checkpoint storage with LangGraph
DeltaChannelcuts thread
storage from O(N²) to near-linear for long research/coding runs. ([#4292]) - Chat streams request
messages-tuple+updates+custominstead of full
valuessnapshots — retransmitted history was ~75% of SSE payload. ([#5159]) - Index
MemoryRunStorebythread_idandMemoryRunEventStoreevents by
run_idto eliminate O(n) scans. ([#3562], [#3686]) read_filereads only the requested line range from the sandbox instead of
fetching the whole file first. ([#3824])view_imageinjects content viawrap_model_call, so up to 20 MB of base64
no longer sits in two checkpoints per viewed image. ([#5014])- Cache sandbox path-rewrite and output-masking regexes per instance.
([#3648], [#3713]) - Frontend: coalesce streaming renders to a frame budget, stop re-deriving
message content on every chunk, cache settled copy-data derivation, and
enforce route JS/CSS budgets. ([#4425], [#4441], [#5095]) - Browser Live frames encode as JPEG, cutting progress payload size. ([#4836])
- Bound gateway memory after terminal runs. ([#5112])
- Deduplicate streamed AI messages via a seen-id set (O(n²) → O(n)). ([#3687])
- Index tool-call results per group. ([#4411])
🔒 Security
- Skill review gate — SkillScan now receives every file byte for byte
(binaries, nested archives, and NUL bytes no longer escape scanning),
archive extraction is capped by member count as well as size, and installer,
export guard, and scanner share one code-file/executable-magic definition.
([#5431], [#4241]) - Prompt-injection defenses — new input-sanitization middleware with both
bypasses closed; untrusted content in model prompts (memory facts,
SOUL.md, subagent descriptions, skill metadata) HTML-escaped; MindIE
tool-response framing escaped; andweb_captureand MCP-sourced tool
results sanitized through the same trust boundary as the built-in web tools.
([#3662], [#5375], [#4028], [#4253], [#4839]) - Sandbox hardening — local Docker sandboxes bind published ports to the
Docker bridge gateway, run Docker's default seccomp profile, drop all
capabilities, and getno-new-privileges;SSH_AUTH_SOCKis scrubbed from
the sandbox environment; and projected skill files are copies, not
hardlinks, so a sandboxed write cannot mutate the canonical source.
([#4986], [#5145], [#4825], [#4830]) - Secrets — inherited secret environment variables are scrubbed from the
skill environment; MCP stdio launcher arguments and env vars are constrained
at the config API; credentials that cannot travel as HTTP header values are
rejected at the config boundary; and skill toggles no longer persist
resolved$VARsecrets intoextensions_config.json. ([#4018], [#4617],
[#5066], [#5357]) - Artifacts — the outputs-only write guard is no longer fooled by
percent-encoded dot segments or symlinks, and XML artifacts (any+xml
type included) are served as download attachments so active content cannot
call the API with the viewer's session. ([#5321], [#5353]) - Authorization — an empty tool allowlist now denies instead of failing
open; run-create is enforced on stateless stream/wait endpoints; a revoked
sandbox:executegrant is re-checked before sandbox reuse; custom-Agent
skill allowlists are enforced at the sandbox filesystem level; and
cancel/rollback actions on GET stream joins are rejected with 405.
([#4067], [#5030], [#5006], [#5077], [#5092]) - Other — SSRF guard for self-hosted
web_fetchproviders; Lark CLI
credential trees enforce private ACLs on Windows; and streamdown
sanitization is restored in custom rehype chains. ([#3942], [#5141], [#4987])
🐛 Notable fixes
- Runs & runtime — cancel a run from any live gateway worker, not only the
owner; cross-worker idempotent reuse no longer permanently blocks the
thread; keyed retries resolve the request user consistently; the shutdown
run drain survives repeated cancellation; and a repair migration heals
databases that silently skipped the run-change clock schema. ([#4500],
[#5393], [#5401], [#5487], [#5517]) - Middleware — loop detection keys
read_fileby exact line range, so
paging through a file no longer trips the hard stop;max_turnsnow grants
the turns it names (it was passed as LangGraph super-steps, ~7–8 per turn);
token budgets hold across goal continuations; guards that remove tool calls
no longer break every later Claude/Responses turn; and retried model calls
re-deliver queued warnings. ([#5486], [#5485], [#5410], [#5447], [#5433]) - Subagents — a subagent keeps its instructions after context compaction;
a delegated subagent's error no longer fails the parent run; repeatedly
cancelled subagents no longer leak their execution slot; and Windows
acceptance checks fail closed on out-of-scope commands. ([#5454], [#5407],
[#5477], [#5162]) - Sandbox tools — remote
list_dir/glob/grepreport failures
instead of inventing "empty directory" or "no matches";read_file
truncation is reported in lines with the exact resume point; host-path
masking handles$PATH-style joins and forward-slash Windows spellings;
concurrent subagents work past the AIO shell-session ceiling; and CJK tool
output is no longer garbled in PowerShell. ([#5264], [#5422], [#5380],
[#5474], [#5418], [#5373], [#5178], [#5440]) - Models — the Claude Code OAuth token is read once per process, so title,
summarization, and subagent models stop losing their credential; models with
supports_reasoning_effortno longer fail to build; Codex invalid tool
calls are paired with their results; andapi_baseis honored on every
BaseChatOpenAIsubclass. ([#5411], [#5403], [#5509], [#4146]) - Channels — WeCom clips and splits over the 20 KB protocol cap instead of
dropping the reply; one undecodable WeChat message no longer drops its
batch; a dead Discord client no longer hangs outbound sends and freezes the
channel pool; Telegramrich_messagesrenders only when the text actually
contains rich constructs; and WeChat/WeCom inbound media is streamed,
size-bounded, and host-allowlisted. ([#5148], [#4231], [#5227], [#5470],
[#5225]) - Skills & secrets — toggling a skill no longer writes resolved secrets
intoextensions_config.json; restore$VARreferences and rotate any
credential exposed this way. ([#5357]) - Scheduler — the global
max_concurrent_runsbudget is enforced on
SQLite (not just Postgres) and for manual triggers; and a dispatch race
that could launch two runs for one task is closed. ([#5469], [#4769],
[#4105]) - MCP — parallel synchronous calls to one stdio server no longer cancel
each other's connection; the session pool holds its capacity limit under
concurrent initialization; and durable task polling preserves pooled
sessions across protocol timeouts. ([#5396], [#4962], [#5027]) - Frontend — message order stays stable across long runs and reconnects;
human-input cards keep the turn that requested them; the user's input is
restored after an incremental stream reconnect; sidebar chat deletion asks
for confirmation first; and the client emits a streamed tool call once, with
its complete arguments. ([#5293], [#4892], [#5428], [#5406], [#5408])
📦 Deploy & ops
- Docker — the published entry port binds loopback by default (see
breaking changes);make upwaits for a real Gateway health probe before
declaring the stack ready; startup tolerates a missing.env; and Windows
Git Bash preflight and socket handling work. ([#4618], [#4658], [#4806],
[#5371], [#5402]) - Kubernetes — per-sandbox Services default to
ClusterIPinstead of
NodePort, so sandboxes are reachable only inside the cluster ([#4190]);
ClusterIP Services and scoped per-skill PVC mounts ([#4016], [#3928]); and
an optional Lark credential broker sidecar keeps app secrets out of the
sandbox filesystem. ([#4501]) - Health & readiness — the new
GET /health/readyruns a bounded database
probe and returns 503 while the database is unreachable;/healthstays
pure liveness. ([#5166]) - Nginx — thread routes that wait on a model call allow 600 seconds (a
slow/compactno longer returns 504 for work that was applied), and long
chat prompts pass/api/langgraph/without a raw 500. ([#5505], [#4277]) - Configuration — a custom PostgreSQL schema is selected via
postgres_schemaand created automatically ([#3442]);recursion_limitand
scheduler.recursion_limitare deployment-configurable ([#5390], [#4848]);
andmake devpreserves theollamauv extra across restarts. ([#5318]) - Upgrades — startup tolerates a database migrated to the reviewed newer
revision, keeping rollback possible ([#5219]); legacy threads get run-event
seed backfill ([#4590]); and Postgres connections survive idle timeouts via
pool_recycle. ([#4230]) - CI & packaging — the backend unit-test workflow splits into four
parallel shards with isolated Postgres/Redis ([#5137]); and the renamed
tenkipackage replaces the PyPI-removedtenki-sandbox. ([#5087])
🙌 Thanks
Huge thanks to the 178 contributors who landed 772 merged PRs in the 2.1.0
milestone, and to everyone who filed issues, tested builds, and shared
feedback. DeerFlow 2.1 wouldn't exist without you.
In alphabetical order:
- @0717lee — Fengmin Li
- @ajayr
- @alanhuangyoo
- @Amazingjun-j — Jun
- @angus-guo — gus
- @aniketwaghh — Aniket Wagh
- @AnnaSuSu — Wenchao An
- @AnoobFeng
- @AoHanBei
- @axsapronov — Aleksandr Sapronov
- @AZE98 — 阿泽
- @Baldwinzc
- @Beautyl0ve
- @belharethsami — Sami Belhareth
- @BetterAndBetterII — Yuzhong Zhang
- @betterkite
- @Beverly621
- @bjtolo
- @BlueX888 — 哈基米
- @Boooobby
- @chaoxi007
- @chengjoey
- @chenjiahan — Jiahan Chen
- @chetan655 — Chetan Sharma
- @chuenchen309 — Andrew Chen
- @codeingforcoffee
- @CorgiBoyG — RongJie G
- @Creeper998
- @cuishuang — cui fliter
- @CyanYuMu
- @cybersentia
- @cyberspace-cs — buleboy
- @Czile-create — Czile
- @d33kayyy
- @dajiaohuang — Wu Shuwen
- @DaoyuanLi2816 — Daoyuan Li
- @dcaldr — Dan Caldr
- @deepcoldy — DeepCold
- @DengY11 — Yi Deng
- @diegodscamara — Diego Câmara
- @DorianZheng
- @ech0hol — Zhipeng Zheng
- @ehz0ah — z1gon
- @Eilen6316 — Eilen Shin
- @fallintoplace — Minh Vu
- @fancyboi999 — Xinmin Zeng
- @FanouZeng-TT
- @felix-windsor — Felix Wang
- @fgoll
- @fszcd — GGbond
- @georgeatparallel — George Pickett
- @georgelichen
- @ggnnggez — Nan Gao
- @GodBlf — Xuehao Xu
- @goloisme
- @googio — Serply
- @haimingZZ — Chris Z
- @HaotianChen616
- @hata33 — hataa
- @he-yufeng — Yufeng He
- @heart-scalpel
- @hetaoBackend — DanielWalnut
- @Huang-404-Q
- @Huixin615
- @hyeonsang010716 — Hyeonsang Cho
- @icn5381
- @imohammedansari — Mohammed Ansari
- @IshaanPotle — Ishaan Potle
- @jamespud — spud
- @Janlaywss — Janlay
- @Jholly2008 — Jholly
- @jianpingpei — muguo
- @jiaqiang000 — jiaqiang0000
- @jie101234 — jie
- @jp0xz
- @kapil971390
- @kassdinzheng123 — Zheng Haoran
- @KevinAndrewDong — dong
- @kongxiangxin — 明年我18
- @KXHXK — KXH
- @Leeminjing — Lee minjing
- @LittleChenLiya — Admire
- @liunianxuxie
- @LKL-ZREO
- @lllyfff
- @lucky798213 — blue
- @luojiyin1987 — luo jiyin
- @ly-wang19
- @lyxnbclass — shawn
- @March-77
- @MeiSiristhebest — Nefelibata
- @MeloMei
- @MiaoRuidx
- @Michael-Yu2978 — Michael
- @ming1523
- @Miracle778
- @mvanhorn — Matt Van Horn
- @nankingjing — 黄云龙
- @NewAmorend — Amorend
- @nicochow
- @nothingyuancando — Tsai Yuan
- @now-ing
- @Osamaali313 — Syed Osama Ali Shah
- @parthiban-sivakumar — Parthiban Sivakumar
- @patrick-andstar — Wu JiaCheng
- @pclin1212 — pclin
- @PeaceMaker-best
- @PiedPiper911
- @poijygfdyy — NanPan
- @praxstack — Prax Lannister
- @pwd11 — wd_pan
- @qin-chenghan
- @qingbo1011
- @rain02333z-spec
- @ranxi2001 — Onefly
- @rayhpeng
- @richardmilles
- @Ricky-7-Yan
- @RongfuShuiping
- @ruirui6946 — yang rui
- @RykerFeng — Ryker_Feng
- @ShenAC-SAC — AochenShen99
- @ShiroKSH — Kushida
- @ShitK
- @shoemoney — Jeremy Schoemaker
- @Shxiao101 — Shxiao
- @simpleqt — 陈志谦
- @sontianye — Tianye Song
- @sqsge
- @starslittle
- @sunshine-lang — Sunshine
- @Syt3s
- @Terminator666666
- @thefoolgy
- @therenansimoes
- @tiammomo
- @TNsparrow — Mason Zhou
- @Totoro-qaq — Totoro
- @Tsubaki-01 — Weng Qiang
- @TuNaiChao — Tu Naichao
- @tvost2 — Otavio Rodrigues Santana
- @tzlwn1 — SPEC
- @Undermoon1412
- @us — Recep S
- @Uygniqoar — Vicki
- @vantanco
- @Vanzeren — Zeren Wang
- @VectorPeak
- @wcy12378 — Kris
- @whhe — He Wang
- @WillemJiang — Willem Jiang
- @winklemad — Madan Kumar
- @Wsp030914 — Roc
- @Wuong
- @wutongyuonce — 梧桐雨
- @xiaodu55
- @xiaoqianbaobao — qian
- @xiawiie — Wei
- @XIIRUAN
- @yeejhyang
- @yjchen101
- @yong326 — yong
- @yu-xin-c — Stellar鱼
- @yusufgurdogan — Yusuf Gürdoğan
- @yym36991
- @YZJF
- @zaoshangduziteng — 早上肚子疼
- @ZenCGL — ChenglongZ
- @zeng-bohan
- @ZeroMadLife — ChiHaYa
- @zhangbububu — Keswyk Cheung
- @zhangwei-way
- @Zhengcy05
- @zhernrong92
- @zhfeng — Zheng Feng
- @zhuiyueya — ChaseMoon
- @zkforge — Zhou Kai
- @zwj110610 — zgenu
See the full author and PR list on the
milestone page.
DeerFlow 2.0.0
DeerFlow 2.0 is a ground-up rewrite around a "super agent" harness that
orchestrates sub-agents, persistent memory, sandboxed execution,
and an extensible skills/tools system. It shares no code with the 1.x line,
which lives on the main-1.x branch.
This release closes the 2.0.0 milestone
with 182 merged PRs since the first 2.0 milestone tag.
📖 Full notes: CHANGELOG.md · 中文版
⚠️ Breaking change
- Run hydration — runs now hydrate from
RunStoreand persistinterrupted
status. Cancellation now requires the worker who owns the run; cross-worker
cancels return409instead of silently appearing successful. ([#2932])
✨ Highlights
- Custom agents that update themselves — agents can persist edits to their
ownSOUL.md/config.yamlfrom a normal chat, with full per-user
isolation. ([#2713]) - User-owned IM channel connections — users can bind their own Slack,
Telegram, Discord, Feishu/Lark, DingTalk, WeChat, and WeCom accounts on top
of operator-configured bots. ([#3487]) - More models & community search — StepFun and MiMo reasoning models,
MiniMax for image/video/podcast skills plus a new music-generation skill,
and Brave Search / SearXNG / Browserless / Serper Google Images tools.
([#3461], [#3298], [#3437], [#3528], [#3451], [#3575]) - Richer channels — Discord gets mention-only mode, thread routing, and
typing indicators; Telegram streams replies by editing the placeholder
message in place. ([#2842], [#3534]) - Configurable loop detection with per-tool frequency overrides and
deferred warning injection. ([#2586], [#2711], [#2752]) - Subagent token usage streams to the header in real time, with spans
attributed to the parent thread's Langfuse trace. ([#2882], [#3611]) - Trace polish — clean
lead_agent/ custom-agent trace names;session_id - Token-usage tracking on by default, with refined display modes and usage
attributed to the actual models. ([#2841], [#2329], [#3658]) - Flexible memory & suggestions — opt out of tiktoken in restricted
networks viamemory.token_counting; make AI follow-up suggestions optional.
([#3465], [#3591])
🚀 Performance
- Push thread metadata filters into SQL. ([#2865])
- Index runs by
thread_idinRunManagerto eliminate O(n) scans. ([#3499]) - Index messages in
MemoryRunEventStoreto eliminate O(n) scans. ([#3531]) - Cache
Base.to_dictcolumn reflection per class. ([#3654]) - Speed up
should_ignore_namein glob/grep sandbox walks. ([#3657])
🔒 Security
- Reject symlinked upload destinations on Linux and Windows.
([#2623], [#2794]) - Mask sensitive values in MCP config responses; harden the endpoint.
([#2667], [#3425]) - Reject cross-site auth POSTs. ([#2740])
- Cap skill artifact preview decompression (zip-bomb defense). ([#2963])
- Mount the host Docker socket only in aio (DooD) sandbox mode. ([#3517])
- Don't bind-mount host CLI auth dirs by default. ([#3521])
🐛 Notable fixes
- Memory runs on a persistent event loop instead of a short-lived one
asyncio.run(); queued updates isolated per agent; wrapped JSON responses
parsed correctly. ([#2627], [#2941], [#3252]) - Runs hydrate from the persistent store after a gateway restart, return
ISO 8601 timestamps, and have an idempotent cancel. ([#2989], [#2599], [#3058]) - Subagents isolated from the parent run's checkpointer; timeout terminal
state atomic; respect model overrides for tools/middleware. ([#3559],
[#2583], [#2641]) - Sandbox readiness polling no longer blocks the event loop;
/mnt/user-datacontract enforced at the API boundary; PVC data scoped per
user; Windows/Git Bash MSYS path conversion disabled. ([#2822], [#2881],
[#2973], [#2766]) - Auth auto-generated JWT secrets persist across restarts; setup-status
uses cached responses instead of 429. ([#2933], [#2915]) - Frontend fixes a swallowed first message, login flicker / resize-observer
loop, duplicate optimistic messages, deeply nested list render crashes, and
thread isolation on new chats. ([#2731], [#2954], [#3002], [#3393], [#3570],
[#3508]) - Channels — user-owned IM now requires a bound identity, scopes files, and
helper commands to the owner, makes the provider state authoritative, and makes
The connect flow is deterministic, backed by shared retry helpers and
operational guardrails. ([#3578], [#3579], [#3580], [#3581], [#3582],
[#3583], [#3584]) - Streaming & history — interrupts propagate through SSE values events for
the LangGraph SDK, and base64 image payloads are stripped from streamed and
history responses to keep the UI responsive. ([#3605], [#3631], [#3535]) - Frontend (more) — the workspace chat list paginates beyond 50 threads,
stays interactive when the SSR auth probe can't reach the gateway, and gets a
mobile-friendly layout. ([#3485], [#3495], [#3646])
📦 Deploy & ops
- Docker Gateway defaults to a single worker (multi-worker breakage).
([#3475]) - Docker nginx resolves upstream names at request time. ([#2717])
- Packaging adds
postgresextra for store/checkpointer support. ([#2584]) - Scripts preserve
uvextras acrossmake devrestarts; clean up local
nginx on stop; exclude runtime state from gateway reload. ([#2767], [#3005],
[#3426])
🙌 Thanks
Huge thanks to the 40 contributors who landed 180 merged PRs in the 2.0.0 milestone, and to everyone who filed issues, tested builds, and shared feedback. DeerFlow 2.0 wouldn't exist without you.
In alphabetical order:
- @18062706139fcz — Ryker_Feng
- @64johnlee — john lee
- @airene — Airene Fang
- @AnoobFeng — AnoobFeng
- @chetan655 — Chetan Sharma
- @ech0hol — Zhipeng Zheng
- @Eilen6316 — Eilen Shin
- @fancyboi999 — Xinmin Zeng
- @ggnnggez — Nan Gao
- @greatmengqi — greatmengqi
- @hata33 — hataa
- @heart-scalpel — heart-scalpel
- @he-yufeng — Yufeng He
- @hetaoBackend — DanielWalnut
- @Hinotoi-agent — Hinotobi
- @Huixin615 — Huixin615
- @idefav — idefav
- @jinghuan-Chen — jinghuan-Chen
- @Kiteeater — KiteEater
- @kibabsquirrel — Lawrance_YXLiao
- @knight0940 — Amorend
- @Layau-code — YuJitang
- @liuchuan01 — liuchuan01
- @LittleChenLiya — Admire
- @ly-wang19 — ly-wang19
- @NewAmorend — Amorend
- @nguyen0096 — Nguyen DN
- @p-yf — yangyufan
- @player0718 — Lucy Shen
- @ShenAC-SAC — AochenShen99
- @shenlihust — 魔力鸟
- @sunshine-lang — sunsine
- @stphtt — stphtt
- @wahajahmed010 — Wahaj Ahmed
- @whhe — He Wang
- @WillemJiang — Willem Jiang
- @xunliu — Xun
- @yangzheli — yangzheli
- @yitang — Yi Tang
- @Yuyi-Ao — Yuyi Ao
- @zengxi — zengxi
- @zwj110610 — zgenu
See the full author and PR list on the
milestone page.
@ Every self-hosted release, weekly
One Monday email with the week's stable releases across the directory.
More in AI Agents
DeftSelf-hosted workspace unifying chat, tasks, knowledge, calendar, and AI agents. Docker Compose deploy, BYO AI providers, MCP for agent access. AGPL-3.0-only, alpha.
DeskRPGA self-hosted 3D workspace where Hermes AI profiles become desk-dwelling coworkers that chat, meet, tackle kanban tasks, and run scheduled jobs in a shared office.
difyDify is a self-hosted, open-source LLM app platform with visual workflows, RAG pipelines, agents, and model management for taking AI apps from prototype to production.
disp8chSelf-hosted AI workspace turning plain English into visual workflows, multi-agent ops, cited research, and design artifacts — runs offline with local models.
DodaiosSelf-hosted open-source AI assistant for desktop and headless servers. Coordinates coding agents, voice control with wake word, 40+ tool integrations, all data local.
dograhSelf-hosted open-source voice AI platform: build phone agents in a visual workflow editor with BYOK LLM/STT/TTS and telephony — an alternative to Vapi and Retell.
DormiceDormice is a self-hosted, E2B-compatible sandbox platform for AI agents. Permanent sandboxes freeze when idle (~5 MiB RAM) and wake in ~50ms. Single binary deploy.
dotcraftDotCraft is a self-hosted, open-source AI agent runtime on .NET with desktop, CLI, Android apps sharing one workspace, plus server deployment and embeddable harness.
DSH MobileSelf-hosted Android app running DeepSeek Harness AI agent locally without root or Termux, with 19 built-in toolchains and accessibility automation.
duragraphDuraGraph is a self-hosted, open-source control plane for durable AI agent workflows. It uses event sourcing and CQRS to make every run replayable and crash-safe.
e2bOpen-source sandboxes with JS and Python SDKs for running agent code in isolated Linux VMs; self-hosted via Docker Compose, Terraform, or Kubernetes on one machine.
edictum-consoleSelf-hosted operations console for AI agent governance with contract management, human-in-the-loop approvals, audit event feeds, and fleet monitoring.
0 comments