What the Dify Agent app adds and when to enable it
A team that wants Dify agents to run code or shell commands needs the Dify Agent app and its sandbox runtime, which adds a Linux sandbox for code and shell execution, an agent backend service, and an agent SSRF proxy to the self-hosted stack. Enable it only when a specific agent workflow needs that execution ability and the team has agreed how the sandbox will be isolated from the rest of the deployment. Without that agreed need, the default Compose services already cover the standard app, workflow and knowledge features, and the extra runtime is surface you would have to defend for no benefit.
The sandbox is a capability that expands your attack surface, not a convenience feature. Code and shell commands generated by a model or supplied by a user can attempt to reach the network, read files or call internal services, so the isolation decisions come before the first deployment. Dify 1.16.1 moved the local sandbox onto dedicated agent sandbox networks and routed its outbound traffic through an agent SSRF proxy built on Squid, and it passes AGENT_BACKEND_API_TOKEN and DIFY_AGENT_API_TOKEN as bearer tokens between the api, worker and agent backend services. Read the Dify 1.16.1 release notes and confirm which of these controls your target version provides before you plan around them.
Before enabling the Dify Agent app, record who may build agents that execute code, which network destinations those agents may reach, where the sandbox runs relative to your data stores and secrets, and how you will rotate the internal tokens. Confirm with your Dify version's environment reference which variables control these services, and test egress from a sandboxed run against your own internal address ranges. These decisions set the scope of any quote, because each network path or host you want to isolate adds design and verification work.
Configuration options and when each fits
This table compares the three sandbox paths a self-hosted Dify operator can choose: the default Compose sandbox, local_sandbox on dedicated agent networks, and the agent SSRF proxy path. Read each row against your own network policy, since the reach of each option depends on how your Compose file and host firewall are configured. The main takeaway is that the 1.16.1 change isolated local_sandbox on its own networks, so the choice now turns on which runtime executes code and where its outbound traffic can go.
| Option | Purpose | Network reach | When it fits and what to confirm |
|---|---|---|---|
| Default Compose sandbox | Runs code and shell steps for workflows in the sandbox service that ships with the Compose deployment | Reaches only the networks that your Compose file attaches it to; confirm this on your own host | Fits a standard single-host trial or pilot; confirm which outbound destinations it can reach before any workflow runs sensitive data |
| local_sandbox on agent networks | Runs agent code and shell commands on dedicated agent sandbox networks, introduced in Dify 1.16.1 | Confined to the dedicated agent sandbox networks rather than the general application network | Fits deployments that need stronger separation from core services; confirm the release you run includes this change and check the network layout in your version's Compose file |
| Agent SSRF proxy path (agent_ssrf_proxy) | Routes outbound requests from agent activity through a Squid proxy added in Dify 1.16.1 | Outbound only, filtered by the proxy's rules; internal and private ranges should be blocked, which you must verify | Fits teams that must control which external hosts agents can call; confirm the allow and deny lists, and test that internal addresses are actually refused |
| Service-to-service token authentication | Requires AGENT_BACKEND_API_TOKEN and DIFY_AGENT_API_TOKEN as bearer tokens between api, worker and agent_backend | Internal calls between Dify services only | Always relevant once the Agent app is enabled; confirm that both tokens are generated, stored in your secrets manager and rotated through a planned change |
| Operator decision on enablement | Determines whether the Agent app and its runtime services run at all in your environment | Depends on the option selected above | Confirm with your security team whether agent code execution is permitted for each workspace before enabling the services |
Enabling the Agent app in a Docker Compose deployment
This sequence takes a Docker Compose Dify host from a sizing check to a running stack in which the agent backend, the agent SSRF proxy and the sandbox services are confirmed healthy. Each step closes with a check so the team knows whether to continue. The steps assume a pinned release and a reviewed configuration before any service starts.
Confirm host sizing and Compose version
The platform team checks that the host meets the documented minimum of 2 CPU cores and 4 GB of RAM, and that Docker Compose is version 2.24.0 or later. Agent features add services beyond the core stack, so treat these figures as the floor and confirm with your own load expectations. Run
docker compose versionon the host and record the output. Done when the reported version is 2.24.0 or later and the host resources are documented in your change record.Pin a release from the GitHub releases page
The operator selects a specific Dify release from the GitHub releases page instead of pulling a floating tag, and reads that release's upgrade notes. Agent sandbox networking and token handling changed in 1.16.1, so confirm the chosen release includes those changes and check any notes that mention the agent services. Record the exact version in your configuration repository. Done when the chosen version tag is committed and its release notes have been reviewed by the person who owns the deployment.
Review agent variables in .env.example
The operator copies the Docker Compose folder for the pinned release, then reads
.env.examplefor the variables that govern the agent backend, the agent SSRF proxy and the sandbox, including theSSRF_PROXYsettings. Compare the file against your existing.envso that no new variable is missed after an upgrade. Note any variable that is set to a default you have not yet decided on. Done when every agent-related variable has a recorded value or an explicit decision to keep the default.Set SECRET_KEY and agent API tokens
The security owner generates a strong
SECRET_KEYand the bearer tokens required between services, includingAGENT_BACKEND_API_TOKENandDIFY_AGENT_API_TOKEN, and stores them in your approved secrets store rather than in a shared file. SettingSECRET_KEYafter launch logs out all users and affects encrypted OAuth credentials, so confirm it before the first start. Do not reuse tokens across environments. Done when the values are present in the environment file, none of them is a placeholder, and the storage location is recorded.Confirm sandbox isolation decisions before start
Before bringing the stack up, the platform and security teams agree on how the sandbox may reach networks, which outbound destinations the SSRF proxy allows, and who approves changes to those rules. The sandbox runs code and shell commands, so this decision governs blast radius. Write the decisions down alongside the configuration. Done when the networking and egress decisions are approved in writing and reflected in the planned compose overrides.
Bring up the stack and wait for health
The operator starts the stack with
docker compose up -dfrom the release folder and waits for every container to report running. Review the logs ofapi,workerandagent_backendfor startup errors, especially token mismatches between services. Done when all containers are running and the logs show no repeated restart or authentication failures.Verify agent_backend, agent SSRF proxy and sandbox
The operator checks
docker compose psfor theagent_backend,agent_ssrf_proxyandsandboxservices, confirms each reports healthy, and then opens the Dify console to create a test agent app. Run a harmless test that uses the sandbox, then attempt an outbound request to a private address to confirm the proxy blocks it. Done when the three services are healthy, the test run completes, and the blocked request is recorded as denied in the proxy logs.
Isolation decisions to make before enabling the sandbox
Enabling the Agent app adds a runtime that executes code and shell commands, so the decisions below belong in the design record before the first agent runs. Each card is a question your security, platform and application owners must answer for your own environment, and the answers feed the same configuration in the Compose stack.
Which workspaces may run code
Agents that execute code are a different risk class from chat apps, so decide which workspaces and builders may create them at all. Restrict the capability to named teams, and record who owns each agent app and what data its workflow can reach. Confirm how your Dify edition controls this, since the Community edition is limited to a single workspace and Enterprise adds multiple workspaces. Review new agent apps the same way you review other code that reaches production systems.
Outbound destinations through the agent proxy
The agent SSRF proxy is the controlled path for requests made from the sandbox, so its allowlist defines what an agent can reach. Start from no external destinations, then add each domain or service a specific agent needs, with a named owner and reason. Test that internal and private address ranges stay blocked, and confirm the exact proxy settings with the Dify environment reference for your version before you rely on them.
Handling bearer tokens and SECRET_KEY
Version 1.16.1 passes AGENT_BACKEND_API_TOKEN and DIFY_AGENT_API_TOKEN as bearer tokens between the api, worker and agent backend services. Generate them per environment, store them in your secrets manager rather than in plain .env files shared by teams, and rotate them with a documented procedure. Treat SECRET_KEY the same way: changing it after deployment logs out all users, so plan its rotation as a scheduled maintenance event.
Host isolation for sandbox containers
The sandbox containers run untrusted code, so decide where they run and what they can touch on the host. Ask whether the sandbox shares a Docker host with the metadata database, vector store or other tenants, and whether its network is limited to the dedicated agent networks. Confirm the container privileges, resource limits and filesystem mounts your version uses, and keep the sandbox off hosts that hold production database credentials.
Logging of executed commands
Operators need to answer what an agent ran, against which system, and on whose request. Define which events you capture from the sandbox, the agent backend and the proxy, where they are shipped, and how long they are kept. Confirm with your own tests what Dify records for code and shell execution in your version, because workflow logs alone may not show command output or outbound requests. Align retention with your privacy policy before go-live.
Who approves upgrades that touch agent networks
Minor releases arrive roughly monthly, and changes to sandbox networks, proxies and internal tokens can alter what agents can reach. Name an approver for any upgrade that modifies agent services, require a backup before the upgrade, and check the new .env.example for added variables. Test the proxy allowlist and token handling in a staging environment that matches production before the change window.
How the isolation choice differs by environment
In an evaluation, the goal is to learn how the Agent app behaves with sample data, not to hold production records. Teams can enable the sandbox on an isolated host so they can observe what code and shell commands the agent runs, which network paths it tries, and how it fails. The Dify 1.16.1 release notes describe agent sandbox network isolation through a Squid proxy, so the evaluation should confirm that this isolation is active in the release under test rather than assume it.
- Dedicated test host: Run the Compose stack on a machine with no route to production databases, identity systems or internal file shares.
- Synthetic data only: Load invented documents and test credentials, and keep real customer or employee records out of knowledge bases and tool inputs.
- Replaceable secrets: Generate a fresh
SECRET_KEYand agent tokens for the test stack and do not reuse them later. - Logged test runs: Record which version was tested, which prompts triggered code execution and what the sandbox attempted to reach.
Before leaving evaluation, check that the sandbox cannot reach internal address ranges and that the results are written down in a form the pilot team can reuse.
An internal pilot brings real staff and some internal data into the platform, so the sandbox becomes a path into systems the organization cares about. The posture should narrow who can create agent apps, which tools they can attach and which outbound destinations the sandbox can use. Dify's SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, and the pilot should confirm that the agent SSRF proxy follows the same rule for sandboxed traffic.
- Restricted builders: Limit agent app creation to a named group, and keep sign-up policy closed to people outside that group.
- Allowlisted egress: Permit only the model endpoints and internal services the pilot needs, and test that everything else is refused.
- Scoped tokens: Confirm that
AGENT_BACKEND_API_TOKENandDIFY_AGENT_API_TOKENare set to unique values and are not exposed to end users or browser code. - Separate knowledge data: Use a copy of internal documents, not the system of record, and keep any write-capable tools out of the pilot.
- Tested rollback: Take a backup before enabling the Agent app so the stack can return to its previous state.
Before the pilot grows, confirm that a failed sandbox run leaves no residue in shared storage and that the team can explain each outbound path.
In regulated production, the sandbox runs code on behalf of users whose actions may be subject to review. The isolation decision should be made by the security and compliance owners together with the platform team, documented before go-live and revisited with each Dify upgrade. Operators should plan the host, network and key management as one design, because the sandbox is only as isolated as the infrastructure around it. The Dify environment reference notes that workspace encryption keys can be stored locally or in Azure Key Vault, which is one of several key placement decisions to record.
- Dedicated hosts or segments: Place the sandbox and its proxy on infrastructure separated from databases and identity services, and confirm the separation with the network team.
- Default-deny network policy: Block all egress from the sandbox except named destinations, and verify the rules with negative tests from inside the sandbox.
- Managed secrets: Store
SECRET_KEY, agent tokens and workspace keys in your secrets platform, with a documented rotation process. Confirm with the vendor what rotation requires, since changingSECRET_KEYafter deployment logs out all users. - Retained evidence: Keep configuration snapshots, network policy exports, test results, upgrade records and access reviews, in a form your auditors can request.
- Change control: Require review before enabling new tools or changing sandbox settings.
Before approval, ask your independent auditor which evidence they expect, since DeployOpen prepares controls and evidence but does not issue assessments.
Limits to confirm in your own environment
The Agent app adds moving parts that the release notes and generic Docker Compose guides do not fully describe. Each card below is a check to run against your chosen Dify release and your own network before agents get access to code execution. Confirm each item in writing with your vendor or implementation partner.
Services your release actually starts
Dify 1.16.1 added an agent_ssrf_proxy, moved local_sandbox onto dedicated agent sandbox networks and introduced agent_backend. The Docker Compose docs list these as dependent components, but service names and networks can change between minor releases. Pull the Compose file for your exact target version, list every service it starts, and confirm which containers hold internet egress and which hold none. Do not assume the 1.16.1 layout carries forward unchanged.
Languages and packages in the sandbox
Agents that run Python, Node.js or shell commands only work if the sandbox image includes the interpreters, libraries and CLI tools they need. Ask which runtimes ship in the image you deploy, whether package installs are allowed at run time, and what happens to installs across sessions. If your agents need internal packages, plan how they reach the sandbox through a mirror that the egress policy permits.
CPU and memory limits for sandbox containers
Sandbox containers run untrusted or model-generated code, so an unbounded process can starve the api, worker and database on the same host. Confirm which CPU, memory, process count and execution time limits the release sets by default, where they are configured, and whether they apply to the local sandbox and the code sandbox alike. Load test a runaway script on a staging host before any production agent is published.
Behavior on air-gapped networks
The Agent app needs outbound paths for model providers, package mirrors and any tools an agent calls. On an isolated network, the SSRF proxy and sandbox egress rules decide which of those calls succeed and which fail silently. Confirm how the proxy allowlist is configured, whether package downloads and image pulls for the sandbox can run from an internal registry, and which upgrade steps need internet access.
Whether Enterprise changes the agent model
The Community edition is limited to a single workspace, while the Enterprise edition adds SSO, multiple workspaces and advanced security. Ask the vendor whether the Enterprise deployment uses the same agent backend, sandbox and proxy services, how Kubernetes deployment places these components, and whether workspace isolation for agents differs from Community. Do not rely on the Community isolation model for a multi-team rollout until this answer is in writing.
Questions teams ask before enabling the Agent app
What does enabling the Dify Agent app cost in effort, and who does the work?
Enabling the Agent app is mostly configuration, secret management and verification work on top of an existing Dify deployment, so the effort sits with whoever operates the stack. Your platform team owns the host, network segmentation, secrets and backups, while DeployOpen can plan the isolation design, configure the services and document the result under a written, fixed scope. Costs recur in the form of upgrade testing and monitoring, and they rise with the number of environments, the number of workflows that call code or shell commands, and how strict your network policy is. Ask any quote to separate one-time design and build work from ongoing support, and to name which services and environments it covers.
How long does setup and hardening take, and what drives the duration?
Duration depends on the size of the change and the state of your environment, and no fixed timeline applies across deployments. The main drivers are whether Dify already runs on a supported Docker Compose layout, how many outbound destinations the sandbox must reach, whether your egress proxy and firewall rules need changes, and how many review cycles your security team requires. Testing the sandbox against real workflows that run code or shell commands usually takes longer than the initial container start. Ask for a schedule that lists each gate, such as design sign-off, staging validation and security review, so you can see which parts depend on your team.
What does the work need from our team before we start?
You need a current Dify deployment or a documented target layout, access to the host and its network controls, and a named owner for secrets and approvals. Your team should provide the Docker Compose version in use, the host sizing, the outbound destinations your workflows need, and the policy for internal and private address ranges. Someone must also decide which workflows are allowed to run code or shell commands, because that decision determines the isolation requirements. Plan for a staging environment that matches production closely enough to test these settings before they reach users.
Can an internal team run the Agent app on its own?
An internal team with Docker, Linux networking and secrets management experience can run the Agent app, provided it understands the trust boundaries between the api, worker, agent backend, sandbox and proxy services. The harder part is keeping those boundaries correct over time, since each upgrade can change services, tokens and network rules. Teams that run it alone should own a written runbook, a test workflow that exercises code execution and a regular review of the proxy allow lists. Confirm with your staff which of these skills they already hold before deciding between an internal build and a partner-supported model.
How do Dify upgrades affect the agent services?
Upgrades can change the agent services, not just the main application images, so each release needs its own review. Dify's Docker Compose guidance says to follow the upgrade guide for the target version, back up before every upgrade and check .env.example for new variables. Dify 1.16.1 changed how the local sandbox, the agent SSRF proxy and the bearer tokens for the agent backend are wired, which shows why these services need explicit checks after an upgrade. Ask your team to confirm the release notes for each target version, rerun your sandbox test workflow in staging and verify that tokens and proxy rules still apply before promoting the change.
What should we confirm before a security review of the sandbox?
Confirm where the sandbox runs, which network it can reach, which secrets it can read and what the proxy blocks. Ask whether AGENT_BACKEND_API_TOKEN and DIFY_AGENT_API_TOKEN are generated per deployment and stored in your secrets manager, and whether SECRET_KEY is set before first start because changing it later logs out all users. Verify that SSRF_PROXY settings block internal and private ranges for the agent path and that egress from the sandbox is limited to destinations you approved. Also confirm who can enable workflows that run code and how that access is logged, since reviewers will ask for that evidence. DeployOpen can prepare these controls and documentation, but independent auditors and certification bodies issue any assessment outcome.
How the bearer tokens between services protect the agent path
Dify 1.16.1 authenticates calls between the agent services with two bearer tokens, `AGENT_BACKEND_API_TOKEN` and `DIFY_AGENT_API_TOKEN`, which the release notes say are passed to the api, worker and agent_backend services. Treat them as credentials in their own right. Any process holding the token can send requests on the agent path, so the operator's job is to decide which services hold which value, generate each token with enough randomness, and keep both out of image layers, shared compose files, and application logs. Confirm in the release notes and the environment variable reference whether the two values must differ, whether one service needs only one of them, and what format the token must take before you generate anything.
Storage and rotation are where most operators get this wrong. Keep the values in your secrets manager or in an untracked .env file with restricted file permissions, and inject them at container start rather than baking them into images. Check that your logging pipeline and any debug output do not echo environment variables from the api, worker or agent_backend containers. Rotation is a coordinated change: the token has to be updated in every service that holds it, and the stack restarted so the new value is in effect everywhere. A partial rotation will break agent calls with authentication errors, so schedule it as a planned maintenance window and rehearse it in a staging copy first.
Before you enable the agent app, write down your rotation procedure and the owner who runs it, then confirm the exact steps, restart order and any side effects on running agent sessions with the vendor documentation for your target release. Ask the vendor whether tokens are read only at startup and whether any stored data is encrypted with them, since that changes what rotation costs you. Also ask whether an upgrade can change either token name or its required format, because the upgrade guide for each release is where such changes would appear. Recording these answers alongside your secret inventory gives your security team evidence that the service-to-service trust was designed, not inherited.
