Local sandbox

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

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:

duo --sandbox true

export DUO_SANDBOX_ENABLED=true

Check sandbox status

To check whether the sandbox is on and available:

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:

1. Create a sandbox.json file in the file location.

2. 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.

3. Save the file.

4. 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:

duo --sandbox true --sandbox-config ~/sandbox-strict.json

File location

The file is at ~/.gitlab/duo/sandbox.json.

If you set the XDG_CONFIG_HOME environment variable, the file is at $XDG_CONFIG_HOME/gitlab/duo/sandbox.json.

Configuration file reference

The file supports the following keys. Unless stated otherwise, each key takes a list of strings.

Your rules add to the default rules. You cannot remove:

• Write access to the workspace and the temporary directory.
• Network access to your GitLab instance.
• The blocked write paths in the workspace.

If the file is not valid JSON or contains a key that is not in this table, GitLab Duo ignores the whole file and uses the default rules. The error is written to the GitLab Duo log.

Configure the sandbox for an MCP server

Some local MCP servers need access that the default rules block. For example, an MCP server that reads its own configuration from ~/.config/ cannot start.

To change the sandbox rules for one MCP server:

1. Open your user MCP configuration file.

2. In the server configuration, add a sandbox object. For example:

   json

   {
     "mcpServers": {
       "gitlab": {
         "type": "stdio",
         "command": "glab",
         "args": ["mcp", "serve"],
         "sandbox": {
           "allowRead": ["~/.config/glab-cli/"]
         }
       }
     }
   }

   This example uses the glab configuration directory on Linux. On macOS, use ~/Library/Application Support/glab-cli/.

3. Save the file.

4. Restart your IDE or the GitLab Duo CLI.

The sandbox removes credential environment variables from an MCP server, even when you set them in the server’s env object.

MCP server sandbox settings

The sandbox object applies only to MCP servers that use the stdio transport. It supports the following keys:

Where you set the sandbox object affects which keys apply:

• User configuration: All keys apply.
• Workspace configuration (.gitlab/duo/mcp.json): Only denyRead applies. A project can restrict a server, but cannot give it more access. GitLab Duo ignores the other keys and logs a warning.
• Plugins: The sandbox object is ignored.

Troubleshooting

When working with the local sandbox, you might encounter the following issues.

Error: Sandbox is enabled but sandbox provider is not available (missing_dependencies)

You might get this error when the sandbox is on and required software is not installed. In VS Code, a warning also lists the missing dependencies.

To resolve this issue, install the prerequisites, then restart your IDE or the GitLab Duo CLI.

Error: Sandbox is enabled but sandbox provider is not available (unsupported_platform)

You might get this error when the sandbox is on and your operating system is not supported.

To resolve this issue, turn off the sandbox:

• In VS Code, in the settings, search for gitlab.duoAgentPlatform.sandbox.enabled, then clear the Enable Sandboxing checkbox.
• In the GitLab Duo CLI, unset the DUO_SANDBOX_ENABLED and DUO_SANDBOX_CONFIG environment variables, then start the CLI without the --sandbox and --sandbox-config options.

Error: Operation is blocked by sandbox.

You might get this error when an agent action tries to read, write, or connect to something that the sandbox rules block.

To resolve this issue, if the agent needs the access, add a rule to your sandbox configuration file.

MCP server fails to start

When the sandbox is on, a local MCP server might fail to start because:

• The sandbox cannot start. The error includes Sandbox is enabled but sandbox provider is not available. To resolve this issue, install the prerequisites.
• The server reads files or connects to hosts that the sandbox blocks. To resolve this issue, configure the sandbox for the MCP server.
• The server needs a credential environment variable that the sandbox removes, such as GITHUB_TOKEN. To resolve this issue, if you trust the server, set "sandboxEnabled": false in its sandbox object.

Project MCP sandbox settings are ignored

You might get a warning that includes sandbox settings from this project's committed config can only narrow, not widen.

This warning occurs when the workspace .gitlab/duo/mcp.json file sets sandbox keys other than denyRead.

To resolve this issue, move the keys to your user MCP configuration file.

Requests to the GitLab instance are blocked

Processes in the sandbox can connect to your GitLab instance only on the host and port in your instance URL. Requests to a different port are blocked. For example, if your instance URL is https://gitlab.example.com, the allowed port is 443, so a request to http://gitlab.example.com on port 80 is blocked.

To resolve this issue, use the same port as your instance URL, or add the host and port to network.allowedDomains in your sandbox configuration file. For example, gitlab.example.com:8080.