Local sandbox | GitLab Docs
/ Local sandbox Tier : Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Status : Experiment Introduced as an experiment in GitLab for VS Code 6.80.0, during the GitLab 19.0 release. Introduced as an experiment in GitLab Duo CLI 8.94.0, during the GitLab 19.1 release. Sandbox configuration file introduced in GitLab Language Server 9.4.0 and GitLab Duo CLI 9.4.0, during the GitLab 19.3 release.
The local sandbox restricts what GitLab Duo agents can read, write, and reach on the network when they run on your computer. It applies to agents in your editor and in the GitLab Duo CLI. The sandbox is off by default. Until you turn it on, the risks described in security considerations for editor extensions and CLI tools apply. For flows that run on GitLab Runner, see remote execution environment sandbox . How the sandbox works When the sandbox is on, GitLab Duo runs agent actions in a separate worker process that the operating system restricts.
Agent actions include shell commands, file reads and writes, file searches, and directory listings. Local MCP servers that use the stdio transport run in the same kind of sandbox. The sandbox removes known credential environment variables, such as GITLAB_TOKEN , GITHUB_TOKEN , AWS_SECRET_ACCESS_KEY , and SSH_AUTH_SOCK , from the environment of processes in the sandbox. Other environment variables are not removed. By default, the sandbox also blocks: Reads from common credential and personal directories.
Writes outside the workspace and the temporary directory. Network access to every host except your GitLab instance. For the full list, see default sandbox rules . The sandbox is a process sandbox, not a container or a virtual machine. The following run outside the sandbox: Your editor and GitLab Duo itself. Connections to MCP servers that use the http or sse transport. MCP servers with "sandboxEnabled": false . GitLab Duo CLI hooks .
The sandbox reduces the risks of running agents locally, but does not remove them. Agents can still read and change files in your workspace, and send data to the hosts the sandbox allows. If the sandbox is on but cannot start, for example because a dependency is missing, agent actions and local MCP servers fail with an error. They do not run without the sandbox. This behavior is different from the remote execution environment sandbox, which runs flows without the sandbox and shows a warning.
Supported platforms Operating system Supported macOS Yes Linux Yes, with prerequisites Windows No Prerequisites On Linux, install bubblewrap and socat . For example: On Debian or Ubuntu: shell sudo apt-get install bubblewrap socat On Fedora: shell sudo dnf install bubblewrap socat On macOS, no additional software is required. Turn on the sandbox To turn on the sandbox: In VS Code, open the settings: For macOS, press Command + , .
For Windows or Linux, press Control + , . Search for gitlab.duoAgentPlatform.sandbox.enabled . Select the Enable Sandboxing checkbox. Alternatively, on the bottom status bar, select Duo ( ), then select Enable Agent Sandboxing . The sandbox setting is available only in alpha builds of the GitLab Duo plugin for JetBrains IDEs. In your IDE, in the top bar, select your IDE’s name, then select Settings . In the left sidebar, select Tools > GitLab Duo .
Under GitLab Duo Agent Platform , select the Enable Sandboxing checkbox. Select OK or Save . Start the GitLab Duo CLI with the --sandbox option set to true : shell duo --sandbox true Alternatively, set the DUO_SANDBOX_ENABLED environment variable: shell export DUO_SANDBOX_ENABLED = true Check sandbox status To check whether the sandbox is on and available: On the bottom status bar, select Duo ( ). The menu shows the sandbox status, for example Agent Sandboxing: Enabled or Agent Sandboxing: Missing Dependencies .
For details, open the Command Palette, run GitLab: Diagnostics , and go to the GitLab Duo Agent Sandboxing section. In the status bar, select Duo ( ). The menu shows the sandbox status, for example Agent Sandboxing: Enabled or Agent Sandboxing: Missing Dependencies . Start the GitLab Duo CLI with the sandbox turned on: shell duo --sandbox true Run the /doctor command. Go to the Sandbox section. The Sandbox section reports on the current session only.
If you start the CLI without --sandbox true or DUO_SANDBOX_ENABLED=true , the section shows the sandbox as turned off. Each status check reports whether: Process sandboxing is enabled in settings. Process sandboxing is supported on this platform. System dependencies required for process sandboxing are installed. Default sandbox rules These rules apply to agent actions and to local MCP servers when the sandbox is on. Network Processes in the sandbox can connect only to the host and port of your GitLab instance URL.
If your instance URL does not include a port, the sandbox uses 443 for https and 80 for http . All other hosts are blocked, including package registries. To allow more hosts, customize the sandbox rules . The sandbox checks only the host and port of each connection. It does not inspect the requests. Agents can send data to any project or account on a host the sandbox allows. File system read Processes in the sandbox cannot read: Credential files and directories, such as ~/.ssh/ , ~/.gnupg/ , ~/.aws/ , ~/.azure/ , ~/.kube/config , ~/.docker/config.json , ~/.netrc , ~/.git-credentials , ~/.npmrc , and ~/.pypirc . ~/.config/ , except ~/.config/git/ .
Personal directories: ~/Documents/ , ~/Downloads/ , ~/Desktop/ , ~/Pictures/ , ~/Movies/ , and ~/Music/ . Shell history: ~/.bash_history and ~/.zsh_history . On macOS, ~/Library/Application Support/ , ~/Library/Containers/ , ~/Library/Group Containers/ , and ~/Library/Keychains/ . On Linux, and on macOS in VS Code, processes in the sandbox can read only an allowed set of paths. The allowed paths include the workspace, system directories such as /usr/ , /bin/ , and /etc/ , the temporary directory, the GitLab Duo configuration directory, your Git configuration, and common Node.js version manager directories.
On macOS in JetBrains IDEs and the GitLab Duo CLI, processes in the sandbox can read any path that is not in the blocked list. An allowed path takes precedence over a blocked path that contains it. For example, if your workspace is in ~/Documents/ , processes in the sandbox can read the workspace. File system write Processes in the sandbox can write only to the workspace, the temporary directory, and a few log directories that the sandbox runtime uses.
In the workspace, processes in the sandbox cannot write to: .git/hooks/ and .git/config .gitlab-ci.yml and .gitlab/ .gitconfig and .gitmodules Shell startup files, such as .bashrc , .zshrc , and .profile Editor configuration directories: .vscode and .idea In the GitLab Duo CLI, if you use the --cwd option to open a workspace from another directory, the rules for .git/config , .gitmodules , shell startup files, and editor configuration directories apply to the directory where you started the CLI, not to the workspace.
To keep these rules on the workspace, start the CLI from the workspace directory. Customize sandbox rules You can add rules to the defaults in a sandbox configuration file. Your rules apply to every workspace. To customize sandbox rules: Create a sandbox.json file in the file location . Add the rules you need. For example, to let agents install packages from the npm registry and read a directory in your home directory: json { "network" : { "allowedDomains" : [ "registry.npmjs.org" ] }, "filesystem" : { "allowRead" : [ "~/reference-docs/" ], "allowWrite" : [ "~/.npm/" ] } } npm stores downloaded packages in ~/.npm/ , so the example also allows writes there.
Save the file. Restart your IDE or the GitLab Duo CLI. In the GitLab Duo CLI, you can use a different file with the --sandbox-config option or the DUO_SANDBOX_CONFIG environment variable. Use an absolute path or a path that starts with ~/ . The sandbox must also be turned on: she
The rest of this page is on the live site.