Sandbox Code Execution#

Dify runs two distinct sandboxed execution environments in separate containers:

Both are declared in docker/docker-compose-template.yaml as the sandbox and local_sandbox services respectively.

Legacy dify-sandbox (Code Nodes)#

The legacy sandbox is an external Go service (langgenius/dify-sandbox) running image langgenius/dify-sandbox:0.2.15 1. It accepts HTTP requests and secures each execution with two independent layers:

1. Docker isolation — container-level network and filesystem separation
2. seccomp BPF — a per-child-process kernel syscall filter defaulting to ActKillProcess for any unlisted syscall 2

Languages supported: Python3, Node.js, and Jinja2 (which runs as Python3 at runtime) 3.

Configuration is in docker/volumes/sandbox/conf/config.yaml: port 8194, max_workers: 4, enable_network: true, and an optional allowed_syscalls list for extending the seccomp whitelist 4. The WORKER_TIMEOUT env var (default 15s) and PIP_MIRROR_URL for a custom PyPI mirror are set in the compose file 5.

Dependency caching: the compose file mounts ./volumes/sandbox/dependencies:/dependencies 6, allowing pre-downloaded Python packages to survive container restarts.

API Layer Integration (CodeExecutor)#

The CodeExecutor class in api/core/helper/code_executor/code_executor.py is the single entry point for all code execution from the API layer.

• Endpoint: CODE_EXECUTION_ENDPOINT (default http://sandbox:8194) → POST /v1/sandbox/run 7
• Auth: X-Api-Key header using CODE_EXECUTION_API_KEY 8
• Timeouts: connect 10 s, read 60 s, write 10 s (configurable) 9
• Connection pooling: httpx.Limits with configurable max_connections (default 100) and max_keepalive_connections (default 20) 10

Call flow: execute_workflow_code_template() → language transformer's transform_caller() (wraps user code, serializes inputs as base64) → execute_code() → POST /v1/sandbox/run → response parsed by transform_response().

Language transformers:

dify-agent-runtime (Agent V2 Shell)#

The dify-agent-runtime (langgenius/dify-agent-local-sandbox:1.17.1) is a Go rewrite of the original Python shellctl package, built for Agent V2 shell job execution 12. It exposes shellctl serve --listen 0.0.0.0:5004 13.

Build: a two-stage Dockerfile — a golang:1.26 builder compiles five Go binaries (shellctl, shellctl-runner, shellctl-sanitize-pty, shellctl-runner-exit, dify-agent) with CGO_ENABLED=0, then copies them into a python:3.12-slim-bookworm runtime image 14.

Pre-installed toolchain in the runtime image 15:

Runtime dependency installation: Agent job configurations (DifyShellLayerConfig) can declare cli_tools with install_commands lists; these bootstrap scripts are executed by shellctl-runner when a workspace is first created 16. pip, uv, npm, and pnpm are all available in the container for these install steps.

Filesystem isolation (Landlock): each job runs with per-workspace path restrictions — read-write only to $HOME and the workspace directory (cwd); read-only to /usr, /bin, /lib, etc.; everything else denied 12. The workspace directory itself serves as both the command working directory and temporary storage space, with TMPDIR, TMP, and TEMP environment variables pointing directly to it. Requires Linux ≥ 5.13; disable via SHELLCTL_ENABLE_PATH_ISOLATION=false.

Environment variables:

• SHELLCTL_AUTH_TOKEN — authentication token for the shellctl endpoint 17; the Agent V2 backend connects via DIFY_AGENT_SHELLCTL_ENTRYPOINT
• HTTP_PROXY=http://agent_ssrf_proxy:3128 — routes HTTP traffic through the agent SSRF proxy
• HTTPS_PROXY=http://agent_ssrf_proxy:3128 — routes HTTPS traffic through the agent SSRF proxy
• NO_PROXY=localhost,127.0.0.1 — bypasses proxy for localhost traffic

Network isolation: local_sandbox is not connected to the default network. It is connected to two internal networks:

• agent_sandbox_network — shared with agent_backend, allows agent_backend to communicate with the shellctl endpoint on port 5004
• local_sandbox_proxy_network — shared only with agent_ssrf_proxy, provides proxy access for outbound traffic

This network isolation prevents direct access to internal services like api.

Traffic routing: All HTTP/HTTPS traffic (except localhost and 127.0.0.1) is automatically routed through agent_ssrf_proxy on port 3128. The proxy enforces strict access control:

• ✅ Allows agent_backend /agent-stub/* endpoints
• ✅ Allows api /files/* endpoints (for signed upload/download URLs)
• ✅ Allows external internet access (e.g., to LLM APIs)
• ✅ Allows additional private IPs or domains configured via SSRF_PROXY_ALLOW_PRIVATE_IPS and SSRF_PROXY_ALLOW_PRIVATE_DOMAINS environment variables
• ❌ Denies all other internal service access (default behavior when allowlist variables are not set)

Shellctl communication (agent_backend → local_sandbox:5004) uses the agent_sandbox_network directly.

Security considerations: The proxy and network isolation prevent SSRF attacks from malicious code running in the sandbox. Code executed in the sandbox cannot directly reach internal services. Access to the Dify API is restricted to the /files/* endpoint for signed file URLs only. Access to agent_backend is restricted to /agent-stub/* endpoints only. Known limitation: code in the sandbox can still reach agent_backend via the agent_sandbox_network, though the primary goal is preventing access to api and other services.

Key Source Files#