Isolation layers

目录

{{% include "sandboxes-local-scope.md" %}}

AI coding agents need to execute code, install packages, and run tools on your behalf. Docker Sandboxes run each agent in its own microVM. Five isolation layers protect your host: hypervisor, network, Docker Engine, workspace, and credential proxy.

Hypervisor isolation

Every sandbox runs inside a lightweight microVM with its own Linux kernel. Unlike containers, which share the host kernel, a sandbox VM cannot access host processes, files, or resources outside its defined boundaries.

The agent runs as a non-root user with sudo privileges inside the VM. The hypervisor boundary is the isolation control, not in-VM privilege separation.

Processes in a local sandbox can write text to your host clipboard, but can't read existing clipboard text. Host clipboard image reads are a separate, opt-in feature. After running untrusted code, check clipboard contents before pasting them on the host.

Network isolation

Each sandbox has its own isolated network. Sandboxes cannot communicate directly with each other or share a network with your host. To reach a service running on the host through a policy-controlled connection, see Accessing host services from a sandbox.

All outbound TCP traffic passes through a proxy on your host that enforces the network access policy. The sandbox routes traffic through either a forward proxy or a transparent proxy depending on the client's configuration. Both enforce the network policy. Only the forward proxy injects credentials for AI services.

Outbound UDP is disabled by default. When you turn on experimental UDP egress, network policy controls its destinations. ICMP is blocked. DNS queries use the sandbox's internal resolver, which enforces network policy. TCP connections are allowed only when a policy rule matches the destination.

For the default set of allowed domains, see Default security posture. To forward allowed traffic through a corporate or upstream proxy, see Configure an upstream proxy.

Docker Engine isolation

Agents often need to build images, run containers, and use Docker Compose. Mounting your host Docker socket into a container would give the agent full access to your environment.

Docker Sandboxes avoid this by running a separate Docker Engine inside the sandbox environment, isolated from your host. When the agent runs docker build or docker compose up, those commands execute against that engine. The agent has no path to your host Docker daemon.

This Docker Engine boundary applies to processes running inside the sandbox VM. It doesn't apply to local stdio MCP servers registered through the MCP gateway. Those servers run on the host, outside the sandbox VM. If a local MCP server starts a Docker container, it uses Docker on the host.

Each sandbox VM runs its own Docker Engine. The agent runs inside the VM, alongside that engine, and drives it to create containers, all within the VM:

flowchart TB
  subgraph host["Host system"]
    subgraph hostd["Host Docker daemon"]
      hc["Your containers and images"]
    end
    subgraph vm["Sandbox (microVM)"]
      a["Agent"]
      subgraph e["Sandbox Docker engine"]
        c["Containers created by agent"]
      end
      a -->|"docker build / compose up"| e
    end
  end
  style host fill:#3b82f622,stroke:#3b82f6

Workspace isolation

When you create a sandbox, choose how the agent receives a workspace:

See Git workflows for direct-mount and clone-mode workflows.

Mountless

Omit the workspace path from sbx create to create a mountless sandbox, then attach by name:

$ sbx create --name scratch claude
$ sbx run --name scratch

The agent uses the sandbox template's default working directory. Docker-provided agent templates use /home/agent/workspace. If the template doesn't define a usable absolute working directory, the daemon uses that path. Files there stay within the sandbox, persist across stops and restarts, and are deleted when you remove the sandbox. A mountless sandbox doesn't expose a host project directory, but separately configured host resources such as the shared skills store can still be mounted.

Direct mount

Pass a workspace path to share it into the VM as a read-write mount. The agent and the host see the same files, and changes the agent makes appear on your host as soon as they're written. sbx run mounts the current directory when you don't pass a path:

$ sbx run claude

Direct mounts enforce access by path. If a workspace file is a hard link to a file outside the workspace, the agent can read and modify the underlying file through the workspace path. Changes affect every hard link to that file, including links outside the authorized workspace. Filesystem access policies do not block this access because they evaluate the workspace path rather than other paths to the same file. Clone mode prevents writes through the primary workspace by mounting the host repository read-only.

Direct mount gives the agent broad write access to your workspace. The agent can create, modify, or delete workspace files, including:

Some of these files execute code when you trigger normal development actions — committing, pushing, building, or opening the project in an IDE. Review them after any agent session before performing those actions:

Sandbox environment files

Sandbox environment files can declare lifecycle and credential commands that run on the host with your privileges. Before running these commands, sbx shows them in an environment plan and asks for approval. Review the plan before you approve host commands.

For file placement and read-only protection, see Sandbox environment files.

[!WARNING] Treat sandbox-modified workspace files the same way you would treat a pull request from an untrusted contributor: review before you trust them on your host.

Clone mode

When you start a sandbox with --clone, the agent never works directly against your host repository. Even with full root inside the VM, it cannot modify your .git directory, your working tree, or any tracked file on your host.

[!IMPORTANT] Clone mode protects your host repository from modification, not from inspection. Your repository is still mounted read-only into the sandbox, including untracked files and files excluded by .gitignore. Files such as .env remain readable by the agent. Store secrets outside your working directory or use credential isolation instead.

flowchart LR
  subgraph host["Host repository (untouched)"]
    direction TB
    repo[".git/ + working tree"]
    remote["remote sandbox-<name>"]
  end
  subgraph vm["Sandbox VM"]
    direction TB
    mount["/run/sandbox/source<br/>(read-only bind mount)"]
    clone["private clone (RW)<br/>agent edits here"]
    daemon["git-daemon"]
  end
  repo -->|"read-only bind mount"| mount
  mount -->|"git clone"| clone
  clone --> daemon
  daemon -->|"git fetch"| remote

How the boundary is enforced:

The practical guarantees:

Use clone mode whenever you want a strong boundary between the agent's Git activity and your host repository — for example when running an unfamiliar agent, running multiple agents on the same repository at once, or keeping your working tree clean while the agent works.

Credential isolation

Most agents need API keys for their model provider. Rather than passing keys into the sandbox, the host-side proxy intercepts outbound API requests and injects authentication headers before forwarding each request.

Credential values are never stored inside the VM. They are not available as environment variables or files inside the sandbox unless you explicitly set them. This means a compromised sandbox cannot read API keys from the local environment.

SSH agent forwarding is enabled by default. Private keys stay on the host, but any process inside the sandbox can ask the forwarded agent to authenticate or sign data. Docker Sandboxes forwards only sockets it recognizes as SSH agents. A sandbox receives no SSH agent when forwarding is disabled, the configuration is unavailable, or the selected socket can't be used.

For how to store and manage credentials, see Credentials.

版本号 #2
由 壳壳虫 创建于 2026-10-31 19:02:15 UTC
由 壳壳虫 更新于 2026-10-31 19:02:16 UTC