Agent Runtime Backend Initialization#

Overview#

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

Initialization Flow#

create_app() in app.py orchestrates startup:

1. ServerSettings 1 is instantiated, loading all DIFY_AGENT_* environment variables via Pydantic Settings.
2. settings.build_runtime_backend_profile() 2 calls create_runtime_backend_profile(RuntimeBackendSettings(...)) to produce a RuntimeBackendProfile — or None when runtime_backend == "local" but no local_sandbox_endpoint is set 3.
3. create_default_layer_providers() 4 receives the profile plus plugin-daemon/inner-API credentials, building a tuple of LayerProvider objects. The DifyRuntimeLayer provider is only appended when runtime_backend_profile is not None 5.
4. The resulting layer_providers tuple is passed to RunScheduler during the FastAPI lifespan 6, where it services all subsequent run requests in-process.

ServerSettings (env vars)
    └─ build_runtime_backend_profile()
           └─ create_runtime_backend_profile(RuntimeBackendSettings)
                  └─ RuntimeBackendProfile { execution_bindings, home_snapshots }
                         │
create_default_layer_providers(runtime_backend_profile=...)
       └─ LayerProvider[DifyRuntimeLayer] (injected with execution_bindings)
       └─ LayerProvider[DifyShellLayer] (injected with redact_patterns + agent_stub settings)
       └─ ... other providers
               │
         RunScheduler (lifespan-scoped)

Runtime Backend Selection (runtime_backend)#

DIFY_AGENT_RUNTIME_BACKEND selects one of three backends 7; create_runtime_backend_profile() constructs the matching driver pair 8:

Each backend validation is enforced by RuntimeBackendSettings.validate_selected_backend() at startup 9; missing required credentials raise ValueError before the server accepts traffic.

Local backend#

Connects to a local shellctl sandbox via DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT (also accepted as the legacy alias DIFY_AGENT_SHELLCTL_ENTRYPOINT) 10. Home directories 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) 11.

Enterprise backend#

Uses an enterprise sandbox gateway at DIFY_AGENT_ENTERPRISE_SANDBOX_GATEWAY_ENDPOINT with control-plane / proxy timeout separation 12.

E2B backend#

Uses the E2B SDK (E2BSDKControlPlane) keyed by DIFY_AGENT_E2B_API_KEY, with configurable sandbox template and active timeout 13.

Shell Layer Provider Factory Pattern#

DifyShellLayer blocks direct construction — calling from_config() raises TypeError 14. Instead, it must be instantiated via from_config_with_settings(), which accepts three server-injected settings not present in the per-run config payload:

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

In compositor_factory.py, the shell layer is registered as a factory provider that closes over these settings 15:

LayerProvider.from_factory(
    layer_type=DifyShellLayer,
    create=lambda config: DifyShellLayer.from_config_with_settings(
        DifyShellLayerConfig.model_validate(config),
        shell_redact_patterns=shell_redact_patterns or [],
        agent_stub_api_base_url=agent_stub_api_base_url,
        agent_stub_token_factory=agent_stub_token_factory,
    ),
)

The shell layer itself does not own the sandbox connection — it reads the RuntimeLease from DifyRuntimeLayer.lease at call time 16. HOME is set from lease.layout.home_dir, which is controlled entirely by the runtime backend 17.

Key Settings Reference#

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

Key Entry Points#