Sandbox agent terminal commands

Agent terminal commands can run processes with the same operating system permissions as your user account. Agent sandboxing adds an operating system-level boundary that restricts the files and network resources these commands can access.

This article describes where agent terminal sandboxing is available, how to turn it on, and how to configure its file system and network boundaries.

Understand the sandbox boundary

Sandboxing and approvals provide separate layers of protection:

Sandboxing applies to terminal commands and their child processes. It does not apply to built-in file tools or other agent tools, and it does not replace the isolation provided by cloud sessions or Dev Containers. MCP server sandboxing is a separate feature with its own configuration and platform support.

For the security model and threats that sandboxing helps mitigate, see Trust and safety.

Check platform availability

Agent terminal sandboxing has different lifecycle states and prerequisites by platform.

On Debian and Ubuntu, install the Linux dependencies:

sudo apt-get install bubblewrap socat

On Fedora, install the Linux dependencies:

sudo dnf install bubblewrap socat

WSL version 1 is not supported because it does not provide the Linux kernel features that bubblewrap requires.

On Windows, install the update that applies to your Windows version:

• Windows 11 24H2 or 25H2: KB5124008.
• Windows 11 26H1: KB5124012.

Turn on agent sandboxing

Set the enablement setting for your platform to on, or select Sandboxing for terminal in the permissions picker.

Sandboxing is independent of the selected permission level. For example, an enabled sandbox continues to restrict terminal commands even when you select Allow all.

The shield indicator in the permissions picker shows the effective sandbox state for the current session.

If the required operating system dependencies are unavailable, VS Code does not silently run the command without the sandbox. Follow the notification to install the missing dependency, or turn off sandboxing before you run the command.

Control sandboxing for an Agent Host session

For a Copilot Agent Host session, the Sandboxing for terminal toggle applies only to the current session:

• A new session without an explicit selection uses the effective User or Workspace value of the enablement setting for its platform.
• Turning sandboxing on or off does not update User or Workspace settings or affect another session.
• An explicit session selection persists when you restore the session, reload the window, or restart VS Code.
• A session without an explicit selection follows changes to the applicable User or Workspace setting. A session with a saved selection keeps that selection.
• Peer chats and subagents use the owning session's sandbox state.

The effective state uses the following precedence:

1. A managed setting that requires sandboxing and does not allow a bypass.
2. The saved selection for the current session.
3. The Workspace setting.
4. The User setting.
5. The product default, which is off.

If a managed setting requires sandboxing without a bypass, the toggle is disabled. If the managed setting permits a bypass, the session starts with sandboxing on and you can turn it off for that session. Learn more about managed agent sandboxing.

Configure file system access

With the default file system configuration, sandboxed terminal commands:

• Can read workspace folders, the sandbox runtime temporary folder, and paths that VS Code adds for common developer tools.
• Can write to the current working directory and its subdirectories.
• Cannot read sensitive locations in your home directory by default.
• Apply the same restrictions to child processes, such as build scripts and package managers.

Use the file system setting for your platform to add or restrict paths:

The following example grants read access to an application configuration folder and prevents access to an SSH folder on Linux:

{
    "chat.agent.sandbox.fileSystem.linux": {
        "allowRead": ["/home/me/.config/myapp"],
        "denyRead": ["/home/me/.ssh"]
    }
}

Workspace folders, the sandbox runtime temporary folder, and per-command read paths are added automatically. You typically only need allowRead for configuration or data outside the workspace.

Configure network access

File system and network isolation are separate controls. By default, chat.agent.sandbox.allowNetwork Open in VS Code Open in VS Code Insiders is true, which permits unrestricted network access while preserving the file system boundary.

Set chat.agent.sandbox.allowNetwork Open in VS Code Open in VS Code Insiders to false to apply network isolation. An empty chat.agent.allowedNetworkDomains Open in VS Code Open in VS Code Insiders list then blocks all outbound network access. Add only the domains that terminal commands need, and use chat.agent.deniedNetworkDomains Open in VS Code Open in VS Code Insiders to block exceptions. Denied domains take precedence over allowed domains.

{
    "chat.agent.sandbox.allowNetwork": false,
    "chat.agent.allowedNetworkDomains": [
        "api.github.com"
    ],
    "chat.agent.deniedNetworkDomains": [
        "example.com"
    ]
}

The same domain lists apply to the fetch tool and integrated browser when you turn on chat.agent.networkFilter Open in VS Code Open in VS Code Insiders .

When a sandboxed command is blocked by network isolation, chat.agent.sandbox.retryWithAllowNetworkRequests Open in VS Code Open in VS Code Insiders controls whether the agent can ask you to retry the command inside the sandbox with unrestricted network access. The default is true. File system restrictions remain active for the approved retry.

Control approval and fallback behavior

By default, terminal commands that run inside the sandbox are approved automatically. Set chat.agent.sandbox.allowAutoApprove Open in VS Code Open in VS Code Insiders to false to use the normal terminal approval flow for sandboxed commands.

If a command cannot run inside the sandbox, the agent can ask for confirmation to run it outside the sandbox. Set chat.agent.sandbox.allowUnsandboxedCommands Open in VS Code Open in VS Code Insiders to false to remove this fallback. The default is true.

The agent tries the command inside the sandbox first. Rejecting the confirmation prevents the command from running outside the sandbox.

Related resources

• Manage approvals and permissions
• Understand trust and safety for AI agents
• Manage AI settings in enterprise environments