Shell Provider Lifecycle#

The shell provider lifecycle governs how Dify's agent runtime creates, reuses, and destroys sandbox execution environments across conversation turns. The core abstraction is the ExecutionBindingBackend protocol, which defines four operations:

The acquire/release pair maps to what earlier code called attach/suspend: the sandbox pod stays alive between operations. destroy_binding is the equivalent of the earlier delete. PR #38528 introduced the enterprise sandbox lifecycle and, through subsequent refactoring, promoted these operations from shell-adapter–level suspend()/delete() methods into the runtime backend protocol where they live today.

Conversation-Scoped Binding Ownership#

A binding_ref is per-conversation, created once and reused across every message turn.

First run: AgentAppWorkspaceStore.load_or_create() detects that the conversation has no agent_workspace_binding_id, calls AgentWorkspaceService.create_binding() to provision the backend sandbox, and stores the returned backend_binding_ref in the DB row.

Subsequent runs: The same backend_binding_ref is retrieved and passed through runtime_request_builder.py to DifyRuntimeLayerConfig.backend_binding_ref. DifyRuntimeLayer.resource_context() then calls open_runtime_lease(backend, binding_ref), which invokes backend.acquire(binding_ref) to get a fresh RuntimeLease scoped to this one operation. The lease is released (but the sandbox preserved) when resource_context() exits.

Conversation (turn N)
  └─ AgentAppWorkspaceStore.load_or_create() # returns StoredAgentAppSession
       └─ backend_binding_ref → DifyRuntimeLayerConfig
            └─ DifyRuntimeLayer.resource_context()
                 └─ open_runtime_lease()
                      └─ backend.acquire(binding_ref) # reconnect
                           yield RuntimeLease
                      └─ backend.release(lease) # close clients, keep pod alive

Enterprise Backend Implementation (post-v1.16.1 / PR #38528)#

The EnterpriseExecutionBindingBackend in dify-agent/src/dify_agent/runtime_backend/enterprise.py implements this protocol against the enterprise sandbox gateway:

• create_binding() 1: Posts to POST /v1/sandboxes (gateway control plane), initializes the canonical home_dir/workspace_dir layout via a shellctl control command, then closes the data-plane connection before returning. On any failure, the newly created sandbox is deleted immediately (best-effort).
• acquire() 2: Connects shellctl to {gateway}/proxy/ with X-Sandbox-Id routing, validates that home_dir and workspace_dir still exist with a short 5-second probe, raises BindingLostError if the sandbox is gone (404 or sandbox_expired/not_found codes).
• release() 3: Closes the operation-local shellctl HTTP client. The sandbox pod keeps running.
• destroy_binding() 4: Sends DELETE /v1/sandboxes/{sandboxId} to the gateway (404 is treated as already-gone). Requires destroy_workspace=True because the enterprise backend couples the Binding and Workspace to one physical pod.

_is_missing_sandbox() classifies a ShellProviderError as a lost sandbox when status_code == 404 or the error code is one of not_found, sandbox_expired, sandbox_not_found (case-insensitive). This is the bridge between gateway-level HTTP errors and the BindingLostError the protocol layer expects.

Per-Operation Runtime Layer#

DifyRuntimeLayer wraps one RuntimeLease per operation. It does not own binding creation or destruction — it only acquires and releases. The lifecycle hooks (on_context_create, on_context_resume, on_context_suspend, on_context_delete) all simply assert that a lease is available 5. Actual sandbox provisioning and teardown happen at the API layer.

DifyShellLayer reads the lease from DifyRuntimeLayer.lease at call time 6 and executes shell commands through it. It does not own any part of the sandbox lifecycle.

Binding Retirement and Garbage Collection#

Termination is two-phase to guard against orphans:

1. Retire: AgentWorkspaceService.retire_binding() marks the DB row RETIRED inside the same transaction as the trigger event (e.g., conversation deleted).
2. Collect: collect_retired_binding() calls destroy_execution_binding_sync() (→ backend.destroy_binding()), then deletes the DB row. If the workspace is also retired, collect_retired_workspace() runs first (which calls destroy with destroy_workspace=True).

Error Handling#

Key Source Files#