Dify Enterprise agent sandbox on Kubernetes

Why the Dify Enterprise agent sandbox on Kubernetes needs its own approval

The platform team needs Agent apps to run in Dify Enterprise on a cluster the organization controls, and the agent sandbox is the part of that design that changes the cluster itself. Agent apps execute model-driven steps in an isolated runtime, and the controller that provisions that runtime needs permissions a namespace owner usually does not hold, such as creating cluster-scoped resources or granting workloads elevated access. Because those rights reach beyond any one team, the cluster-admin decision should be made first, before anyone installs anything, and it should be recorded with the exact scope granted.

Sandboxing matters because the Dify 1.16.1 release notes, as published on the Dify GitHub releases page, describe three security changes that depend on it: agent sandbox network isolation through a Squid proxy, token-based API authentication between services, and sandboxed Jinja2 template rendering. Each one shapes what the controller must be allowed to do, from routing sandbox egress through the proxy to handling the service tokens it uses. Before the approval request, confirm the controller's resource types, API versions, service accounts and required permissions with Dify for the specific release you run, and ask for them in writing. Do not copy permissions from a forum post or an older version of the chart.

Put the approval package together with the security team and the cluster owners: the list of requested cluster-scoped permissions, the namespaces the controller will touch, the network paths the sandboxes need, and the rollback plan if the controller must be removed. A reviewer can then decide whether the scope is acceptable instead of approving a broad role that was described only as required for Dify. If your organization cannot grant the rights, the shared sandbox mode described in the next section is the route to evaluate.

What the agent-sandbox controller does inside the cluster

An Agent app run reaches its sandbox through a chain of services, and you should be able to trace that chain on paper before changing the cluster. The Dify services send the execution request for the agent's tool and code steps to the sandbox layer. The agent-sandbox controller then provisions an isolated execution environment for that work. The Dify 1.16.1 release notes describe token-based API authentication between services, so each hop should carry credentials that you can rotate and audit. Confirm with Dify how the request is routed, which service holds the token, and where the token is stored in your cluster.

The Dify docs supplied for this topic do not fully describe the controller's installation footprint, so several points must be confirmed before a change request is written. Ask whether the controller is cluster-scoped or namespace-scoped, which custom resource definitions it installs, what permissions its service account needs, and how its version is paired with each Dify Enterprise release. The Dify Enterprise resources checklist sets Kubernetes 1.24 or later and Helm 3.14 or later as baseline requirements. Those are minimums for the platform, so they do not confirm the controller's own compatibility matrix.

Outbound traffic from the sandbox is the control that most affects data exposure. The Dify releases page lists agent sandbox network isolation through a Squid proxy in the 1.16.1 security changes, so all sandbox egress should pass through that proxy rather than through a direct route. The Dify environment reference describes SSRF_PROXY settings that block internal and private IP ranges in the Docker Compose deployment. Confirm whether the Enterprise sandbox proxy applies the same block list, then test it by attempting a request from a sandbox to an internal address and to an approved external endpoint.

Which sandbox deployment option fits your cluster

This table compares the dedicated controller install, shared sandbox mode for restricted clusters, and isolated runtime mode set per environment. Read each row against your cluster approval process and your workspace tenancy model. The main takeaway is that the controller install needs cluster-admin approval, so confirm who can grant it before choosing a path.

Option	What it requires from the cluster owner	Isolation between workspaces	When it fits
Dedicated controller install	Cluster-admin approval to deploy the agent-sandbox controller, plus spare cluster capacity for sandbox workloads	Depends on how the controller and network policies are configured. Confirm the boundary in the release documentation.	Clusters where the platform team can grant cluster-admin rights and Agent apps run across several workspaces
Shared sandbox mode	A cluster owner who approves a shared sandbox setup that all Agent apps use in the cluster	Workspaces share one sandbox runtime, so confirm what separation the mode provides before onboarding teams.	Restricted clusters where cluster-admin approval for the controller install is not granted
Isolated runtime mode	Environment setup in Dify Enterprise, with CPU quotas taken from the license and capacity for each environment	Separates runtime by environment, so staging and production runs stay apart. Confirm how workspaces are bounded.	Teams that promote Agent apps from staging to production and want each environment's runtime kept separate
Mixed approach (illustrative)	Cluster-admin approval for production and a restricted setup for staging, with environment quotas for both	Production runtime is separated from staging, and workspace boundaries follow the mode chosen for each cluster.	A restricted staging cluster paired with a production cluster that allows the controller install

How to deploy the agent sandbox on Kubernetes

This sequence takes a Dify Enterprise team from version checks to a verified agent sandbox on Kubernetes. Each step closes with a check, so the cluster owner, the platform team and the approver can confirm the sandbox works and can be removed cleanly if it does not.

Confirm release and cluster version compatibility
The platform engineering lead compares the Dify Enterprise release you plan to run with the resources checklist, which requires Kubernetes 1.24 or later, Helm 3.14 or later, PostgreSQL 14 or later, Redis 6 or later, a Qdrant vector database and S3-compatible or cloud object storage. Confirm that your release includes the agent sandbox security changes described in the Dify 1.16.1 release notes, including Squid proxy network isolation and token-based service authentication. Record the output of kubectl version and helm version in the change record. This step is done when the compatibility record is signed by the platform lead.
Draft the cluster-admin approval request
Write the approval request before anyone touches the cluster. List every cluster-scoped object the controller needs, such as custom resource definitions, cluster roles and bindings, plus the namespaces, service accounts, network policies and proxy egress rules it will create or read. Ask the vendor to provide the full manifest set so the approver can review the actual objects, not a summary. Name the people who will install, operate and remove the controller. The step is done when the cluster admin signs the request and the approval reference is attached to the change record.
Install the controller in the agreed namespace
After approval, a cluster admin installs the agent-sandbox controller from the package supplied with your Dify Enterprise release, into the namespace named in the approval. Do not widen permissions beyond the approved list during installation. Confirm the package source and checksum with your vendor before applying it. Check that the controller pods are running and ready, that the custom resource definitions exist, and that the controller logs show no repeated errors or restarts over the first few minutes. Record the controller version and the namespace in the change record.
Select shared or dedicated sandbox mode
Choose the sandbox mode for each environment. Shared mode runs sandboxes for several workspaces on common infrastructure, which suits restricted clusters where dedicated capacity is hard to justify. Dedicated mode gives each workload its own runtime, which suits teams that need stronger separation between workspaces. Ask the vendor which settings control the mode in your release, how CPU quotas apply in each mode, and what isolation the proxy and network policies provide in shared mode. Apply the choice to the staging environment first. The step is done when the selected mode is recorded for each environment and shown in the Enterprise console.
Run a test Agent app invocation
The Dify application owner creates a test Agent app in a non-production workspace. The app should call one tool that makes a single outbound request to an approved external endpoint. Run the app once from the console and once through the API. Watch the namespace while the run executes. The check is passed when a sandbox pod is created for the invocation, the run completes with the expected output, and the pod is removed or released according to the mode you selected. If no pod appears, stop and review the controller logs and the workspace configuration before continuing.
Verify outbound calls in proxy logs
The network owner confirms that all sandbox egress passes through the Squid proxy. Run two tests: one request to the approved external endpoint, which should succeed, and one request to an internal or private address, which should be denied. Search the proxy logs for both requests and record the destinations, timestamps and decisions. The step is done when the allowed request appears as permitted, the internal request appears as denied, and no sandbox traffic bypasses the proxy. Keep these log excerpts as evidence for your security review.
Roll back the controller if verification fails
If any earlier check fails, disable the sandbox mode in the affected environment and stop test Agent apps before you remove anything. Uninstall the controller using the same package and version you installed, then remove the approved cluster role bindings and namespace objects. Remove custom resource definitions only after confirming that no sandbox objects remain, because deleting them also deletes their custom resources. Confirm that no sandbox pods are running, that core Dify services are healthy and that test apps are reverted or flagged. Record the rollback in the change record and return to the approval step with the findings.

Choosing shared or dedicated sandbox mode by cluster situation

When your platform team holds cluster-admin rights, it can install the agent-sandbox controller directly, so the work centers on records, verification and questions to Dify rather than on negotiating approval. The risk is that a fast install skips the evidence an auditor will later ask for.

Approval path: Record the decision to install the controller, its namespace and the chosen sandbox mode in your change tracker, even when no board reviews it.
Image and artifact handling: Confirm every image and chart the controller pulls, the version tag for each, and whether you mirror them into an internal registry and pin digests.
Workspace isolation: Ask Dify how sandboxes are separated between workspaces in shared mode and what isolation remains between tenants. Do not assume that a workspace boundary is also a sandbox boundary.
Rollback: Ask how the controller is removed or switched to another mode, and whether the switch requires restarting Dify services.

Before the first production change, confirm that the platform team can reproduce the install from version-controlled manifests.

Security controls the sandbox must be checked against

The agent sandbox runs code on behalf of agent apps, so it sits at the boundary between model output and your network. The controls below work together: outbound traffic, service authentication, template handling, cluster privileges and secrets. Verify each one in your own cluster before you approve the sandbox for production use.

Outbound isolation through the proxy

Dify 1.16.1 release notes describe agent sandbox network isolation through a Squid proxy. Treat this as a claim to test, not a guarantee. From a sandbox pod, attempt direct connections to the internet, to other pods, to node addresses and to cloud metadata endpoints, and confirm that only the proxy path succeeds. Record the Dify version you tested, because the isolation behavior depends on it and must be rechecked after each upgrade.

SSRF_PROXY settings and private ranges

The environment reference says SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges. Confirm which requests in your deployment go through that proxy and which go through the sandbox proxy, since the two paths may not share the same rules. Test with addresses in private ranges and with hostnames that resolve to private addresses, and check the results in both the API and worker logs.

Token-based authentication between services

Dify 1.16.1 adds token-based API authentication between services. Confirm that the sandbox can only call the internal endpoints it needs, that calls without a valid token are rejected, and that tokens are scoped to a single service. Check how tokens are generated, where they are stored, and how they rotate when a pod is replaced or a release is upgraded.

Sandboxed Jinja2 template rendering

Workflow prompts and templates can contain Jinja2 expressions that run inside the sandbox. Test template inputs that try to read files, import modules, reach the network or access environment variables. Confirm that the rendering sandbox blocks these actions in the version you run, and repeat the test after upgrades because a template engine change can reopen a path that was closed earlier.

Scope of cluster-admin permissions

The controller installation needs cluster-level permissions, so the approval should be narrower than unrestricted cluster admin where your policy allows. Ask the vendor which resources, verbs and namespaces the controller requires, then compare that list with the Helm chart and the generated RBAC objects. Review any ClusterRole or webhook the install creates and document who can grant or change them later.

Secrets for SECRET_KEY and model credentials

SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, and changing it after deployment logs out all users. Store it in your secrets manager and keep it out of Helm values files in source control. Confirm that model and tool credentials used by sandboxed code are not mounted into sandbox pods unless required, and that rotation of each secret has a tested runbook.

What changes for operators once the sandbox is running

Day-two work starts with confirming that the agent-sandbox controller and its sandbox pods are healthy, because an Agent app that cannot get a sandbox fails when a user runs it, not when it is deployed. Set alerts on controller restarts, sandbox pods stuck in pending or failed states, and node pressure on the workers that host sandboxes, and compare them with a baseline captured during acceptance testing. Review the Squid proxy logs on a fixed schedule. Blocked outbound requests show either a workflow that needs a destination nobody has approved yet or an agent attempting to reach an internal address. Decide in advance who triages those entries, what evidence is needed to add a destination to the allow list, and who must approve that change before it takes effect.

Plan controller upgrades as a recurring task. Dify minor releases arrive roughly monthly, based on the dates on the GitHub releases page, with 1.16.0 on July 17, 2026 and 1.17.0 on August 25, 2026 as examples. Each new Enterprise release is an opportunity to review the sandbox security notes, the proxy configuration and the token-based service authentication. Take a backup before every upgrade. The Docker Compose docs give this advice for Compose deployments, and the same discipline applies on Kubernetes. Confirm the backup scope, the restore procedure and the expected downtime with the Enterprise upgrade guide for your target version, and rehearse a restore in a non-production cluster before you rely on it.

The controller version must move together with the Enterprise release it serves. Before upgrading Enterprise, confirm in writing which controller version the target release expects, then test that pairing in staging with representative Agent apps. A change to sandbox mode, such as moving between the shared mode used in restricted clusters and a dedicated setup, should go through the same change review as other production changes: a written request, a named approver, a tested rollback and a record of who executed the change. Keep these records with your other production change logs so auditors and incident responders can trace when a sandbox behavior changed and why.

Limits to confirm before you commit to a design

The supplied facts establish that the agent sandbox needs a controller on Kubernetes, a cluster-admin approval and a shared mode for restricted clusters, but they do not settle the operational details. Each card below names the party who can answer, so the design review ends with written answers rather than assumptions.

Sandbox resource requirements

The facts do not give CPU, memory or storage figures for the agent-sandbox controller or for the sandbox pods it creates. Ask Dify for the sizing guidance that matches your Enterprise release, then compare it with your node pool and any CPU quota that your license applies to deployed environments. Confirm whether sizing changes with the number of concurrent agent runs.

Controller versions per Enterprise release

Which agent-sandbox controller version each Dify Enterprise release expects is not stated in the supplied facts. Ask Dify for a compatibility matrix before you pin a Kubernetes version or schedule an Enterprise upgrade. Also confirm whether the controller can be upgraded independently of the Enterprise chart.

Offline image mirroring

Restricted clusters often pull images only from an internal registry. Ask Dify whether every image the controller and sandbox pods use can be mirrored, and which tags must be copied for a given release. Your platform team should confirm that the internal registry can hold these images and that the signing and scanning steps you require still apply to mirrored copies.

Isolation in shared mode

Shared mode lets workspaces use common sandbox runtime capacity, which changes what separates one team's agent runs from another's. Ask Dify how tenant data, files and network paths are kept apart in shared mode, and whether the Squid proxy isolation described for version 1.16.1 applies in every mode. Your security team should decide whether shared mode is acceptable for production workspaces.

Cluster-scoped permissions

The approval step grants a cluster admin the rights the controller needs, but the exact cluster-scoped resources, verbs and bindings are not in the supplied facts. Ask Dify for the complete list in writing, then have the cluster owner review it against your policy for custom resource definitions, cluster roles and namespace creation. Record who approved the list and when.

Pod security exceptions

Sandbox pods that run agent code may need settings that a restricted Pod Security profile rejects. Ask Dify which securityContext fields and capabilities the sandbox pods require, then ask your security team whether a namespace-scoped exception is acceptable or whether shared mode must run in its own namespace. Confirm the answer with a test deployment before any production change.

Questions teams ask before deploying the agent sandbox

What does the agent sandbox work cost, and who pays for it?

The cost comes from three sources: the Dify Enterprise license, DeployOpen's fixed-scope fee for the work agreed in writing, and your own cluster and staff time. The Dify pricing page lists the self-hosted Enterprise edition as custom priced, so the license figure comes from Dify directly. Cluster capacity is paid through your cloud account or already sits in your data center. One-time costs include scoping, cluster access setup, approval paperwork and the first install. Recurring costs include cluster capacity, upgrades and any support retainer. Cost rises with the number of clusters, the need for air-gapped delivery and the number of approval steps. Ask the quote to split these lines and to state exclusions, such as upgrades after go-live.

How long do cluster approval and deployment usually take?

No duration is published for this work, so treat any figure you hear as something to confirm in writing. The approval step usually sets the pace. It depends on your change board, the security review of the controller's permissions, and who holds cluster-admin rights for the target cluster. Other drivers include whether the cluster meets the baseline in the Dify Enterprise resources checklist, which lists Kubernetes 1.24 or later and Helm 3.14 or later, whether container images must be mirrored into a restricted registry, and how many clusters need the change. Ask for a plan that shows the approval as its own milestone with a named approver, so that a delay in review does not hide inside the build phase.

What does the work need from platform and security teams?

Both teams have defined inputs before any install begins.

Platform team: a namespace, the Kubernetes and Helm versions from the resources checklist, a storage class, node capacity, ingress and DNS, and a decision on which cluster will host the controller.
Security team: review of the RBAC the controller requests, egress rules, and sign-off on the sandbox network isolation. The Dify 1.16.1 release notes describe that isolation through a Squid proxy, so the security team should confirm how it fits your proxy and firewall policy.
Shared responsibility: agreed owners for SSRF proxy settings, secret handling and change records.

Write these inputs into the scope so that neither team learns of a requirement during the install.

Can our internal team deploy the agent sandbox without outside help?

Yes, a capable internal team can deploy it, provided it has Kubernetes operators who can work through the cluster-admin approval, people comfortable with Helm, and time to test before go-live. The harder part is ongoing ownership. Your team would need to track each monthly minor release, which the Dify GitHub releases page shows arriving roughly monthly, and reassess RBAC and network policy after each change. Outside help is most useful in three places: scoping the approval package, hardening the cluster configuration, and assembling the evidence your reviewers ask for. Decide early which of these your team will own and which it will hand to a partner under a written scope.

What should a quote for this work include?

A quote should follow from a written scope, since DeployOpen agrees scope, deliverables and timelines before work starts. Ask for these items:

The number of clusters and environments in scope, including whether staging and production are separate.
The approval path, the people who sign off, and whether the partner prepares the approval package.
The Dify Enterprise version targeted and how the release path after go-live is handled.
Assumptions about air-gapped delivery, image transfer and the registry used.
Acceptance tests for the shared sandbox mode in restricted clusters.
Exclusions, including licensing, cluster capacity and any support retainer.

A quote that lacks these items leaves the approval and the post-go-live effort unpriced.

How do air-gapped delivery and several clusters change the effort?

Each cluster repeats the approval and the install, so effort grows with the cluster count even when the configuration is reused. In an air-gapped network, the chart, container images and any Dify Enterprise license artifacts must be moved across a controlled path, and each transfer needs a record. Restricted clusters may run in the shared sandbox mode, which changes isolation between workspaces, so the team should decide which clusters use shared mode and which get dedicated capacity. Confirm with Dify which artifacts an offline install needs and which Helm and image versions the target Kubernetes version supports before you commit to a plan.

What usually breaks after the agent sandbox goes live?

The most common problems come from changes that happen after the install, not from the install itself. Upgrades are the first risk, because minor releases arrive roughly monthly and each one may change controller permissions or proxy behavior. Cluster policy drift is the second, such as a new admission rule or node pool change that blocks sandbox egress or starves the pods of CPU and memory. Dependency mismatches come third, for example a PostgreSQL, Redis or Qdrant version below the minimum in the resources checklist. Set up monitoring for sandbox pods and proxy errors, record every change in the cluster, and read each release note before upgrading the staging environment first.

How DeployOpen scopes and delivers the agent sandbox work

DeployOpen plans and implements the agent sandbox controller for Dify Enterprise on Kubernetes inside your own clusters and cloud accounts. We start with a written scope that sets out the cluster-admin approval path, the runtime mode decision and the checks that show agent apps run as intended.

How we scope

Confirm the Kubernetes version, Helm version and cluster layout against the Enterprise resources checklist before any change is planned.
Agree in writing which Agent apps will run in sandboxes and which runtime mode fits your clusters.
Document who approves the cluster-admin change, what they review and which namespaces the work touches.

How we build

Deploy the agent-sandbox controller with Helm into the namespace your Enterprise license is bound to.
Configure network isolation for sandboxed runs and verify that outbound traffic passes only through the approved proxy path.
Test sandboxed Agent app runs end to end, including failures, timeouts and resource limits, before handing the environment over.

How we hand over

Deliver the Helm values, manifests and change records in your repository, along with a runbook for upgrades and rollback.
Walk your platform and security teams through the approval evidence, network policy and test results they will need to keep.
Record any shared sandbox mode decisions for restricted clusters so later administrators understand the trade-offs made.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after the fixed-scope work is complete.
Retainer work can cover reviewing each Dify minor release for sandbox, proxy and controller changes before you upgrade.
Ask any delivery partner to confirm how they handle controller version pinning, rollback and access to your cluster between engagements.