Traceary

Catalog / Dify

1.17.0

v1.17.0

yesterdaysecurityaddedfixedOriginal notes

New Features

Agent: E2B Sandbox, Home Snapshots, and Skill Management

  • E2B sandbox backend: agent shell/code execution can now run on E2B cloud sandboxes in addition to the local sandbox. Select the backend with DIFY_AGENT_RUNTIME_BACKEND; a new docker-compose.e2b.yaml ships the E2B stack, E2B traffic is authenticated, and the E2B template is synced on release (#39480, #39705, #39873, #39996, #40858, #40871, #40891, #40892).
  • Build-time Home Snapshots: when an agent build is applied (published), the agent's sandbox home directory — installed packages, prepared files, working state — is captured and subsequent runs of the published agent restore their home directory from that snapshot, so the agent starts from the exact filesystem state it had at build time. (#39702, #40876, #40996).
  • Workspace-level Skill management: Skills are reusable, versioned capabilities packaged with code and tool definitions that agents can discover and invoke. A new workspace-level skills manager with draft → publish → version lifecycle ships alongside a web UI (skill listing, builder panel, file editor). (#39675, #39798, #39799, #41180).
  • Context-aware history compaction: long agent conversations no longer blow past the model's context window — Dify resolves each model's effective window and tiers compaction (clear old tool results first, then summarize older history) so runs stay within budget without losing recent context (#40872).

Reusable LLM Environment Variables in Workflows

  • Define a shared provider/model/mode/parameter configuration once (e.g. for_summarize, for_research) and reference it from any LLM node. Coordinated model changes now happen in one place instead of drifting node-by-node, and the references survive DSL import/export, snippets, RAG pipelines, and collaborative editing (#39125).

Human Input in Loops and Iterations

  • Human-in-the-loop forms now work inside Loop and Iteration nodes, pausing and resuming correctly across page refreshes for both debug and installed apps — enabling review/approval steps within repeated work (#39243).

Provider-Neutral Unified Tracing

  • Opt-in unified tracing (OPS_TRACE_UNIFIED_ENABLED) assembles the full parent-child span tree (workflows, chatflows, messages, nodes, loops, iterations, nested workflows) once in core and delegates only transport to lightweight adapters. Phoenix and LangSmith adapters ship first; disabled by default and fully backward compatible (#39451).
  • New GenAI spans surface LLM TTFT, agent ReAct steps, tool calls, and failed LLM nodes for deeper observability (#39339).

Cloudflare Turnstile (CAPTCHA) Support

  • Optional Turnstile challenge on sign-in and email-code login to protect authentication endpoints from abuse, with configurable site/secret keys and allowed hostnames (#40494).

Azure Key Vault / Pluggable KMS

  • Introduces a KMS provider abstraction with Azure Key Vault support for key provisioning, encryption, and decryption, plus key rotation configuration — a step toward externally-managed encryption keys (#39933).

TiDB Vector Full-Text & Hybrid Search

  • TiDB Vector deployments can now enable full-text and hybrid retrieval (TIDB_VECTOR_ENABLE_FULLTEXT_SEARCH, default off), using a multilingual full-text index alongside vector search (#38112).

Broader Model & File Handling

  • LLM nodes and agents can now pass image files directly to multimodal models, and non-vision attachments are no longer silently dropped from agent chats (#39848, #40179).
  • New multimodal retrieval guidance helps users pick embedding models correctly for image-bearing knowledge bases (#40566).
  • Audio ASR now accepts audio/x-m4a, and audio MIME types are validated more accurately (#40776, #41043).

Go to Anything (⌘K / Ctrl+K)

  • Press ⌘K (Ctrl+K on Windows/Linux) anywhere in the console to open the command palette and jump to apps, agents, skills, knowledge bases, plugins, or workflow nodes, or trigger quick actions via slash commands. New in this release: agents and skills are searchable, and the icon-command system was refactored across all domains for consistency (#40620, #40621, #40646–#40649, #41160).

Other Additions

  • ODT (OpenDocument Text) document extraction support (#39973).
  • New date / date-picker parameter type for tool plugins (#36163).
  • Lao (lo-LA) language support (#39474).
  • Automatic cleanup task for old conversations (ENABLE_CONVERSATION_CLEANUP_TASK) to bound data growth (#40889-era).
  • Marketplace embedded directly into integration categories for smoother tool/plugin discovery (#40744).

Improvements

Accessibility (large a11y pass)

  • A very large set of changes makes the console keyboard- and screen-reader-friendly: real <button> semantics for dozens of interactive controls, accessible names for icon-only actions (copy, close, delete, menus), primary headings on auth/install pages, keyboard-accessible member/tool selectors, and correct ARIA states (#40192–#40377 and many others).

Workflow Authoring

  • The workflow generator now prefers already-installed and configured tools when suggesting nodes, so builders reach for the tools they actually have (#40611, #39850).

Workflow & Runtime Stability

  • Reproducible web workflow runs, preserved canvas state after history updates, no more refresh render loops, and SSE streams now end cleanly on terminal events (#40010, #40489, #41105, #40042).
  • stop is now honored between non-streaming nodes and paused workflows clear stale cancellation signals correctly (#41090, #40905, #40972).
  • APP_MAX_EXECUTION_TIME and WORKFLOW_MAX_EXECUTION_TIME defaults raised from 1200s → 3600s to accommodate longer-running workflows.

Internal Quality

  • Large migration of unit tests to real ORM models / SQLite sessions for more reliable coverage, plus stronger typing across migrated tests (many #38xxx–#39xxx). No user-facing behavior change.

Security Enhancements

  • Authentication hardening: Turnstile challenge on login/email-code flows, hardened email-code verification with attempt limits and token expiry (EMAIL_CODE_LOGIN_MAX_ATTEMPTS, EMAIL_CODE_LOGIN_TOKEN_EXPIRY_MINUTES), suspended-email-domain handling, and short-lived agent authorization tokens (#40494, #40960, #41004, #40884).
  • Access-control / ownership scoping: dataset, document, RAG, conversation, workspace-credential, and OAuth-client resources are now consistently bound to their owners and app scope, closing several unauthorized-access paths (#40989, #40888, #40790, #40745, #40893, #40786, and related).
  • SSRF & outbound hardening: outbound HTTP connect phases are bounded (5s), agent/binding download and run timeouts are configurable, and the SSRF-blocked error message now points to the correct issue (#40807, #41027, #40605).

Bug Fixes (selected)

  • Prevent dropped workflow_started events in Redis Streams and dropped/duplicated runs from superseded executions (#40964, #40699).
  • Normalize workflow timestamps to naive UTC and preserve run snapshots/history for failed, cancelled, and interrupted runs (#40947, #40876, #40972).
  • Prevent cross-tab chat conversation switching and stop dropping non-vision attachments in agent chat (#40709, #40179).
  • Correct Qwen/VL system-message ordering by merging system messages first (#39136).
  • Fix Elasticsearch-JA adapter document_id mapping and VectorType (#40400); avoid empty Bedrock schema fields (#40443).
  • Use dynamic DNS resolution for all nginx upstreams (#39155); preserve UTF-8 byte size for text uploads (#40034).
  • Numerous webapp/UI fixes: restore email-code and password form submissions, mobile sign-in overflow, toast stacking, model selector spacing (#40227, #40222, #40921, #40970, #8d612895).

Environment Variable Changes

Added

Agent runtime / sandbox (docker/envs/core-services/dify-agent.env.example)

  • DIFY_AGENT_RUNTIME_BACKEND, DIFY_AGENT_RUN_TIMEOUT_SECONDS, DIFY_AGENT_SANDBOX_FILES_BASE_URL, DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT, DIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDS
  • E2B: DIFY_AGENT_E2B_API_KEY, DIFY_AGENT_E2B_TEMPLATE, DIFY_AGENT_E2B_SHELLCTL_PORT, DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS
  • Local sandbox: DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT, DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN
  • Outbound HTTP tuning: DIFY_AGENT_OUTBOUND_HTTP_CONNECT_TIMEOUT, DIFY_AGENT_OUTBOUND_HTTP_READ_TIMEOUT, DIFY_AGENT_OUTBOUND_HTTP_WRITE_TIMEOUT, DIFY_AGENT_OUTBOUND_HTTP_POOL_TIMEOUT, DIFY_AGENT_OUTBOUND_HTTP_KEEPALIVE_EXPIRY, DIFY_AGENT_OUTBOUND_HTTP_MAX_CONNECTIONS, DIFY_AGENT_OUTBOUND_HTTP_MAX_KEEPALIVE_CONNECTIONS
  • AGENT_BACKEND_BINDING_FILE_DOWNLOAD_TIMEOUT_SECONDS, AGENT_BACKEND_HOME_SNAPSHOT_TIMEOUT_SECONDS (api/.env.example)

Auth / security

  • TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY, TURNSTILE_ALLOWED_HOSTNAMES, TURNSTILE_EMAIL_CODE_VERIFY_REQUIRED
  • EMAIL_CODE_LOGIN_MAX_ATTEMPTS, EMAIL_CODE_LOGIN_TOKEN_EXPIRY_MINUTES
  • KEY_PROVIDER_TYPE, AZURE_KEYVAULT_VAULT_URL, AZURE_KEYVAULT_KEY_SIZE, AZURE_KEYVAULT_ROTATION_INTERVAL_DAYS

Knowledge / retrieval

  • TIDB_VECTOR_ENABLE_FULLTEXT_SEARCH, TIDB_ON_QDRANT_ESTIMATED_STORAGE_LIMITS_MB, KNOWLEDGE_UPLOAD_FILE_SIZE_LIMIT_FOR_PAID_PLAN

Tracing / observability

  • OPS_TRACE_UNIFIED_ENABLED, OPS_TRACE_PARENT_CONTEXT_TTL_SECONDS

Misc

  • ENABLE_CONVERSATION_CLEANUP_TASK, CONVERSATION_CLEANUP_TASK_INTERVAL, CONVERSATION_CLEANUP_BATCH_SIZE
  • UPLOAD_SKILL_FILE_SIZE_LIMIT, PLUGIN_MAX_FILE_SIZE, MARKDOWN_FORM_FIELD_NAME_EXTRA_CHARS
  • DEPLOYMENT_EDITION (replaces EDITION, see below)

Removed

  • EDITION → renamed to DEPLOYMENT_EDITION
  • ENTERPRISE_ENABLED (enterprise gating consolidated)
  • AGENT_BACKEND_RUN_TIMEOUT_SECONDS → replaced by DIFY_AGENT_RUN_TIMEOUT_SECONDS
  • DIFY_AGENT_SHELLCTL_AUTH_TOKEN, DIFY_AGENT_SHELLCTL_ENTRYPOINT (agent runtime reworked)

Modified (default values)

  • APP_MAX_EXECUTION_TIME: 1200 → 3600
  • WORKFLOW_MAX_EXECUTION_TIME: 1200 → 3600
  • OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES: 60 → 780
  • GRAPH_ENGINE_SCALE_UP_THRESHOLD: 3 → 0

Docker Compose

  • docker/docker-compose.yaml — modified
  • docker/docker-compose.middleware.yaml — modified
  • docker/docker-compose.e2b.yaml — new (E2B agent sandbox stack)

Database Migrations

This release includes new migrations (community-edition relevant):

  • add_workflow_version_number — workflow version numbering (deployment v2)
  • add_oauth_provider_app_auto_authorize — silent OAuth authorization flag
  • add_conversation_cleanup_index — supports the conversation cleanup task
  • add_workspace_skill_management — workspace-level Skill management (draft/version/publish lifecycle)
  • add_agent_home_snapshot_ledger, make_home_snapshot_references_nullable — agent build-time Home Snapshot ledger and nullable snapshot references
  • replace_agent_runtime_sessions_with_*, remove_agent_drive, clean_legacy_agent_soul_files, simplify_agent_v2_output_contract — new agent runtime

No manual backfill command is required for these migrations. Run flask db upgrade as part of the upgrade.

Upgrade Guide

[!IMPORTANT]

  • This release includes new database migrations — run them as part of the upgrade.
  • Environment variables changed substantially (many added, edition variable renamed EDITION → DEPLOYMENT_EDITION, several defaults changed). Review the Environment Variable Changes section and update your .env accordingly. In particular, rename EDITION to DEPLOYMENT_EDITION if you set it.
  • Docker Compose configuration changed and a new docker-compose.e2b.yaml was added. If you maintain a customized docker-compose.yaml, re-apply local customizations carefully.
  • The migration add_conversation_cleanup_index builds index on existing data, which could take longer to execute if the conversations table is big.

Docker Compose Deployments

  1. Back up your customized compose and env files:
    cd docker
cp docker-compose.yaml docker-compose.yaml.$(date +%s).bak
cp .env .env.$(date +%s).bak 2>/dev/null || true
  2. Get the latest code:
    git fetch --tags
git checkout main   # or the target release tag once cut
  3. Stop services (from the docker directory):
    docker compose down
  4. Back up data:
    tar -cvf volumes-$(date +%s).tgz volumes
  5. Review env changes and re-apply local customizations (remember EDITION → DEPLOYMENT_EDITION).
  6. Upgrade:
    docker compose up -d

Source Code Deployments

  1. Stop the API server, Worker, and Web frontend.
  2. Get the latest code:
    git fetch --tags
git checkout main   # or the target release tag once cut
  3. Update Python dependencies:
    cd api
uv sync
  4. Run migrations:
    uv run flask db upgrade
  5. Rebuild/restart the Web frontend, then restart the API server and Worker.

What's Changed

These notes run past the length kept in the archive. The rest is on the publisher’s page.