langgenius/dify 1.18.0

v1.18.0 — Smarter Agent Routing, Portable Apps, Deeper Workflow Visibility

on GitHub

Docker Compose

Once the 1.18.0 release images and tag are published, stop the old stack gracefully, switch to the release, merge the configuration changes above, and pull/start the new stack:

cd dify/docker
docker compose stop -t -1
git fetch --tags
git checkout 1.18.0
# Merge required configuration changes into existing env files here.
docker compose pull
docker compose up -d

Keep database migrations enabled (MIGRATION_ENABLED=true) for the API startup, or run them through your managed migration process before starting new workers. The bundled Weaviate update from 1.17.1 is a patch update within 1.39. If coming from a version that still runs Weaviate 1.27, complete the 1.17.1 staged Weaviate upgrade first.

Source Deployments

Use Python 3.13 for the API, Node.js 24.22.1 or later in the 24.x line, and pnpm 12.10.1. Refresh the locked dependencies and apply the database migrations from the repository root:

uv sync --project api --frozen
uv run --directory api flask db upgrade
pnpm install --frozen-lockfile

Rebuild the web application and restart API, worker, scheduler, and Agent services from the same release. If deploying Agent Backend separately from source, refresh its locked server dependencies as well.

difyctl

Install the matching 1.18.0 client. Its v2 implementation does not reuse v1 login state:

difyctl login --server https://your-dify.example.com
difyctl help

Update scripts to the current server-discovered command surface. The old mode-agnostic /openapi/v1/apps/{app_id}:run route is replaced by per-mode operations; use the catalog instead of hard-coded v1 routes. Refresh installed agent skills with difyctl install skills <dir>. (#42487, #42608, #43819)

• Published triggers: the draft-sync fix does not repair subscriptions already removed before upgrading. Rebind missing subscriptions and republish affected workflows as needed. (#44068)
• Document extraction: re-import/re-index affected content to apply extraction fixes to existing documents.
• Built-in document metadata: toggling built-in fields rewrites only enabled, non-archived documents whose indexing is complete. Other legacy rows can retain the old format and need a later rewrite when eligible; this release does not include a full backfill. (#44218)

Agent Knowledge Base and KnowledgeFS

• Add the Beta knowledge-space experience with local upload preview, connected-source management, document availability and metadata, retrieval history/research, and quality evaluation. Settings control app, Agent, and Service API access. Classic Knowledge remains supported alongside it. (#44165)
• Knowledge Retrieval v2 and Agent knowledge bindings use scoped capabilities; published Explore runs reuse published bindings without requiring ordinary viewers to reconfigure access. (#44165)
• Classic Dataset upgrades have durable checkpoints, availability/metadata reconciliation, retry protection, and recovery through Beat. Run the dedicated upgrade worker with the documented prefork pool and task limits; apply b9d3f7a5c102 before restarting API/workers/Beat. Opting into the service does not automatically migrate all Classic datasets. (#44165)

Portable App Packages

• App exports now default to .ifpkg, bringing the application configuration and its supported resources into one portable package. Explicit YAML export remains available, and imports accept both formats from files or URLs. (#42066, #42189, #42425, #42552)
• Workflow and Chatflow packages include inline Agents, their Skills, and files from each node’s bound configuration snapshot. Imports recreate those Agents in the destination workspace and remap their resources. App icons, Site settings, and node plugin dependencies are included in the export flow. Missing resources are reported during import. (#42579, #42626, #42816, #42863, #42913)
• Agent exports can target a published version. Agent version menus now offer Restore, and pending draft saves finish before restoration so autosave cannot overwrite the restored configuration. Skill duplication and export use the latest saved draft content. (#42485, #42567, #42424, #42502)

Nested Workflow Tools and Trace Drilldown

• Called Workflow Tools run as child graphs under the workflow engine, with coordinated pause, resume, stop, and file outputs. Source graphs are captured before execution, so republishing a tool does not change an in-flight run, including calls inside loops and iterations. (#40277, #42820)
• Workflow, Chatflow, and history views can open a particular tool invocation and navigate its internal execution traces. Access to each source application is required before its details are returned. Human Input forms are tracked by execution identity, including repeated invocations of the same node. (#42819, #42821, #42822)
• Nested Agent logs and usage records retain their source workflow identity and their relationship to the outer run. Nested usage and step totals can still be approximate, particularly after pauses or stops. (#42824, #42820)

Agent Output Routes and Streaming

• Agent v2 nodes can select a workflow branch as part of completing their task. Enable Output Routes, define at least two branches and their selection conditions, and use the read-only switch output to inspect the chosen route. With routing disabled, the normal success outlet remains available. Routed nodes support stopping on error or taking a failure branch; node-level default-value handling is unavailable with routes enabled. (#42599)
• Plain Agent v2 nodes stream text as it is generated. Structured or routed results remain buffered, and nodes using default-value error handling stay buffered so the configured fallback can still replace a failed result. (#43986)

Build and Manage Apps with OpenAPI and difyctl

• /openapi/v1 publishes a server operation catalog. difyctl discovers commands and their input fields from that catalog, provides searchable help, and follows server-provided next steps. Workflow and Chatflow authoring now covers app creation, DSL import/export, settings, environment variables, publishing, and version restoration. Draft hashes protect imports from overwriting concurrent edits. (#42487, #42608, #43067)
• The CLI includes a difyctl skill for agents building Dify apps. Install it with difyctl install skills <dir>. Device login supports --no-wait and --resume, and folder uploads send one multipart part per file. (#43819, #44356)
• Workspace owners can create resource access tokens bound to selected apps or knowledge bases. Tokens work with the supported Service API routes and app operations in difyctl; they do not grant workspace administration. The Settings entry is opt-in through NEXT_PUBLIC_ENABLE_ACCESS_TOKEN, which defaults to false. (#42293, #44422)

Edit Agent Prompts from the Sandbox

• dify-agent config prompt pull [--to PATH] and push [PATH|-] read or replace the raw system prompt, preserving UTF-8, whitespace, and mention markers. Empty text clears it. Only the current account’s writable build draft can be changed; later requests use the saved prompt. (#44561)

Agent Execution Tracing

• Agent apps and Workflow Agent v2 nodes can export their Agent, model, and tool execution trees through the existing tracing providers. Monitoring adds shared tracing configuration, delivery status, retry controls, and links to the trace belonging to the selected execution. Agents referenced by a Workflow inherit the caller’s tracing policy. (#44144, #44186)
• Application tracing is opt-in on both the API and Agent Backend. A separate deployment-wide OTLP trajectory exporter is also available, independently of system tracing. (#42651, #44144)
• Called Workflow Tools’ internal nodes are excluded from external exports because those exports have no viewer identity for source-app access checks. Agents inside those called tools are also excluded from the new execution-tree export for now; authorized Console drilldown remains available. (#42823, #44144)

OpenShell Sandbox Backend and E2B Usage Collection

• Agent execution can use a self-hosted NVIDIA OpenShell gateway with DIFY_AGENT_RUNTIME_BACKEND=openshell. Each Binding has its own sandbox, with authenticated shell access, Home Snapshots on an operator-managed shared volume, and an optional egress allowlist. OpenShell gateway 0.0.106 or newer and a compatible runtime image are required. (#41076)
• OpenShell lease release closes the connection but leaves the sandbox running. There is no automatic idle-stop or sandbox TTL; operators must manage those resources. Multi-tenant deployments require separate OpenShell workspaces and snapshot volumes per tenant. See the OpenShell deployment guide.
• Optional E2B usage collection records provider execution duration and resource sizes through Celery Beat and the ops_trace queue. Collection starts from a configured activation time and does not backfill earlier executions. Both the API and Agent Backend metering flags default to off. (#42554)

Cloud Access Controls, Templates, and Archive Management

• Reusable network access groups let supported Cloud deployments share IP rules across apps, with permission checks, effective-policy status, and trusted client-IP previews. Enforcement depends on the Cloud policy service and Gateway; this is not a standalone Community Edition firewall. (#41025, #44464)
• Cloud users can preview and try published Agent templates before importing them. Agent “Create from Template” is hidden in Community and Enterprise editions because its template data source is Cloud-only. (#42837, #44035)
• In Cloud Workflow Log Archives, workspace owners can permanently delete a selected month, with confirmation, progress, and retry. The action removes archived objects and prepared ZIP downloads; live workflow-run records are outside its scope. Failed deletion jobs now enter the retry policy instead of reporting success. (#44052, #44061, #44203)

• Knowledge performance: dataset lists and indexing status use batched queries; segment imports avoid repeated position queries; retrieval and result post-processing reduce repeated lookups. (#42279, #42191, #42233, #42673, #43665)
• Faster loading: translations load by feature, workflow configuration panels load on demand, and chart, music, and SVG previews defer heavier work. Chat history no longer loads saved prompts that are not needed for display. (#42812, #42873, #42874, #42877, #42970, #42840, #42951, #44521)
• Navigation and accessibility: improved command discovery, keyboard navigation, focus return, dialog labels, and responsive layouts across Studio, workflow editing, Knowledge, Agent configuration, and workspace settings. Studio filters survive navigation, timezones are searchable, and workflow image export has a dedicated toolbar action. (#43133, #44330, #44429, #43944, #43662, #44220, #44378, #44492, #44535, #44539, #44548, #44564)
• Floating controls: menus, selectors, popovers, and tooltips now use Base UI positioning directly, with migrated alignment and offset settings throughout the console. (#44588)
• Date, time, and icons: redesigned date/time pickers, native scrolling for time options, and an updated icon picker with image cropping and self-hosted emoji assets. (#43090, #43723, #43007, #42469)
• Localization: Azerbaijani (az-AZ) joins the supported UI languages, with additional translation and right-to-left layout improvements. (#42291, #43808)
• Developer tooling: faster TypeScript checks through tsrs, plus typed Document and CustomizedSnippet models that preserve existing constructors and database defaults. (#44562, #36084, #40818)
• Operations: archive storage supports configurable S3 addressing style; the API image includes its spaCy model so startup does not need to download it; workflow generation logs identify tools omitted from the bounded fallback catalog. (#43066, #43601, #42596)

• Local sandbox authentication and isolation: enabled Local runtimes reject blank authentication tokens. When path isolation is enabled, a Landlock setup failure aborts the job with exit code 125 before executing user code. (#44152)
• Password hashing and plugin permissions: optional PASSWORD_PEPPER adds a server-side secret to account password hashes. Plugin installation defaults to workspace owners and administrators when no explicit policy is stored; existing saved policies remain in effect. Setting, changing, or removing the pepper invalidates existing password hashes. See the upgrade guidance. (ed772cfcf7)
• Access boundaries: exact CSRF whitelist matching, stronger dataset operation permissions, workspace-bound tracing service accounts, and protected owner/admin role handling. Re-inviting a removed member restores access without allowing the invitation to be reused after a later removal. (#42118, #42758, #44208, #43118, #43311, #43667)
• Knowledge sharing defaults: in RBAC-enabled deployments, new knowledge bases no longer automatically include every workspace member. (#42430)
• Error and plugin handling: API and webhook failures return fixed public messages instead of internal exception text, and plugin daemon requests use pinned package identifiers. (#43049, #44395, #44396)
• Dependency updates: bundled Weaviate moves from 1.39.2 to 1.39.13, alongside Next.js and other dependency security updates. The Weaviate change stays within the 1.39 series; the staged minor-version migration described for 1.17.1 still matters when upgrading from older installations. (#44508, #44127, #44148, #44524)
• The standalone Agent certifi bundle is updated to 2026.10.19; rebuild Agent images to consume the updated trust bundle. (#44462)
• NLTK: NLTK is updated to 3.10.4 for upstream path-handling hardening; this change alone is not a claim that every advisory is resolved. (#44581)

Workflow and Scheduling

• Preserve LLM prompt/model changes during collaboration and synchronize imported graphs correctly. Code generation retains input bindings for surviving parameter names, understands multiline/destructured signatures and Python parameters containing commas, and preserves literal {{inputs}} text in user code. (#42124, #42817, #44075, #44046, #44337, #43438)
• Remove unsupported Chatflow memory settings when pasting into a Workflow and when loading/saving Workflow graphs in the editor. Existing published versions or API-only flows are not rewritten by this editor fix. (#43597, #43752)
• Preserve configured fallback values when Code node outputs are removed, added, or renamed; require confirmation before saving an empty canvas; and retain in-run tool-file access for later nodes. (#42678, #43668, #41300)
• Persist task ownership and stop intent so late writes or a concurrent resume cannot revive a stopped workflow. Failed asynchronous trigger dispatches are recorded as failed in trigger logs, and elapsed time remains consistent across resumptions. (#40277, #43009, #44161)
• Scheduled fire-and-forget dispatch no longer creates a Redis result-backend drainer for every task group, preventing accumulating idle result connections. The same correction covers trigger refresh and pipeline dispatch. (#44551)
• Editing a draft no longer removes published trigger subscriptions. This prevents new damage but does not rebuild relationships already lost before the upgrade. (#44068)
• Save the timezone shown on new schedule nodes, handle daylight-saving transitions in next-run calculation and offset labels, and correct hourly previews at month boundaries. (#43532, #43357, #43627, #43925)

Agents and Skills

• Conversations can continue after cancelled tool calls; replayed tool-call IDs remain stable; parallel tool results stay attached to their own thoughts; and initial event-write failures finalize runs instead of leaving them running. Redis event replay also works with Redis 6. (#41846, #43796, #43843, #43959, #44420)
• E2B uses SDK 2.55.1 with safer retry behavior: resource creation is not replayed after an ambiguous 502, while safe lifecycle operations retain transient-failure recovery. Pauses and Home Snapshots explicitly request full-memory mode. (#43930)
• E2B sandbox acquisition checks that Home and Workspace resources exist, and confirmed-missing Enterprise Home Snapshots count as successful deletion. (#44014, #44085)
• Skill attachments preserve formatted DOCX text, RTF Unicode fallback lengths and binary boundaries, and PPTX presentation order. (#43718, #43789, #43893)
• RTF extraction also combines UTF-16 surrogate pairs before truncation and replaces unmatched surrogates, avoiding UTF-8 encoding failures. (#44565)

Knowledge and Retrieval

• Preserve CSV cell content, Notion mentions/equations, and newlines in recursive splitting. URL imports infer useful file extensions from content type, and unsupported pipeline file types return an explicit error. Re-import affected documents to regenerate content already indexed incorrectly. (#42159, #42171, #44179, #42364, #44012)
• Message citations retain document metadata. Built-in document dates use consistent UTC epoch values while preserving fractional seconds; existing mixed-format metadata is not automatically rewritten. (#41861, #44218)
• Re-enabling segments restores their vectors and refuses segments that have not completed indexing. Hybrid Search retains the reranking setting when saved from either dataset settings or app configuration. (#43865, #44017, #42563)
• Dataset deletion uses bounded cleanup steps with retry-safe progress. Qdrant balances results across keywords, TiDB-on-Qdrant filtering is corrected, Vastbase supports its graph index/BM25 paths, and OceanBase memory-limit discovery no longer depends on row order. (#38519, #44352, #44339, #42922, #42846)

APIs, MCP, and SDKs

• List endpoints calculate has_more from the page size actually served, and message pagination preserves records with tied timestamps. MySQL-specific datasource credential and installed-app ordering issues are corrected. (#41876, #42323, #42531, #44023, #44039, #44029)
• MCP discovery follows all tool pages with bounded requests, mixed-type parameters preserve list values, failed SSE connections close before HTTP fallback, and unsupported methods return protocol errors. MCP protocol support includes 2025-11-25. (#43842, #44182, #42761, #44197, #44066)
• The Node.js SDK handles workflow text chunks and message replacement, propagates streamed API errors, preserves SSE whitespace, and replaces headers case-insensitively. Write requests avoid automatic replay, and reused upload forms retain the explicitly supplied user. (#44177, #44199, #44083, #44090, #43079, #44120)
• difyctl preserves existing files if Windows replacement fails, surfaces SSE read failures, serializes token/config updates, and accepts BOM-prefixed JSON inputs. The PHP client uses the correct conversation rename endpoint and preserves custom API base-path prefixes with or without a trailing slash. (#43974, #43943, #44329, #44375, #44386, #43075, #44569)

Web App and Workspace

• Numeric zero and JSON object inputs keep their intended values. Browser-autofilled login credentials submit correctly, SSO failures are surfaced, and logout clears session state. (#43243, #42431, #44474, #43076, #43055)
• Log annotations apply to the displayed regenerated answer. Feedback drafts remain available when submission fails, and attachment previews keep their resources for the lifetime of the dialog. (#43238, #43520, #43521)
• Existing knowledge-base Add file pages retain their Knowledge sidebar in both standard and pipeline flows. (#44552)
• Knowledge metadata panels remain scrollable without covering their controls, dataset tag actions do not open the card, and Marketplace details open correctly for self-hosted editions. (#43621, #42269, #42576)
• Email normalization expands to Microsoft, Apple, and Proton addresses while retaining original stored email addresses; case-fallback account lookup works in both directions. (#42112, #42541)

Required or Changed Behavior

New Optional Settings

Removed Settings and Features

• GRAPH_ENGINE_MIN_WORKERS, GRAPH_ENGINE_SCALE_UP_THRESHOLD, and GRAPH_ENGINE_SCALE_DOWN_IDLE_TIME are no longer used.
• The older KnowledgeFS implementation removed in #44163 is superseded by #44165. Do not reuse its KNOWLEDGE_FS_JWT_SECRET or SSE timeout configuration; the new integration uses Capability v2 signing and public verification material. KNOWLEDGE_FS_ENABLED, KNOWLEDGE_FS_BASE_URL, and KNOWLEDGE_FS_TIMEOUT_SECONDS remain supported by the new configuration.
• The Console feedback export endpoint, GET /console/api/apps/{app_id}/feedbacks/export, is removed. Update integrations that called it directly. (#43751)
• UV_CACHE_DIR no longer has a baked-in shared default. Keep any deliberate plugin-daemon cache override explicit. (#42481)

Optional/provider-specific settings are documented in the matching files under docker/envs. Preserve existing service env files when upgrading.

Upgrading from 1.17.1 applies 22 schema/data migration revisions and two migration-head merges, ending at b9d3f7a5c102:

The PostgreSQL task-ID index is created concurrently, but still scans workflow_runs and consumes I/O; adding the columns requires a brief schema lock. Existing task IDs need no global backfill. Apply the complete migration chain before starting the new workers. KnowledgeFS has a separate engine database and migration process. A downgrade that would leave KnowledgeFS-only API keys unrestricted is blocked until those keys are revoked through the API; keep backups for rollback.