doc/user/duo_agent_platform/environment_sandbox.md
{{< history >}}
ai_duo_agent_platform_network_firewall and ai_dap_executor_connects_over_wsai_duo_agent_platform_network_firewall enabled in GitLab 18.7.ai_dap_executor_connects_over_ws enabled in GitLab 18.7.network_policy setting introduced in GitLab 18.10.allow_all_unix_sockets network policy setting introduced in GitLab 18.11.dap_instance_network_access_controls and dap_group_network_access_controls. Disabled by default.{{< /history >}}
The execution environment sandbox provides application-level network and filesystem isolation that helps protect GitLab Duo Agent Platform remote flows from unauthorized network access and data exfiltration. It is designed to help prevent data exfiltration attempts, loading of malicious code from external sources, and unauthorized data gathering while maintaining necessary connectivity for legitimate flow operations.
The execution environment sandbox is automatically applied when using a compatible Docker image with Anthropic Sandbox Runtime (SRT) installed. This includes using the default GitLab Docker image (release v0.0.6 and later) or a custom image with SRT installed.
The sandbox is enabled when:
For information about CI/CD variable differences between default and custom image configurations, see Flow execution variables.
To use the execution environment sandbox, you need:
v0.0.6 or above, or a custom image with Anthropic Sandbox Runtime (SRT) installed.The execution environment sandbox uses Anthropic Sandbox Runtime (SRT) to wrap flow execution with the following protections:
If you use a custom image, for example, with an agent-config.yml,
Anthropic SRT version 0.0.20 or later must be installed and available in the environment.
SRT is available through npm as @anthropic-ai/sandbox-runtime. The following example shows the installation stage
in a Dockerfile:
# Install srt sandboxing with cache clearing and verification
ARG SANDBOX_RUNTIME_VERSION=0.0.20
RUN npm cache clean --force && \
npm install -g @anthropic-ai/sandbox-runtime@${SANDBOX_RUNTIME_VERSION} && \
test -s "$(npm root -g)/@anthropic-ai/sandbox-runtime/package.json" && \
srt --version
At runtime, the runner checks that the SRT is available and working:
$ if which srt > /dev/null; then
$ echo "SRT found, creating config..."
SRT found, creating config...
$ echo '{"network":{"allowedDomains":["host.docker.internal","localhost","gitlab.com","*.gitlab.com","duo-workflow-svc.runway.gitlab.net"],"deniedDomains":[],"allowAllUnixSockets":false},"filesystem":{"denyRead":["~/.ssh"],"allowWrite":["./","/tmp"],"denyWrite":["/opt/.gitlab-sandbox"],"allowGitConfig":true}}' > /opt/.gitlab-sandbox/srt-settings.json
$ echo "Testing SRT sandbox capabilities..."
Testing SRT sandbox capabilities...
The following error might occur during runtime, which may indicate that dependencies for SRT are not available:
Warning: SRT found but can't create sandbox (insufficient privileges), running command directly
To resolve this:
Use bash to verify the image with the following command:
docker run --rm -it <image>:<tag> /bin/bash
Use srt:
srt ls
If the following error displays, you must install additional dependencies to your custom image:
Error: Sandbox dependencies are not available on this system. Required: ripgrep (rg), bubblewrap (bwrap), and socat.
When the execution environment sandbox is applied, the following restrictions are enforced.
Use an agent-config.yml file to configure some of your sandbox settings.
By default, the sandbox permits access to the following configurations:
Only the environment variables and parameters required to run DAP and Git operations are accessible from the sandbox environment.
The sandbox enforces the following filesystem restrictions:
~/.ssh) are blocked../) and /tmp./opt/.gitlab-sandbox (used for platform-internal files like sandbox settings).SRT is included in the default GitLab-provided Docker image. You can also install SRT on a custom image.
When SRT is installed, flows can access only the following domains by default. These domains are always allowed and cannot be removed:
localhosthost.docker.internalgitlab.com, *.gitlab.com)If you use a custom image without SRT, no network restrictions are applied and the flow can access any domain reachable from the runner.
[!note] The
network_policydoes not allow"*"in theallowed_domainsor thedenied_domains. SRT does not support turning on all network traffic. However, wildcards are allowed as part of domains, for example"*.domain.com".
When a top-level group owner on GitLab.com or instance administrator on GitLab
Self-Managed configures network access controls, those settings define the
baseline policy for all flows. The Allow projects to extend network sandbox
settings checkbox determines which settings are applied when project owners
configure them in agent-config.yml.
Flexible mode (Allow projects to extend network sandbox settings enabled):
allowed_domains from agent-config.yml are merged with the admin allow-list.denied_domains from agent-config.yml are merged with the admin deny-list.include_recommended_allowed in agent-config.yml overrides the admin setting.allow_all_unix_sockets in agent-config.yml overrides the admin setting.Strict mode (Allow projects to extend network sandbox settings disabled):
denied_domains from agent-config.yml are merged with the admin deny-list.include_recommended_allowed can only be set to false to tighten a setting the admin enabled.
It has no effect when the admin has it disabled.allow_all_unix_sockets can only be set to false to tighten a setting the admin enabled.
It has no effect when the admin has it disabled.allowed_domains from agent-config.yml are ignored.To allow or deny additional domains, add a network_policy to your agent-config.yml file:
network_policy:
include_recommended_allowed: true # default: false
allow_all_unix_sockets: true # default: false
allowed_domains:
- my-own-site.com
denied_domains:
- malicious.com
Use the allow_all_unix_sockets setting to grant the flow access to all Unix domain sockets on
the host. This is disabled by default.
[!warning] Enabling
allow_all_unix_socketsgrants access to all Unix sockets. Enable this only when necessary and only in trusted environments.
{{< history >}}
dap_instance_network_access_controls and dap_group_network_access_controls. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
In addition to project-level agent-config.yml settings,
administrators and top-level group owners can manage network access controls through the GitLab UI.
These settings are stored at the instance level (GitLab Self-Managed) or top-level group level
(GitLab.com) and are inherited by all projects underneath.
For a description of how these settings combine with project-level agent-config.yml,
see Administrator network policy controls.
Prerequisites:
To configure instance-level network access controls:
agent-config.yml
file.Prerequisites:
To configure group-level network access controls:
duoSettingsUpdate
GraphQL mutation.ai_settings_attributes parameter.aiDomainSettingsInstanceUpdate
and
aiDomainSettingsNamespaceUpdate
GraphQL mutations.To give your flows access to a set of external domains used for package registries and development tools,
turn on the include_recommended_allowed setting.
This setting is disabled by default (false). To turn it on, in your agent-config.yml file,
set include_recommended_allowed to true.
When network access controls are enabled in strict mode (Allow projects to extend network sandbox settings disabled),
you can only disable include_recommended_allowed. Setting it to true has no effect when the
admin has it disabled.
[!warning] Enabling
include_recommended_allowedpermits network access to a broad set of external domains. These egress endpoints could potentially be used to exfiltrate data from your environment. Enable this only when necessary and only in trusted environments.
This setting turns on access to the following domains:
github.comwww.github.comapi.github.comnpm.pkg.github.comraw.githubusercontent.compkg-npm.githubusercontent.comobjects.githubusercontent.comcodeload.github.comavatars.githubusercontent.comcamo.githubusercontent.comgist.github.comgitlab.comwww.gitlab.comregistry.gitlab.combitbucket.orgwww.bitbucket.orgapi.bitbucket.orgregistry-1.docker.ioauth.docker.ioindex.docker.iohub.docker.comwww.docker.comproduction.cloudflare.docker.comdownload.docker.comgcr.io*.gcr.ioghcr.iomcr.microsoft.com*.data.mcr.microsoft.compublic.ecr.awscloud.google.comaccounts.google.comgcloud.google.comstorage.googleapis.comcompute.googleapis.comcontainer.googleapis.comartifactregistry.googleapis.comcloudresourcemanager.googleapis.comoauth2.googleapis.comwww.googleapis.comlogin.microsoftonline.compackages.microsoft.comdotnet.microsoft.comdot.netdev.azure.coms3.amazonaws.com*.s3.amazonaws.com*.codeartifact.amazonaws.com*.s3.api.aws*.codeartifact.api.awsdownload.oracle.comyum.oracle.comregistry.npmjs.orgwww.npmjs.comwww.npmjs.orgnpmjs.comnpmjs.orgyarnpkg.comregistry.yarnpkg.compypi.orgwww.pypi.orgfiles.pythonhosted.orgpythonhosted.orgtest.pypi.orgpypi.python.orgpypa.iowww.pypa.iorubygems.orgwww.rubygems.orgapi.rubygems.orgindex.rubygems.orgruby-lang.orgwww.ruby-lang.orgrubyonrails.orgwww.rubyonrails.orgrvm.ioget.rvm.iocrates.iowww.crates.ioindex.crates.iostatic.crates.iorustup.rsstatic.rust-lang.orgwww.rust-lang.orgproxy.golang.orgsum.golang.orgindex.golang.orggolang.orgwww.golang.orggoproxy.iopkg.go.devmaven.orgrepo.maven.orgcentral.maven.orgrepo1.maven.orgjcenter.bintray.comgradle.orgwww.gradle.orgservices.gradle.orgplugins.gradle.orgkotlin.orgwww.kotlin.orgspring.iorepo.spring.iopackagist.orgwww.packagist.orgrepo.packagist.orgnuget.orgwww.nuget.orgapi.nuget.orgpub.devapi.pub.devhex.pmwww.hex.pmcpan.orgwww.cpan.orgmetacpan.orgwww.metacpan.orgapi.metacpan.orgcocoapods.orgwww.cocoapods.orgcdn.cocoapods.orghaskell.orgwww.haskell.orghackage.haskell.orgswift.orgwww.swift.orgarchive.ubuntu.comsecurity.ubuntu.comubuntu.comwww.ubuntu.com*.ubuntu.comppa.launchpad.netlaunchpad.netwww.launchpad.netdl.k8s.iopkgs.k8s.iok8s.iowww.k8s.ioreleases.hashicorp.comapt.releases.hashicorp.comrpm.releases.hashicorp.comarchive.releases.hashicorp.comhashicorp.comwww.hashicorp.comrepo.anaconda.comconda.anaconda.organaconda.orgwww.anaconda.comanaconda.comcontinuum.ioapache.orgwww.apache.orgarchive.apache.orgdownloads.apache.orgeclipse.orgwww.eclipse.orgdownload.eclipse.orgnodejs.orgwww.nodejs.orgsourceforge.net*.sourceforge.netpackagecloud.io*.packagecloud.iojson-schema.orgwww.json-schema.orgjson.schemastore.orgwww.schemastore.org*.modelcontextprotocol.ioIf sandboxing is unavailable or cannot be applied:
This ensures flows continue to execute even if sandboxing cannot be enabled, while alerting you to the situation.