|
1 | 1 | --- |
2 | 2 | title: Isolation layers |
3 | 3 | weight: 10 |
4 | | -description: How Docker Sandboxes isolate AI agents using hypervisor, network, Docker Engine, and credential boundaries. |
5 | | -keywords: docker sandboxes, isolation, hypervisor, network, credentials |
| 4 | +description: How Docker Sandboxes isolate AI agents using hypervisor, network, Docker Engine, workspace, and credential boundaries. |
| 5 | +keywords: docker sandboxes, isolation, hypervisor, network, credentials, workspace, git |
| 6 | +aliases: |
| 7 | + - /ai/sandboxes/security/workspace/ |
6 | 8 | --- |
7 | 9 |
|
8 | 10 | AI coding agents need to execute code, install packages, and run tools on |
9 | | -your behalf. Docker Sandboxes run each agent in its own microVM with four |
10 | | -isolation layers: hypervisor, network, Docker Engine, and credential proxy. |
| 11 | +your behalf. Docker Sandboxes run each agent in its own microVM. Five |
| 12 | +isolation layers protect your host: hypervisor, network, Docker Engine, |
| 13 | +workspace, and credential proxy. |
11 | 14 |
|
12 | 15 | ## Hypervisor isolation |
13 | 16 |
|
@@ -59,18 +62,136 @@ your host. When the agent runs `docker build` or `docker compose up`, those |
59 | 62 | commands execute against that engine. The agent has no path to your host Docker |
60 | 63 | daemon. |
61 | 64 |
|
62 | | -```plaintext |
63 | | -Host system |
64 | | - ├── Host Docker daemon |
65 | | - │ └── Your containers and images |
66 | | - │ |
67 | | - └── Sandbox Docker engine (isolated from host) |
68 | | - ├── [VM] Agent container — sandbox 1 |
69 | | - │ └── [VM] Containers created by agent |
70 | | - └── [VM] Agent container — sandbox 2 |
71 | | - └── [VM] Containers created by agent |
| 65 | +Each sandbox VM runs its own Docker Engine. The agent runs inside the VM, |
| 66 | +alongside that engine, and drives it to create containers, all within the |
| 67 | +VM: |
| 68 | + |
| 69 | +```mermaid |
| 70 | +flowchart TB |
| 71 | + subgraph host["Host system"] |
| 72 | + subgraph hostd["Host Docker daemon"] |
| 73 | + hc["Your containers and images"] |
| 74 | + end |
| 75 | + subgraph vm["Sandbox (microVM)"] |
| 76 | + a["Agent"] |
| 77 | + subgraph e["Sandbox Docker engine"] |
| 78 | + c["Containers created by agent"] |
| 79 | + end |
| 80 | + a -->|"docker build / compose up"| e |
| 81 | + end |
| 82 | + end |
| 83 | + style host fill:#3b82f622,stroke:#3b82f6 |
72 | 84 | ``` |
73 | 85 |
|
| 86 | +## Workspace isolation |
| 87 | + |
| 88 | +When you create a sandbox, you choose one of two ways to share your |
| 89 | +workspace with it: |
| 90 | + |
| 91 | +- **Direct mount** (the default): the agent has read-write access to |
| 92 | + your working tree. There is no boundary between the agent's edits and |
| 93 | + your host filesystem. |
| 94 | +- **Clone mode** (`--clone`): your repository is mounted read-only into |
| 95 | + the VM and the agent works on a private clone inside the VM. The |
| 96 | + agent's edits never reach your host until you fetch them. |
| 97 | + |
| 98 | +See [Git workflow](../usage.md#git-workflow) for the workflow side of |
| 99 | +each. |
| 100 | + |
| 101 | +### Direct mount (default) |
| 102 | + |
| 103 | +By default, your workspace is shared into the VM as a read-write mount. |
| 104 | +The agent and the host see the same files, and changes the agent makes |
| 105 | +appear on your host as soon as they're written. |
| 106 | + |
| 107 | +There is no isolation between the agent and your workspace in this mode. |
| 108 | +The agent can create, modify, or delete any file in the workspace, |
| 109 | +including: |
| 110 | + |
| 111 | +- Source code and configuration files |
| 112 | +- Build files (`Makefile`, `package.json`, `Cargo.toml`) |
| 113 | +- Git hooks (`.git/hooks/`) |
| 114 | +- CI configuration (`.github/workflows/`, `.gitlab-ci.yml`) |
| 115 | +- IDE configuration (`.vscode/tasks.json`, `.idea/` run configurations) |
| 116 | +- Hidden files, shell scripts, and executables |
| 117 | + |
| 118 | +Some of these files execute code when you trigger normal development |
| 119 | +actions — committing, pushing, building, or opening the project in an IDE. |
| 120 | +Review them after any agent session before performing those actions: |
| 121 | + |
| 122 | +- Git hooks (`.git/hooks/`) run on commit, push, and other Git actions. |
| 123 | + These are inside `.git/` and don't appear in `git diff` output — |
| 124 | + check them separately with `ls -la .git/hooks/`. |
| 125 | +- CI configuration (`.github/workflows/`, `.gitlab-ci.yml`) runs on |
| 126 | + push. |
| 127 | +- Build files (`Makefile`, `package.json` scripts, `Cargo.toml`) run |
| 128 | + during build or install steps. |
| 129 | +- IDE configuration (`.vscode/tasks.json`, `.idea/`) can run tasks |
| 130 | + when you open the project. |
| 131 | + |
| 132 | +> [!WARNING] |
| 133 | +> Treat sandbox-modified workspace files the same way you would treat a pull |
| 134 | +> request from an untrusted contributor: review before you trust them on |
| 135 | +> your host. |
| 136 | +
|
| 137 | +### Clone mode |
| 138 | + |
| 139 | +When you start a sandbox with [`--clone`](../usage.md#clone-mode), the agent |
| 140 | +never works directly against your host repository. Even with full root |
| 141 | +inside the VM, it cannot modify your `.git` directory, your working tree, |
| 142 | +or any tracked file on your host. |
| 143 | + |
| 144 | +```mermaid |
| 145 | +flowchart LR |
| 146 | + subgraph host["Host repository (untouched)"] |
| 147 | + direction TB |
| 148 | + repo[".git/ + working tree"] |
| 149 | + remote["remote sandbox-<name>"] |
| 150 | + end |
| 151 | + subgraph vm["Sandbox VM"] |
| 152 | + direction TB |
| 153 | + mount["/run/sandbox/source<br/>(read-only bind mount)"] |
| 154 | + clone["private clone (RW)<br/>agent edits here"] |
| 155 | + daemon["git-daemon"] |
| 156 | + end |
| 157 | + repo -->|"read-only bind mount"| mount |
| 158 | + mount -->|"git clone"| clone |
| 159 | + clone --> daemon |
| 160 | + daemon -->|"git fetch"| remote |
| 161 | +``` |
| 162 | + |
| 163 | +How the boundary is enforced: |
| 164 | + |
| 165 | +- Your repository's Git root is mounted at `/run/sandbox/source` as |
| 166 | + read-only. Nothing the agent does inside the VM can write back through |
| 167 | + that mount. |
| 168 | +- The agent works on a private clone that lives inside the sandbox. The |
| 169 | + clone has its own index, its own refs, and its own working tree. Writes |
| 170 | + to the clone never reach your host. |
| 171 | +- The sandbox publishes the clone over a Git daemon bound to localhost on |
| 172 | + the host. The CLI wires it up as a `sandbox-<sandbox-name>` Git remote on |
| 173 | + your host repository. Fetching from that remote uses the same trust |
| 174 | + model as fetching from any third-party remote — nothing is integrated |
| 175 | + until you explicitly merge or check out the fetched refs. |
| 176 | + |
| 177 | +The practical guarantees: |
| 178 | + |
| 179 | +- The agent cannot modify any tracked file or any byte under `.git/` on |
| 180 | + your host. A compromised or buggy agent cannot drop a |
| 181 | + `.git/hooks/pre-commit`, alter `.github/workflows/`, or sneak changes |
| 182 | + into your working tree. |
| 183 | +- Concurrent `git` commands on the host and inside the sandbox cannot |
| 184 | + race on a shared `.git/index` or shared refs — there is no shared |
| 185 | + writable state. |
| 186 | +- Credentials, signing keys, and any settings in your repository's |
| 187 | + `.git/config` stay on the host. The agent's clone has its own |
| 188 | + independent configuration. |
| 189 | + |
| 190 | +Use clone mode whenever you want a strong boundary between the agent's |
| 191 | +Git activity and your host repository — for example when running an |
| 192 | +unfamiliar agent, running multiple agents on the same repository at once, |
| 193 | +or keeping your working tree clean while the agent works. |
| 194 | + |
74 | 195 | ## Credential isolation |
75 | 196 |
|
76 | 197 | Most agents need API keys for their model provider. Rather than passing keys |
|
0 commit comments