Agent Runtime Backend Initialization#

The dify-agent FastAPI server initializes its sandbox runtime at startup through a two-stage process: ServerSettings resolves DIFY_AGENT_* environment variables into a RuntimeBackendProfile, and create_default_layer_providers() wires that profile into the LayerProvider set consumed by the RunScheduler. Layers and providers never read environment variables directly — all credentials and endpoints are injected at construction time.

Initialization Flow#

create_app() in server/app.py orchestrates the startup sequence:

1. ServerSettings is instantiated, loading all DIFY_AGENT_* env vars via Pydantic Settings.
2. settings.build_runtime_backend_profile() calls create_runtime_backend_profile(RuntimeBackendSettings(...)). For the local backend, it returns None when DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT is not set 1; for all other backends, missing required credentials raise ValueError at startup before any traffic is accepted 2.
3. create_default_layer_providers() receives the profile (or None) plus plugin-daemon and inner-API credentials, and builds a tuple of LayerProvider objects.
4. The resulting providers tuple is passed to RunScheduler during the FastAPI lifespan, servicing all run requests in-process.

ServerSettings (DIFY_AGENT_* env vars)
    └─ build_runtime_backend_profile()
           └─ create_runtime_backend_profile(RuntimeBackendSettings)
                  └─ RuntimeBackendProfile { execution_bindings, home_snapshots }

create_default_layer_providers(runtime_backend_profile=...)
    ├─ always: DifyShellLayer, DifyExecutionContextLayer, PromptLayer, ...
    └─ optional: DifyRuntimeLayer (only when profile is not None)
           │
     RunScheduler (lifespan-scoped)

Backend Selection#

DIFY_AGENT_RUNTIME_BACKEND (default: local) selects one of four backends 3. create_runtime_backend_profile() constructs the matching execution_bindings + home_snapshots driver pair:

• Local: connects to a shellctl sandbox via DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT. Home dirs are materialized under DIFY_AGENT_LOCAL_SANDBOX_MATERIALIZED_HOME_ROOT (default /home/dify) and snapshots under DIFY_AGENT_LOCAL_SANDBOX_HOME_SNAPSHOT_ROOT (default /home/dify/.snapshots) 4.
• Enterprise: uses a gateway at DIFY_AGENT_ENTERPRISE_SANDBOX_GATEWAY_ENDPOINT with configurable control-plane/proxy timeout separation 5.
• E2B: uses the E2B SDK keyed by DIFY_AGENT_E2B_API_KEY, with a configurable sandbox template (default difys-default-team/dify-agent-local-sandbox) and active timeout 6.
• OpenShell: manages sandboxes on a self-hosted NVIDIA OpenShell gateway via gRPC. The backend bootstraps shellctl via an idempotent control exec on acquire and reaches it through authenticated ForwardTcp tunnels. Home snapshots are directory copies on a shared volume (no native snapshot capability). Requires DIFY_AGENT_OPENSHELL_DRIVER_CONFIG (JSON object mounting the shared Home Snapshot volume) 7.

Layer Provider Registration#

create_default_layer_providers() always registers the following providers 8:

• Direct type (LayerProvider.from_layer_type()): PromptLayer, DifyUserPromptLayer, PydanticAIHistoryLayer, DifyOutputLayer, DifyAskHumanLayer, DifyConfigLayer
• Factory-wrapped (LayerProvider.from_factory()): DifyExecutionContextLayer, DifyShellLayer, DifyPluginLLMLayer, DifyPluginToolsLayer, DifyCoreToolsLayer, DifyKnowledgeBaseLayer

DifyRuntimeLayer is conditionally appended only when runtime_backend_profile is not None 9. If absent, any run that requires dify.runtime or dify.shell fails at run time (not at startup).

Shell Layer: Enforced Factory Pattern#

DifyShellLayer.from_config() raises TypeError — direct construction is blocked. The factory always calls from_config_with_settings(), which injects three server-owned values absent from per-run HTTP payloads:

• shell_redact_patterns — server-level regex list for masking secrets in shell output
• agent_stub_api_base_url — public Agent Stub endpoint URL
• agent_stub_token_factory — callable that mints JWE tokens for shell jobs

The same pattern applies to DifyRuntimeLayer: from_config() raises TypeError; the only valid path is from_config_with_backend(), which accepts the ExecutionBindingBackend from the RuntimeBackendProfile 10.

DifyShellLayer does not own the sandbox connection. Every shell tool call reads the RuntimeLease via _require_resource() from its DifyRuntimeLayer dependency. HOME is set from lease.layout.home_dir, which is controlled exclusively by the runtime backend 11.

Key Settings Reference#

All settings live in ServerSettings under the DIFY_AGENT_ env-var prefix:

Key Entry Points#