chore(dify-agent): make local dev work with defaults out of the box (#41533)

Co-authored-by: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

dify-agent/.example.env

@@ -4,7 +4,7 @@
 
 # Redis
 # Redis connection URL for run records and per-run event streams.
-DIFY_AGENT_REDIS_URL=redis://:difyai123456localhost:6379/0
+DIFY_AGENT_REDIS_URL=redis://:difyai123456@localhost:6379/0
 # Prefix for Redis run-record and event-stream keys.
 DIFY_AGENT_REDIS_PREFIX=dify-agent
 
@@ -24,14 +24,14 @@ DIFY_AGENT_PLUGIN_DAEMON_API_KEY=lYkiYYT6owG+71oLerGzA7GXCgOT++6ovaezWAjpCjf+Sjc
 # Base URL for Dify API inner endpoints used by Agent Stub config and file requests.
 DIFY_AGENT_INNER_API_URL=http://localhost:5001
 # Must match API/worker INNER_API_KEY_FOR_PLUGIN, not the generic INNER_API_KEY.
-DIFY_AGENT_INNER_API_KEY=
+DIFY_AGENT_INNER_API_KEY=QaHbTe77CtuXmsfyhR7+vRjI/+XbV1AaFy691iy+kGDv2Jvy0/eAh8Y1
 
 # Runtime resources
 # Select one coherent Home Snapshot + Execution Binding backend: local, enterprise, or e2b.
 DIFY_AGENT_RUNTIME_BACKEND=local
 # Local backend: shellctl data-plane URL and optional bearer token.
 # Leave the endpoint empty when this server will not provide dify.runtime or resource endpoints.
-DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT=
+DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT=http://localhost:5004
 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN=
 # Enterprise resource operations currently fail fast with NotImplementedError.
 # These names are retained for the configured Enterprise Gateway boundary.
@@ -54,12 +54,12 @@ DIFY_AGENT_SHELL_REDACT_PATTERNS=
 # Public Agent Stub URL reachable from shellctl-managed remote machines.
 # Use an HTTP(S) service root or an explicit /agent-stub API root.
 # Leave empty to avoid injecting DIFY_AGENT_STUB_* into shell.run jobs.
-DIFY_AGENT_STUB_API_BASE_URL=http://localhost:5050/agent-stub
+DIFY_AGENT_STUB_API_BASE_URL=http://host.docker.internal:5050/agent-stub
 # Optional bind override used only when DIFY_AGENT_STUB_API_BASE_URL uses grpc://.
 DIFY_AGENT_STUB_GRPC_BIND_ADDRESS=
 # Dify API base URL reachable from the Sandbox for the signed /files/* data plane,
 # including Config file and skill pulls.
-DIFY_AGENT_SANDBOX_FILES_BASE_URL=http://localhost:5001
+DIFY_AGENT_SANDBOX_FILES_BASE_URL=http://host.docker.internal:5001
 # Maximum Agent Stub upload size in MiB; forwarded to Dify API as a signed byte limit.
 DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT=50
 # Shell command deadline for converting a Binding file to a ToolFile.
@@ -84,6 +84,6 @@ DIFY_AGENT_OUTBOUND_HTTP_POOL_TIMEOUT=10
 DIFY_AGENT_OUTBOUND_HTTP_MAX_CONNECTIONS=100
 DIFY_AGENT_OUTBOUND_HTTP_MAX_KEEPALIVE_CONNECTIONS=20
 DIFY_AGENT_OUTBOUND_HTTP_KEEPALIVE_EXPIRY=30
-DIFY_AGENT_LOCAL_SANDBOX_MATERIALIZED_HOME_ROOT=
-DIFY_AGENT_LOCAL_SANDBOX_WORKSPACE_ROOT=
-DIFY_AGENT_LOCAL_SANDBOX_HOME_SNAPSHOT_ROOT=
+DIFY_AGENT_LOCAL_SANDBOX_MATERIALIZED_HOME_ROOT=/home/dify
+DIFY_AGENT_LOCAL_SANDBOX_WORKSPACE_ROOT=/workspace
+DIFY_AGENT_LOCAL_SANDBOX_HOME_SNAPSHOT_ROOT=/home/dify/.snapshots

docker/docker-compose.middleware.yaml

@@ -127,6 +127,30 @@ services:
     networks:
       - ssrf_proxy_network
 
+  # Local sandbox for Dify Agent shell workspaces (shellctl data plane).
+  # Exposes port 5004 on the host so a locally-run agent backend can reach it
+  # at http://localhost:5004 (DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT).
+  local_sandbox:
+    image: langgenius/dify-agent-local-sandbox:1.17.0
+    restart: always
+    env_file:
+      - ./middleware.env
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      SHELLCTL_AUTH_TOKEN: ${DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN:-${DIFY_AGENT_SHELLCTL_AUTH_TOKEN:-}}
+    ports:
+      - "${EXPOSE_LOCAL_SANDBOX_PORT:-5004}:5004"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5004/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    volumes:
+      - dify_agent_local_sandbox_home:/home/dify
+      - dify_agent_local_sandbox_workspace:/workspace
+
   # plugin daemon
   plugin_daemon:
     image: langgenius/dify-plugin-daemon:0.6.10-local
@@ -259,3 +283,7 @@ networks:
   ssrf_proxy_network:
     driver: bridge
     internal: true
+
+volumes:
+  dify_agent_local_sandbox_home:
+  dify_agent_local_sandbox_workspace:

docker/envs/middleware.env.example

@@ -106,6 +106,12 @@ SANDBOX_HTTP_PROXY=http://ssrf_proxy:3128
 SANDBOX_HTTPS_PROXY=http://ssrf_proxy:3128
 SANDBOX_PORT=8194
 
+# ------------------------------
+# Environment Variables for local_sandbox Service (Dify Agent shell workspaces)
+# ------------------------------
+# Leave empty to disable shellctl auth (local development default).
+DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN=
+
 # ------------------------------
 # Environment Variables for ssrf_proxy Service
 # ------------------------------
@@ -145,6 +151,7 @@ EXPOSE_POSTGRES_PORT=5432
 EXPOSE_MYSQL_PORT=3306
 EXPOSE_REDIS_PORT=6379
 EXPOSE_SANDBOX_PORT=8194
+EXPOSE_LOCAL_SANDBOX_PORT=5004
 EXPOSE_SSRF_PROXY_PORT=3128
 EXPOSE_WEAVIATE_PORT=8080