Skip to content

docs: sandbox template contents and config version hint #3566

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dgageot merged 4 commits into from
Jul 10, 2026
+17 −3
Merged

docs: sandbox template contents and config version hint #3566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2b1a018
docs: document docker-mcp available in sandbox template (PR #3545)
aheritier Jul 10, 2026
b098136
docs: update config version to 12 and document version-hint error mes…
aheritier Jul 10, 2026
5343bb9
docs: fix prose style: Docker Agent not docker-agent
aheritier Jul 10, 2026
78b7d8b
docs: fix MD040 fenced code block missing language specifier
aheritier Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions docs/configuration/overview/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ A docker-agent config has these main sections:

```bash
# 1. Version — configuration schema version (optional but recommended)
version: 10
version: 12

# 2. Metadata — optional agent metadata for distribution
metadata:
Expand Down Expand Up @@ -294,10 +294,10 @@ For YAML editor autocompletion and validation, use the [Docker Agent JSON Schema

## Config Versioning

docker-agent configs are versioned. The current version is `10`. Add the version at the top of your config:
docker-agent configs are versioned. The current version is `12`. Add the version at the top of your config:

```yaml
version: 10
version: 12

agents:
root:
Expand All @@ -307,6 +307,14 @@ agents:

When you load an older config, docker-agent automatically migrates it to the latest schema. It's recommended to include the version to ensure consistent behavior.

If you use a config key that requires a newer schema version, Docker Agent will fail with a strict-parse error and include a hint like:

```text
hint: this key is supported by config version 12; update the top-level 'version' field (currently 11)
```

Bump the `version` field as directed to enable the new key.

## Metadata Section

Optional metadata for agent distribution via OCI registries:
Expand Down
6 changes: 6 additions & 0 deletions docs/configuration/sandbox/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,12 @@ docker agent run --sandbox agent.yaml
6. All tools (shell, filesystem, background jobs, etc.) run inside the VM.
7. When the session ends, docker-agent exits but does not stop or remove the sandbox VM; both the VM and the kit are kept around so subsequent runs from the same workspace can reuse them. A fresh sandbox is created only when the mount set has changed.

### What the default template includes

The default template (`docker/sandbox-templates:docker-agent`) ships with:

- **`docker-mcp`** CLI plugin — installed at `~/.docker/cli-plugins/docker-mcp`, available out of the box so agents can invoke `docker mcp` commands inside the sandbox without any additional setup.

## Auto-Kit

The sandbox VM has its own filesystem and `$HOME` — none of the host's `~/.agents/skills/`, `~/.claude/skills/`, project-level `.agents/skills/`, or prompt files like `AGENTS.md` and `CLAUDE.md` are visible inside it. To bridge that gap, docker-agent automatically builds a **kit**: a self-contained directory staged on the host before the sandbox starts and bind-mounted read-only into the VM at the same path.
Expand Down
Loading