Docker Networking#

Dify's Docker Compose stack uses Docker's embedded DNS resolver for inter-service communication: containers refer to each other by their service name (e.g., api, plugin_daemon, redis), and Docker resolves those names to container IPs on a shared bridge network. All authoritative definitions live in docker/docker-compose-template.yaml (the generated docker-compose.yaml must not be edited directly).

Network Topology#

The stack defines six named bridge networks 1:

Service → network membership 2 3 4:

Two services are intentionally isolated from the default network for security:

• sandbox — ssrf_proxy_network only; cannot reach the external network directly, all outbound traffic routes through the Squid SSRF proxy 8.
• local_sandbox — agent_sandbox_network + local_sandbox_proxy_network only; isolated from api and other internal services. All egress traffic (except to agent_backend and localhost) is forced through agent_ssrf_proxy, which enforces path-based ACLs: only /agent-stub/* on agent_backend and /files/* on api are allowed. This prevents SSRF attacks from malicious code running in the agent sandbox.

┌─ default (external access) ───────────────────────────────────────────────┐
│ nginx → api / worker / api_websocket / plugin_daemon / web │
│ redis db_postgres agent_backend agent_ssrf_proxy │
└───────────────────────────────────────────────────────────────────────────┘
          │ ssrf_proxy_network (internal: true)
          ├── api, worker, worker_beat, api_websocket
          ├── plugin_daemon
          ├── ssrf_proxy (Squid :3128)
          └── sandbox ← only here (no external egress)

          agent_sandbox_network (internal: true)
          ├── agent_backend (also on default)
          └── local_sandbox ← shellctl control channel (:5004)

          local_sandbox_proxy_network (internal: true)
          ├── agent_ssrf_proxy (also on default)
          └── local_sandbox ← proxy egress path (:3128, ACL-restricted)

Key Inter-Service DNS Names and Ports#

All default service URLs use Docker DNS names, configured in docker/.env and the compose template 9 10:

Critical: Never use localhost for cross-container URLs in Docker Compose. localhost resolves to the container itself, not a peer service. The most common misconfiguration is leaving PLUGIN_DAEMON_URL=http://localhost:5002 in a Dockerized deployment 11.

Plugin Daemon Connectivity#

The plugin daemon requires two bidirectional paths 19:

1. API → Daemon (http://plugin_daemon:5002): Used for all plugin invocations. Requires PLUGIN_DAEMON_URL to use the service name, not localhost. Authenticated via PLUGIN_DAEMON_KEY (sent as X-Api-Key).
2. Daemon → API (http://api:5001): The daemon calls back to the Dify API for inner-API operations. Configured via DIFY_INNER_API_URL on the daemon, authenticated with PLUGIN_DIFY_INNER_API_KEY.

The debugging/remote-install port (5003) is the only port published to the host in default configuration 20. The main API port (5002) is internal-only — accessible over the default network by service name, but not exposed to the Docker host. See Plugin Daemon Port Configuration for the full variable mapping.

In source (dev) mode, the daemon runs in Docker while the API runs on the host, requiring PLUGIN_DIFY_INNER_API_URL=http://host.docker.internal:5001 on macOS/Windows, or the host bridge IP on Linux 21.

web Service SSR Routing#

The Next.js web container's server-side rendering process must reach the API over the internal network. SERVER_CONSOLE_API_URL defaults to http://api:5001 in the compose template 16. If you override CONSOLE_API_URL with a public hostname (e.g., for browser access), also explicitly set SERVER_CONSOLE_API_URL to the internal DNS name. Leaving it pointing to an external hostname that doesn't resolve inside the container is the most common cause of silent SSR failures 22.

Key Source Files#