From 381fe5483e30eedce7e0cc158669597d4130e78a Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:38:29 +0000 Subject: [PATCH] docs: document shared agent skills The Sandboxes docs did not explain how to import host agent skills or account for the writable store in the security model. Document the supported paths and behavior, clarify the narrow cross-sandbox trust boundary, and update related security, lifecycle, and FAQ guidance. Co-Authored-By: Codex --- content/manuals/ai/sandboxes/architecture.md | 8 +- content/manuals/ai/sandboxes/faq.md | 33 ++++---- .../manuals/ai/sandboxes/security/_index.md | 22 ++++- .../manuals/ai/sandboxes/security/defaults.md | 17 +++- .../ai/sandboxes/security/isolation.md | 11 +-- content/manuals/ai/sandboxes/usage.md | 11 +-- content/manuals/ai/sandboxes/workflows.md | 81 ++++++++++++++++++- 7 files changed, 141 insertions(+), 42 deletions(-) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index ef44743e1111..7d0c8332f950 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -31,9 +31,11 @@ When you create a sandbox, everything inside it persists until you remove it: Docker images and containers built or pulled by the agent, installed packages, agent state and history, and workspace changes. -Sandboxes are isolated from each other. Each one maintains its own Docker -daemon state, image cache, and package installations. Multiple sandboxes don't -share images or layers. +Each sandbox maintains its own Docker daemon state, image cache, and package +installations. Multiple sandboxes don't share images or layers. The +[shared agent skills store](workflows.md#share-agent-skills) is an exception: +supported agents mount the same host-side store read-write unless you opt out +when creating the sandbox. Each sandbox consumes disk space for its VM image, Docker images, container layers, and volumes, and this grows as you build images and install packages. diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 0b0bf00728aa..62779fc0cdd4 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -134,9 +134,9 @@ $ echo $BRAVE_API_KEY The sandbox itself is the safety boundary. Because agents run inside an isolated microVM with [network policies](governance/), [credential isolation](security/credentials.md), and no access to your host -system outside the workspace, the usual reasons for approval prompts (preventing -destructive commands, network access, file modifications) are handled by the -sandbox isolation layers instead. +system outside explicitly shared paths, the usual reasons for approval prompts +(preventing destructive commands, network access, file modifications) are +handled by the sandbox isolation layers instead. If you prefer to re-enable approval prompts, change the permission mode inside the session. Most agents let you switch permission modes after @@ -173,24 +173,19 @@ in-progress task: ## Why doesn't the sandbox use my user-level agent configuration? -Sandboxes don't pick up user-level agent configuration from your host. This -includes directories like `~/.claude` for Claude Code or `~/.codex` for Codex, -where hooks, skills, and other settings are stored. Only project-level -configuration in the working directory is available inside the sandbox. +Sandboxes don't import your complete user-level agent configuration. Hooks, +settings, and other files under directories such as `~/.claude` remain on the +host. Project-level configuration in the working directory remains available +inside the sandbox. -To make configuration available in a sandbox, copy or move what you need into -your project directory before starting a session: +Shared agent skills are the exception. Run `sbx skills import` to copy skills +from supported host directories into a persistent store shared with +sandboxes. See [Share agent skills](workflows.md#share-agent-skills) for the +supported directories, mount behavior, and per-sandbox opt-out. -```console -$ cp -r ~/.claude/skills .claude/skills -``` - -Don't use symlinks — a sandboxed agent can't follow symlinks to paths outside -the sandbox. - -Collocating skills and other agent configuration with the project itself is a -good practice regardless of sandboxes. It's versioned alongside the code and -evolves with the project as it changes. +Keep project-specific skills and other agent configuration in the project +itself. This versions the configuration alongside the code. Don't use symlinks +to host paths because a sandboxed agent can't follow them outside the sandbox. ## Can I paste images into an agent? diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 2991f9bcf81a..19bb2a54ee90 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -26,17 +26,23 @@ What crosses the boundary into the VM: outbound HTTP requests. The raw credential values never enter the VM. - **Network access:** HTTP and HTTPS requests to [allowed domains](defaults/) are proxied through the host. +- **Shared agent skills:** a persistent host-side store is mounted read-write + at the agent's skills directory unless you opt out when creating the + sandbox. Supported agents in other sandboxes mount the same store. What crosses the boundary back to the host: - **Workspace file changes:** visible on your host in real time with the default direct mount. - **HTTP/HTTPS requests:** sent to allowed domains through the host proxy. +- **Shared skill changes:** written to the host-side store and visible to other + sandboxes that share it. -Everything else is blocked. The agent cannot access your host filesystem -(outside the workspace), your host Docker daemon, your host network or -localhost, other sandboxes, or any domain not in the allow list. Raw TCP, UDP, -and ICMP are blocked at the network layer. +Outside the workspace and shared skills store, the agent cannot access your +host filesystem. It also cannot access your host Docker daemon, your host +network or localhost, or any domain not in the allow list. Sandboxes cannot +communicate directly over the network. Raw TCP, UDP, and ICMP are blocked at +the network layer. ![Sandbox security model showing the hypervisor boundary between the sandbox VM and the host system. The workspace directory is shared read-write. The agent process, Docker Engine, packages, and VM filesystem are inside the VM. Host filesystem, processes, Docker Engine, and network are outside the VM and not accessible. A proxy enforces allow/deny policies and injects credentials into outbound requests.](../images/sbx-security.png) @@ -91,6 +97,14 @@ supply-chain risk, `sbx` restricts kit installs to an allowlist of sources that defaults to Docker Hub only. See [Restrict kit sources](../customize/kits.md#restrict-kit-sources). +Shared agent skills create a narrow exception to cross-sandbox isolation. The +store is mounted read-write, so one sandbox can modify instructions or scripts +that an agent later uses in another sandbox. This doesn't expose the rest of +the host filesystem or create a direct network path between sandboxes, but it +does put participating sandboxes in the same trust boundary. See +[Share agent skills](../workflows.md#share-agent-skills) for details and the +per-sandbox opt-out. + ## Organization-wide control On a single developer's machine, security and policy are configured locally — diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 349ddc03d418..f42fd3018cb6 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -3,7 +3,7 @@ title: Default security posture linkTitle: Defaults weight: 15 description: What a sandbox permits and blocks before you change any settings. -keywords: docker sandboxes, security defaults, network policy, credentials, sbx +keywords: docker sandboxes, security defaults, network policy, credentials, shared skills, sbx --- A sandbox created with `sbx run` and no additional flags has the following @@ -31,6 +31,14 @@ including hidden files, configuration files, build scripts, and Git hooks. See [Workspace isolation](isolation.md#workspace-isolation) for what to review after an agent session. +## Shared skills defaults + +Sandboxes for supported agents mount a persistent shared skills store +read-write by default. Every sandbox that uses the store can change skills that +other participating sandboxes may load. Use `--no-share-skills` when creating a +sandbox to keep it outside this shared trust boundary. See +[Share agent skills](../workflows.md#share-agent-skills). + ## Credential defaults No credentials are available to the sandbox unless you provide them using @@ -52,17 +60,18 @@ The agent runs with full control inside the sandbox VM: Everything the agent installs or creates inside the VM, including packages, Docker images, and configuration changes, persists across stop and restart cycles. When you remove the sandbox with `sbx rm`, the VM and its contents -are deleted. Only workspace files remain on the host. +are deleted. Workspace files and the shared skills store remain on the host. ## What is blocked by default The following are blocked for all sandboxes and cannot be changed through policy configuration: -- Host filesystem access outside the workspace directory +- Host filesystem access outside explicitly mounted workspaces and the shared + skills store - Host Docker daemon - Host network and localhost -- Communication between sandboxes +- Direct network communication between sandboxes - Raw TCP, UDP, and ICMP connections - Traffic to private IP ranges and link-local addresses diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 5d72cea66660..b754c0c8430a 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -20,10 +20,11 @@ processes, files, or resources outside its defined boundaries. - **Process isolation:** separate kernel per sandbox; processes inside the VM are invisible to your host and to other sandboxes -- **Filesystem isolation:** only your workspace directory is shared with the - host. The rest of the VM filesystem persists across restarts but is removed - when you delete the sandbox. Symlinks pointing outside the workspace scope - are not followed. +- **Filesystem isolation:** your workspace directory and, for supported agents + that haven't opted out, the dedicated [shared skills + store](../workflows.md#share-agent-skills) are shared with the host. The rest + of the VM filesystem persists across restarts but is removed when you delete + the sandbox. Symlinks pointing outside the workspace scope are not followed. - **Full cleanup:** when you remove a sandbox with `sbx rm`, the VM and everything inside it is deleted @@ -189,7 +190,7 @@ The practical guarantees: into your working tree. - Concurrent `git` commands on the host and inside the sandbox cannot race on a shared `.git/index` or shared refs — there is no shared - writable state. + writable Git state. - Credentials, signing keys, and any settings in your repository's `.git/config` stay on the host. The agent's clone has its own independent configuration. diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 5b5008b3c721..4136be0029f8 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -187,8 +187,8 @@ shared libraries the agent shouldn't modify: $ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro ``` -Each sandbox is completely isolated, so you can also run separate projects -side-by-side. Remove unused sandboxes when you're done to reclaim disk space: +You can also run separate projects side-by-side. Remove unused sandboxes when +you're done to reclaim disk space: ```console $ sbx run claude ~/project-a @@ -254,6 +254,7 @@ dev server and host-service recipes, see While a sandbox exists, installed packages, Docker images, configuration changes, and command history all persist across stops and restarts. When you -remove a sandbox, everything inside is deleted — only your workspace files -remain on your host. To preserve a configured environment, create a -[custom template](customize/templates.md) or use a [kit](customize/kits.md). +remove a sandbox, everything inside is deleted. Your workspace files and the +[shared agent skills store](workflows.md#share-agent-skills) remain on your +host. To preserve a configured environment, create a [custom +template](customize/templates.md) or use a [kit](customize/kits.md). diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index 1de3477ae845..702de9ad7ebd 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -2,14 +2,91 @@ title: Workflow patterns linkTitle: Workflows weight: 30 -description: Workflow patterns for Docker Sandboxes, covering git strategies, local services, authenticated tools, commit signing, and CI integration. -keywords: docker sandboxes, sbx, workflows, clone mode, git, branches, commit signing, github cli, local services, ci, headless +description: Workflow patterns for Docker Sandboxes, covering shared agent skills, git strategies, local services, authenticated tools, and CI integration. +keywords: docker sandboxes, sbx, workflows, agent skills, shared skills, clone mode, git, branches, commit signing, github cli, local services, ci, headless --- Use this page when you need to choose an approach for a specific way of working with sandboxes. For command syntax and lifecycle basics, see [Usage](usage.md). +## Share agent skills + +Shared agent skills make skills from supported agents on your host available +inside your sandboxes. Importing copies the skills into a persistent store that +survives sandbox deletion and is shared by default with new sandboxes that run +a supported agent. + +> [!NOTE] +> Shared agent skills are experimental. + +Preview the skills that `sbx` finds without copying them: + +```console +$ sbx skills import --dry-run +``` + +The command scans the following directories in order and copies each skill +subdirectory into the shared store. When a sandbox is created, `sbx` mounts the +store at the path the agent reads inside the sandbox. + +| Agent | Host source | Sandbox mount target | +| ----------- | ------------------- | ----------------------------- | +| Claude Code | `~/.claude/skills` | `/home/agent/.claude/skills` | +| Codex | `~/.agents/skills` | `/home/agent/.agents/skills` | +| Copilot | `~/.copilot/skills` | `/home/agent/.copilot/skills` | +| Cursor | `~/.cursor/skills` | `/home/agent/.cursor/skills` | +| Droid | `~/.factory/skills` | `/home/agent/.factory/skills` | + +All imported skills go into the same store, regardless of their source. If +more than one source contains a skill with the same directory name, the skill +from the first source in the table wins and `sbx` warns about the others. + +Import the skills: + +```console +$ sbx skills import +``` + +The final output reports the shared store path. The default locations are: + +| Platform | Shared store path | +| -------- | --------------------------------------------------------------------------- | +| macOS | `~/Library/Application Support/com.docker.sandboxes/sandboxes/agent-skills` | +| Linux | `~/.local/state/sandboxes/sandboxes/agent-skills` | +| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\state\agent-skills` | + +On Linux, `sbx` uses `$XDG_STATE_HOME/sandboxes/sandboxes/agent-skills` when +`XDG_STATE_HOME` is set. + +When a skill already exists in the store, `sbx` prompts before replacing it. +Use `--force` to replace existing skills without prompts. Importing replaces +the complete skill directory rather than merging files. Run the import command +again when you want to copy updates from the host. Running `sbx reset` clears +the shared store. + +Sandboxes created with `sbx run` or `sbx create` for a supported agent mount +the store as a read-write directory by default. To create a sandbox without +the shared store, use `--no-share-skills`: + +```console +$ sbx run --no-share-skills claude +``` + +The option only applies when the sandbox is created. To turn off shared skills +for an existing sandbox, remove it and recreate it with the option. + +> [!WARNING] +> The shared skills store is mounted read-write. A sandbox can modify any skill +> in the store, and another sandbox can later load the modified instructions or +> run the modified scripts. The store is dedicated sandbox state, so this does +> not by itself execute the modified skill on your host. It does put every +> sandbox that shares the store in the same trust boundary. Use +> `--no-share-skills` to keep a sandbox outside that boundary. + +Some agents scan for skills when a session starts. If imported skills don't +appear in an existing session, start another agent session. + ## Git workflows Sandboxes support three approaches for working with Git repositories. The