You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|[Transfer Task]({{ '/tools/transfer-task/' | relative_url }}) | Delegate tasks to sub-agents (auto-enabled with `sub_agents`) |
43
47
|[Background Agents]({{ '/tools/background-agents/' | relative_url }}) | Dispatch work to sub-agents concurrently |
44
-
|[Handoff]({{ '/tools/handoff/' | relative_url }}) |Delegate tasks to remote agents via A2A|
48
+
|[Handoff]({{ '/tools/handoff/' | relative_url }}) |Hand the conversation off to another local agent in the same config (auto-enabled with `handoffs:`)|
45
49
|[A2A]({{ '/tools/a2a/' | relative_url }}) | Connect to remote agents via the Agent-to-Agent protocol |
# For user-wide global permissions, see ~/.config/cagent/config.yaml
58
65
permissions:
59
66
allow: ["read_*"]
@@ -181,10 +188,10 @@ For editor autocompletion and validation, use the [Docker Agent JSON Schema](htt
181
188
182
189
## Config Versioning
183
190
184
-
docker-agent configs are versioned. The current version is `5`. Add the version at the top of your config:
191
+
docker-agent configs are versioned. The current version is `8`. Add the version at the top of your config:
185
192
186
193
```yaml
187
-
version: 5
194
+
version: 8
188
195
189
196
agents:
190
197
root:
@@ -218,6 +225,32 @@ metadata:
218
225
219
226
See [Agent Distribution]({{ '/concepts/distribution/' | relative_url }}) for publishing agents to registries.
220
227
228
+
## Reusable MCP Servers (`mcps:`)
229
+
230
+
The top-level `mcps:` section defines named MCP server configurations that agents can reference with `toolsets: [{type: mcp, ref: <name>}]`. This avoids repeating the same command / URL / headers across agents and keeps credentials in one place.
An `mcps` entry accepts every field a regular `type: mcp` toolset accepts (command/args/env, `remote` with `url`/`transport_type`/`headers`/`oauth`, `tools` filter, `instruction`, `defer`, …) — the `type: mcp` is implicit. See the [Tool Config]({{ '/configuration/tools/' | relative_url }}) page for all options and the [Remote MCP Servers]({{ '/features/remote-mcp/' | relative_url }}) guide for remote setups.
253
+
221
254
## Custom Providers Section
222
255
223
256
Define reusable provider configurations with shared defaults. Providers can wrap any provider type — not just OpenAI-compatible endpoints:
Copy file name to clipboardExpand all lines: docs/configuration/permissions/index.md
+7Lines changed: 7 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,13 +46,20 @@ permissions:
46
46
- "read_*"# Glob patterns
47
47
- "shell:cmd=ls*"# With argument matching
48
48
49
+
# Always ask before running these tools, even if an allow pattern would match
50
+
ask:
51
+
- "shell:cmd=git push*"
52
+
- "write_file:path=/home/user/important/*"
53
+
49
54
# Block these tools entirely
50
55
deny:
51
56
- "shell:cmd=sudo*"
52
57
- "shell:cmd=rm*-rf*"
53
58
- "dangerous_tool"
54
59
```
55
60
61
+
The three lists are evaluated in order `deny` → `allow` → `ask`, so an `ask:` entry lets you add a confirmation layer on top of an otherwise-allowed tool.
62
+
56
63
## Global Permissions
57
64
58
65
Global permissions let you enforce rules across **all** agents, regardless of which agent config you run. Define them in your user config file:
Copy file name to clipboardExpand all lines: docs/configuration/sandbox/index.md
+32-11Lines changed: 32 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,23 @@
1
1
---
2
2
title: "Sandbox Mode"
3
-
description: "Run agents in an isolated Docker container for enhanced security."
3
+
description: "Run agents in an isolated Docker sandbox VM for enhanced security."
4
4
permalink: /configuration/sandbox/
5
5
---
6
6
7
7
# Sandbox Mode
8
8
9
-
_Run agents in an isolated Docker container for enhanced security._
9
+
_Run agents in an isolated Docker sandbox VM for enhanced security._
10
10
11
11
## Overview
12
12
13
-
Sandbox mode runs the entire agent inside a Docker container instead of directly on the host system. This provides an additional layer of isolation, limiting the potential impact of unintended or malicious commands.
13
+
Sandbox mode runs the entire agent inside a disposable sandbox VM instead of directly on the host system. All shell, filesystem, and process activity happens inside that VM, so a misbehaving agent cannot touch files outside the mounted working directory or reach long-lived host state.
14
+
15
+
The backend is provided by the [`docker sandbox`](https://docs.docker.com/desktop/features/sandbox/) CLI plugin (ships with Docker Desktop) or the standalone [`sbx`](https://github.com/docker/sbx) CLI if it is on `PATH`.
14
16
15
17
<divclass="callout callout-info"markdown="1">
16
18
<divclass="callout-title">ℹ️ Requirements
17
19
</div>
18
-
<p>Sandbox mode requires Docker to be installed and running on the host system.</p>
20
+
<p>Sandbox mode requires Docker Desktop with sandbox support (or a working <code>sbx</code> CLI). docker-agent shells out to these tools, it does not start raw <code>docker run</code> containers.</p>
19
21
20
22
</div>
21
23
@@ -27,7 +29,23 @@ Enable sandbox mode with the `--sandbox` flag on the `docker agent run` command:
27
29
docker agent run --sandbox agent.yaml
28
30
```
29
31
30
-
This runs the agent inside a Docker container with the current working directory mounted.
32
+
docker-agent launches a sandbox VM, copies itself into it, mounts the current working directory, and re-runs the agent from inside.
|`--template`|`docker/sandbox-templates:docker-agent`| OCI image used as the sandbox template. Passed to `docker sandbox create -t` / `sbx create -t`. |
40
+
|`--sbx`|`true`| Prefer the `sbx` CLI backend when it is available. Set `--sbx=false` to always use `docker sandbox`. |
41
+
42
+
```bash
43
+
# Use a custom template image
44
+
docker agent run --sandbox --template myorg/custom-agent-template:latest agent.yaml
45
+
46
+
# Force the docker sandbox backend even if sbx is on PATH
47
+
docker agent run --sandbox --sbx=false agent.yaml
48
+
```
31
49
32
50
## Example
33
51
@@ -48,15 +66,18 @@ docker agent run --sandbox agent.yaml
48
66
49
67
## How It Works
50
68
51
-
1. When `--sandbox` is specified, docker-agent launches a Docker container
52
-
2. The current working directory is mounted into the container
53
-
3. All agent tools (shell, filesystem, etc.) operate inside the container
54
-
4. When the session ends, the container is automatically stopped and removed
69
+
1.`--sandbox` tells docker-agent to prefer the `sbx` CLI (if available and `--sbx` is true), otherwise it falls back to `docker sandbox`.
70
+
2. A new sandbox VM is created from the image passed via `--template`.
71
+
3. The current working directory is mounted into the VM; the agent binary is copied in.
72
+
4. All tools (shell, filesystem, background jobs, etc.) run inside the VM.
73
+
5. When the session ends, the sandbox VM is stopped and removed.
55
74
56
75
<divclass="callout callout-warning"markdown="1">
57
76
<divclass="callout-title">⚠️ Limitations
58
77
</div>
59
78
60
-
- Container starts fresh each session (no persistence between sessions)
79
+
- Sandbox VMs start fresh each session (no persistence between sessions).
80
+
- Only the working directory is mounted; files outside it are not visible to the agent.
81
+
- Network egress is constrained by the sandbox backend's policy.
|`handoff`|Local conversation handoff to another agent in the same config (auto-enabled by `handoffs:`)|[Handoff]({{ '/tools/handoff/' | relative_url }}) |
0 commit comments