Sandbox Copilot Agent Host sessions

Copilot Agent Host sessions can run terminal commands and start language or tool servers on your local machine or a connected remote host. Agent sandboxing confines these processes to the file system and network access that you configure on the execution host.

Use this article to understand the security boundary, turn on sandboxing, grant the minimum required access, and inspect the effective policy for a session.

The settings and behavior below apply to the Agent Host's default Copilot SDK tool implementation, not the Local chat harness or the custom terminal tool override.

Understand the sandbox boundary

Sandboxing and approvals provide separate layers of protection:

Sandboxing applies to terminal commands and their child processes. When configured, it also applies to MCP and language servers that the Agent Host launches or manages. Built-in tools that don't start operating system processes use their own permission checks.

Sandboxing is not a virtual machine or user-account boundary, and it does not replace endpoint security. A sandboxed process still runs on the execution host under your account. Network access, extra paths, credentials, developer tool access, and permission to run outside the sandbox all weaken isolation. Grant only the access that a task requires.

Depending on the operation and platform, restrictions use operating system protections or checks within the agent host process. Sandboxing does not replace the isolation provided by cloud sessions or Dev Containers. MCP server sandboxing outside the Agent Host 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 Host sandboxing has the following platform prerequisites. Check the operating system where the agent runs. For a remote Agent Host, install dependencies and operating system updates on the remote host, not the client machine.

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 sandboxing on the execution host

The chat.agent.sandbox.enabled Open in VS Code Open in VS Code Insiders setting controls Agent Host sandboxing on all platforms. It accepts off or on and defaults to off.

For a local Agent Host, the execution host is your local machine. For a connected remote Agent Host, its platform determines the sandbox implementation and prerequisites. Settings are resolved on that host, and all configured paths refer to its file system, not the client machine.

1. Meet the platform prerequisites on the execution host.
2. Set chat.agent.sandbox.enabled Open in VS Code Open in VS Code Insiders to on in the settings for that host.
3. Start a new Agent Host session.
4. Inspect the effective sandbox policy to verify the session's restrictions.

To enable sandboxing in your settings JSON:

{
  "chat.agent.sandbox.enabled": "on"
}

If an operating system dependency is unavailable, the Agent Host does not silently run the command without the sandbox. Follow the notification to install the missing dependency.

Control sandboxing for the current session

In an Agent Host session, open Permissions and select Sandboxing for terminal to change sandboxing for that session. This control does not update User or Workspace settings, change other sessions, or set the default for new sessions.

A new session inherits the effective configuration of its execution host. An explicit session selection persists when you restore the session unless an organization-managed restriction overrides it.

Sandboxing is independent of the selected permission level. For example, the sandbox continues to restrict processes when you select Allow all.

Configure sandboxing for an Agent Host session

Copilot Agent Host sessions are available in both the Agents window and an editor window. They use the Copilot SDK built-in shell by default. You do not need to change terminal implementations to use sandboxing.

For a remote Agent Host, use the session toggle to change the current session's sandbox state. Defaults for new sessions come from the connected host's sandbox configuration, not from the client machine's settings.

Agent Host sandbox settings

The following settings configure the Agent Host sandbox. Shared setting names do not imply that other chat harnesses use the same behavior.

Inspect the effective sandbox policy

The /sandbox policy slash command is available only in Agent Host sessions. Run it to verify whether sandboxing is active or investigate why a process is blocked.

• Enter /sandbox policy in the chat input and submit it. The report opens automatically in the editor as a Markdown preview. Select Open Sandbox Policy in the response to reopen it.

The generated sandbox-policy.md report describes the execution host, whether sandboxing is enabled, the operating system's sandbox implementation, and the effective file system and network policy. You can also run the command when sandboxing is off. In that case, the report indicates that sandbox restrictions are not active.

The command does not start a model turn or change your sandbox settings.

Run /sandbox policy again after a change to refresh the report. The command updates the same report for the session, so earlier links also open the latest generated report. To check the defaults for new sessions, start a new session before running the command.

Configure file system access

The sandbox automatically grants read and write access to the current working directory. Use chat.agent.sandbox.fileSystem.userConfiguredPaths Open in VS Code Open in VS Code Insiders to customize path permissions on all supported platforms:

For a path listed in more than one property, deniedPaths takes precedence over readonlyPaths, which takes precedence over readwritePaths. Paths refer to the machine where the agent runs, including for remote Agent Host sessions.

The following example grants read and write access to a build output folder, read access to shared source, and prevents access to sensitive data:

{
    "chat.agent.sandbox.fileSystem.userConfiguredPaths": {
        "readwritePaths": ["/path/to/build-output"],
        "readonlyPaths": ["/path/to/shared-source"],
        "deniedPaths": ["/path/to/sensitive-data"]
    }
}

The arrays default to empty.

The chat.agent.sandbox.fileSystem.allowDevToolAccess Open in VS Code Open in VS Code Insiders setting defaults to true. It grants read access to tool directories on PATH, toolchain directories, developer-tool configuration and caches, including registry tokens, and read and write access to shared build caches. Set it to false to remove these automatic developer-tool grants, and add narrower paths if necessary.

Use /sandbox policy to inspect the effective permissions, including runtime defaults and organization-managed restrictions.

Configure managed servers and credentials

When sandboxing is on, these settings determine whether processes managed by the Agent Host run with specific sandbox access:

• chat.agent.sandbox.mcpServers Open in VS Code Open in VS Code Insiders defaults to true and applies sandboxing to MCP servers launched or managed by the Agent Host.
• chat.agent.sandbox.lspServers Open in VS Code Open in VS Code Insiders defaults to true and applies sandboxing to language servers launched or managed by the Agent Host.
• chat.agent.sandbox.credentials.authenticategit Open in VS Code Open in VS Code Insiders defaults to true and provides Git authentication to sandboxed processes.
• chat.agent.sandbox.credentials.authenticategh Open in VS Code Open in VS Code Insiders defaults to true and provides GitHub CLI authentication to sandboxed processes.

Turning off MCP or language server sandboxing leaves those Agent Host-managed server processes outside the sandbox. Servers that you start independently are also outside the Agent Host's management. Turn off credential access that a task does not need. A process with credentials can act with the permissions of the associated account.

Configure network access

File system and network isolation are separate controls:

• chat.agent.sandbox.network.allowNetwork Open in VS Code Open in VS Code Insiders defaults to true and permits outbound network access. Set it to false to block outbound access, including for the integrated browser.
• chat.agent.sandbox.network.allowLocalNetwork Open in VS Code Open in VS Code Insiders defaults to false and controls access to hosts on the local network.
• chat.agent.sandbox.network.allowedDomains Open in VS Code Open in VS Code Insiders and chat.agent.sandbox.network.deniedDomains Open in VS Code Open in VS Code Insiders restrict destinations when outbound access is enabled. The Agent Host forwards these hostname restrictions to the sandbox runtime.

Allow local network access only when the task must connect to a service on the execution host or private network. Use /sandbox policy to inspect the effective network policy for the current Agent Host session.

To enable outbound access subject to domain filtering:

{
    "chat.agent.sandbox.network.allowNetwork": true,
    "chat.agent.sandbox.network.allowedDomains": [
        "api.github.com"
    ],
    "chat.agent.sandbox.network.deniedDomains": [
        "example.com"
    ]
}

Your organization can enforce network restrictions that you cannot relax with a local setting. See Copilot managed sandbox settings.

Control approval and fallback behavior

If a command is blocked, check the applicable file system or network restriction first. Grant only the access needed for the task rather than turning off the sandbox.

If a command cannot run inside the sandbox, the agent can ask for confirmation to run it outside the sandbox. The chat.agent.sandbox.allowUnsandboxedCommands Open in VS Code Open in VS Code Insiders setting controls this fallback:

• true (default): the agent can request permission to run outside the sandbox. For Agent Host sessions, a supported prompt can offer approval for one operation or for the current session. Approve only if you trust the command to run without the sandbox's file system and network restrictions.
• false: Allow Outside Sandbox is not offered, and requests to run outside the sandbox fail instead of prompting for approval. Commands that comply with the sandbox policy can still run.

The agent requests approval when a sandboxed command fails or sandbox restrictions would block it. Rejecting the confirmation prevents the command from running outside the sandbox.

Legacy Local and custom terminal behavior

Legacy Local sessions and custom terminal implementations don't use all Agent Host settings in the same way. The following compatibility settings don't configure the standard Agent Host sandbox:

• The removed chat.agent.sandbox.enabledWindows setting is replaced by the unified chat.agent.sandbox.enabled Open in VS Code Open in VS Code Insiders setting on Windows.
• The former chat.agent.sandbox.allowNetwork Open in VS Code Open in VS Code Insiders setting migrates to chat.agent.sandbox.network.allowNetwork Open in VS Code Open in VS Code Insiders .
• chat.agent.sandbox.retryWithAllowNetworkRequests Open in VS Code Open in VS Code Insiders is a deprecated Local terminal setting. It can offer a network-enabled retry inside the legacy sandbox and does not apply to Agent Host.
• chat.agent.sandbox.allowAutoApprove Open in VS Code Open in VS Code Insiders controls legacy Local terminal approval behavior. It is not an Agent Host sandbox setting.
• chat.agent.sandbox.fileSystem.mac Open in VS Code Open in VS Code Insiders , chat.agent.sandbox.fileSystem.linux Open in VS Code Open in VS Code Insiders , and chat.agent.sandbox.fileSystem.windows Open in VS Code Open in VS Code Insiders are deprecated platform-specific settings. Agent Host ignores them.

Domain allow and deny controls remain public for compatible terminal implementations. Their capabilities differ by implementation and platform, so don't use legacy behavior to infer the effective Agent Host policy.

When your organization manages sandboxing

Managed sandbox enforcement is in Preview. Your organization can require sandboxing, prevent bypass, or restrict network access. Enforced controls are locked, but you can select a more restrictive value where a control remains editable.

If a setting is locked or you need access that policy denies, contact your administrator. For policy details, see enterprise agent sandboxing.

Related resources

• Manage approvals and permissions
• Understand trust and safety for AI agents
• Review AI settings