Agent Shell Layer#

The Agent Shell Layer is the mechanism by which Dify injects a dify.shell runtime layer into agent runs. It consists of two interlocking concerns: a global on/off flag (AGENT_SHELL_ENABLED) and a per-agent config schema that maps AgentSoulConfig fields into the DifyShellLayerConfig structure forwarded to the agent backend.

Global Flag: AGENT_SHELL_ENABLED#

The AGENT_SHELL_ENABLED boolean (default True) in AgentBackendConfig gates whether the Home, Workspace, Sandbox, and Shell runtime layers are injected at all. Both request builder call sites — workflow Agent v2 and Agent App — read dify_config.AGENT_SHELL_ENABLED and pass it as include_shell to the backend request builder. Setting this flag to False suppresses the entire shell layer regardless of per-agent config.

Per-Agent Config Schema#

Per-agent shell configuration is rooted in AgentSoulConfig, which holds three shell-relevant top-level fields:

AgentSoulEnvConfig 1 holds variables: list[AgentEnvVariableConfig] and secret_refs: list[AgentSecretRefConfig]. The AgentEnvVariableConfig supports multiple name aliases (name, key, env_name, variable) and a value/default field 2. AgentSecretRefConfig similarly supports name aliases plus value (for inline Composer-provided secrets), ref, credential_id, and provider_credential_id 3.

AgentSoulSandboxConfig 4 wraps a provider string and an AgentSandboxProviderConfig with optional image, working_dir, env, and cpu fields 5.

AgentCliToolConfig 6 represents one CLI tool. Key fields:

• enabled: bool (default True)
• install_commands: list[str] — list of bootstrap commands; aliases install_command, install, setup_command, command are also accepted
• env: AgentCliToolEnvConfig — per-tool env vars and secret refs
• authorization_status, permission, pre_authorized — authorization gates
• dangerous, dangerous_command, requires_confirmation — risk flags; dangerous_acknowledged, dangerous_accepted, risk_accepted, approved — acknowledgement flags

Mapping to DifyShellLayerConfig#

The shared build_shell_layer_config function (used by both workflow and Agent App builders) maps AgentSoulConfig to DifyShellLayerConfig:

1. CLI tools — only tools passing _cli_tool_enabled are included. A tool is excluded if:

   • enabled is False
   • pre_authorized is False
   • Any permission/authorization field resolves to a denied state (unauthorized, denied, forbidden, invalid, unavailable) 7
   • The tool has a danger flag (dangerous, dangerous_command, requires_confirmation or risk_level == "dangerous") without a corresponding acknowledgement flag (dangerous_acknowledged, dangerous_accepted, risk_accepted, approved) 8

2. Env vars — _shell_env_vars combines agent_soul.env.variables and any secret_refs that carry an inline value (those are promoted to plain env vars rather than secret refs, since the backend secret ref schema only accepts short backend-managed IDs) 9.

3. Secret refs — _shell_secret_ref emits a DifyShellSecretRefConfig only for secret refs that have no inline value and carry a backend-managed ref, credential_id, or provider_credential_id.

4. Name normalization — _name_from_mapping resolves the env var name by checking the keys name, key, env_name, variable in order, returning the first non-blank string.

Runtime Behavior (DifyShellLayer)#

Once injected, the DifyShellLayer (type ID dify.shell) exposes four tools to the agent: shell_run, shell_wait, shell_input, and shell_interrupt 10. The layer:

• Persists only JSON-safe shell session state in runtime_state; active ShellctlHandle lives on the layer instance during the active resource scope.
• Delegates workspace lifecycle to ShellProvisionProtocol (provision, reattach, destroy).
• Sets HOME=<shell_home_root>/<agent_id> for all shell commands, where shell_home_root defaults to /home and is configured via DIFY_AGENT_SHELL_HOME_ROOT.
• Redacts all shell output in two passes: per-job JWE token redaction, then regex-pattern redaction from DIFY_AGENT_SHELL_REDACT_PATTERNS (server-level) and config.redact_patterns (per-agent) 10. The injected JWE token is masked as *** in model-facing shell_run, shell_wait, and shell_input observations; raw shellctl output and files referenced by output_path remain unchanged.
• Optionally injects Agent Stub env vars (DIFY_AGENT_STUB_API_BASE_URL, DIFY_AGENT_STUB_AUTH_JWE) into user-visible shell.run jobs when valid agent_stub_api_base_url and token factory are provided. Agent Stub authorization is limited to five minutes and does not refresh inside an already-running process. If a command reports that the authorization expired, users should start a new shell tool call and retry the command.

File Upload Recovery#

When using Agent Stub file commands, if file upload successfully uploads the file but creating the public URL fails, the command prints the canonical mapping and exits with an error containing an exact dify-agent file public-url <reference> retry command. Run that command from a new shell tool call to create the public URL without uploading the file again. On success, file public-url prints the complete JSON mapping containing transfer_method, reference, and public_download_url.

Key Entry Points#