From b487bba297646efcd59a7718d5a971cec7d7de0c Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 15 Sep 2026 11:37:16 +0000 Subject: [PATCH 1/2] docs: update shared skills behavior for sbx v0.43.0 The skills guide and related security and architecture passages described read-write sharing as the default and recommended the retired opt-out flag. Document --skills modes, skills.defaultMode, the read-only default, and the requirement to recreate existing sandboxes to change their mounts. --- content/manuals/ai/sandboxes/architecture.md | 6 ++- .../manuals/ai/sandboxes/security/_index.md | 16 +++--- .../manuals/ai/sandboxes/security/defaults.md | 11 ++-- .../ai/sandboxes/workflows/agent-skills.md | 52 +++++++++++++------ 4 files changed, 55 insertions(+), 30 deletions(-) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 7a02fbd4e3bd..529e5eb9f1ec 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -51,8 +51,10 @@ a directly mounted workspace live on the host instead. 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/agent-skills.md) is an exception: -supported agents mount the same host-side store read-write unless you opt out -when creating the sandbox. +sandboxes created for supported agents mount the same host-side store read-only +by default starting with `sbx` version 0.43.0. Use `--skills` or +`skills.defaultMode` to choose another mode at creation. Existing sandboxes +retain their mounts until recreated. 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/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 0d4f522ba859..b2c888a147d7 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -28,9 +28,10 @@ What crosses the boundary into the VM: outbound HTTP requests. The raw credential values never enter the VM. - **Network access:** outbound TCP connections to destinations allowed by [network policy](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. +- Shared agent skills: starting with `sbx` version 0.43.0, sandboxes created + for supported agents mount a persistent host-side store read-only by default + at the agent's skills directory. Use `--skills` or `skills.defaultMode` to choose another mode at + creation. Existing sandboxes retain their mounts until recreated. - **MCP gateway traffic:** supported agents connect to a host-side MCP gateway endpoint. The gateway brokers access to registered MCP servers. @@ -40,8 +41,8 @@ What crosses the boundary back to the host: direct mount. - **Outbound TCP connections:** sent to allowed destinations through the host proxy. -- **Shared skill changes:** written to the host-side store and visible to other - sandboxes that share it. +- Shared skill changes: sandboxes with `readwrite` access can write to the + host-side store. These changes are visible to other sandboxes that share it. Outside the workspace and shared skills store, the agent cannot access your host filesystem. It also cannot access your host Docker daemon, your host @@ -113,8 +114,9 @@ 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 +store can be mounted with `readwrite` access, so one sandbox can modify +instructions or scripts that an agent later uses in another sandbox, including +one with `readonly` access. 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/agent-skills.md) for details and the diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index c19ba2e1c02c..39a35831ff52 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -39,10 +39,13 @@ workspace modes and what to review after a direct-mount 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 +Starting with `sbx` version 0.43.0, sandboxes created for supported agents mount +a persistent shared skills store read-only by default. The `skills.defaultMode` +setting can change this default, and `--skills` overrides it for a sandbox at +creation. A sandbox with `readwrite` access can change skills that other +participating sandboxes load, including those with `readonly` access. Use +`--skills=off` when creating a sandbox to omit the shared store. Existing +sandboxes retain their mounts until recreated. See [Share agent skills](../workflows/agent-skills.md). ## Credential defaults diff --git a/content/manuals/ai/sandboxes/workflows/agent-skills.md b/content/manuals/ai/sandboxes/workflows/agent-skills.md index ad9d751ca5c8..f66a1ad2d515 100644 --- a/content/manuals/ai/sandboxes/workflows/agent-skills.md +++ b/content/manuals/ai/sandboxes/workflows/agent-skills.md @@ -120,29 +120,47 @@ repository, so `sbx skills update` won't refresh it. Running `sbx reset` clears the shared store. -Sandboxes created with `sbx` version 0.37.0 or later for a supported agent are -configured to mount the store read-write by default. These sandboxes mount the -current contents of the store each time they start, so you can install skills -before or after creating them. To create a sandbox without the shared store, -use `--no-share-skills`: +Starting with `sbx` version 0.43.0, sandboxes created for a supported agent +mount the shared store read-only by default. These sandboxes mount the contents +of the store each time they start, so you can install skills before or after +creating them. + +Use `--skills` with `sbx run` or `sbx create` to choose the access mode when +creating a sandbox: + +- `readonly`: Mount the store so the agent can read skills but cannot modify them. +- `readwrite`: Mount the store so the agent can read and modify shared skills. +- `off`: Omit the shared store mount. + +For example, create a sandbox without the shared store: + +```console +$ sbx run --skills=off claude +``` + +To change the default for future sandboxes, set `skills.defaultMode` to `off`, +`readonly`, or `readwrite`: ```console -$ sbx run --no-share-skills claude +$ sbx settings set skills.defaultMode readonly ``` -Upgrading `sbx` does not enable shared skills for sandboxes created with an -earlier version. Remove and recreate those sandboxes after upgrading. The -`--no-share-skills` option also only applies when the sandbox is created. To -turn off shared skills for an existing sandbox, remove it and recreate it with -the option. +When no mode is specified, the daemon uses `skills.defaultMode`, whose built-in +value is `readonly`. An explicit `--skills` value overrides that default. + +The mode is applied only when a sandbox is created. Upgrading `sbx` or changing +`skills.defaultMode` leaves existing sandbox mounts unchanged, including +read-write mounts created with earlier versions. Remove and recreate a sandbox +to change its mode. Sandboxes created without shared skills also need to be +recreated to mount the store. > [!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. +> A sandbox with `readwrite` access can modify skills that other sandboxes load, +> including sandboxes with `readonly` access. Read-only access prevents writes +> from that sandbox but does not isolate it from changes to the store. The store +> is dedicated sandbox state, so this does not by itself execute modified skills +> on your host. Use `--skills=off` when creating a sandbox to keep it outside +> this shared trust boundary. Some agents scan for skills when a session starts. If installed skills don't appear in an existing session, start another agent session. From bba88525ec09c43dccc2947192100f427594b573 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 15 Sep 2026 11:41:28 +0000 Subject: [PATCH 2/2] docs: describe shared skills defaults without version callouts Repeated version introductions make the guide and conceptual pages read like release notes. State the default directly while retaining the operational caveat that upgrades and setting changes leave existing mounts unchanged. --- content/manuals/ai/sandboxes/architecture.md | 5 ++--- content/manuals/ai/sandboxes/security/_index.md | 6 +++--- content/manuals/ai/sandboxes/security/defaults.md | 7 +++---- .../manuals/ai/sandboxes/workflows/agent-skills.md | 14 ++++++-------- 4 files changed, 14 insertions(+), 18 deletions(-) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 529e5eb9f1ec..1d0cadc2e1be 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -52,9 +52,8 @@ 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/agent-skills.md) is an exception: sandboxes created for supported agents mount the same host-side store read-only -by default starting with `sbx` version 0.43.0. Use `--skills` or -`skills.defaultMode` to choose another mode at creation. Existing sandboxes -retain their mounts until recreated. +by default. Use `--skills` or `skills.defaultMode` to choose another mode at +creation. Existing sandboxes retain their mounts until recreated. 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/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index b2c888a147d7..ec12f359ff6b 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -28,9 +28,9 @@ What crosses the boundary into the VM: outbound HTTP requests. The raw credential values never enter the VM. - **Network access:** outbound TCP connections to destinations allowed by [network policy](defaults/) are proxied through the host. -- Shared agent skills: starting with `sbx` version 0.43.0, sandboxes created - for supported agents mount a persistent host-side store read-only by default - at the agent's skills directory. Use `--skills` or `skills.defaultMode` to choose another mode at +- Shared agent skills: sandboxes created for supported agents mount a + persistent host-side store read-only by default at the agent's skills + directory. Use `--skills` or `skills.defaultMode` to choose another mode at creation. Existing sandboxes retain their mounts until recreated. - **MCP gateway traffic:** supported agents connect to a host-side MCP gateway endpoint. The gateway brokers access to registered MCP servers. diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 39a35831ff52..dd90dec34d6d 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -39,10 +39,9 @@ workspace modes and what to review after a direct-mount session. ## Shared skills defaults -Starting with `sbx` version 0.43.0, sandboxes created for supported agents mount -a persistent shared skills store read-only by default. The `skills.defaultMode` -setting can change this default, and `--skills` overrides it for a sandbox at -creation. A sandbox with `readwrite` access can change skills that other +Sandboxes created for supported agents mount a persistent shared skills store +read-only by default. The `skills.defaultMode` setting can change this default, +and `--skills` overrides it for a sandbox at creation. A sandbox with `readwrite` access can change skills that other participating sandboxes load, including those with `readonly` access. Use `--skills=off` when creating a sandbox to omit the shared store. Existing sandboxes retain their mounts until recreated. See diff --git a/content/manuals/ai/sandboxes/workflows/agent-skills.md b/content/manuals/ai/sandboxes/workflows/agent-skills.md index f66a1ad2d515..7322fe4c11e8 100644 --- a/content/manuals/ai/sandboxes/workflows/agent-skills.md +++ b/content/manuals/ai/sandboxes/workflows/agent-skills.md @@ -120,10 +120,9 @@ repository, so `sbx skills update` won't refresh it. Running `sbx reset` clears the shared store. -Starting with `sbx` version 0.43.0, sandboxes created for a supported agent -mount the shared store read-only by default. These sandboxes mount the contents -of the store each time they start, so you can install skills before or after -creating them. +Sandboxes created for a supported agent mount the shared store read-only by +default. These sandboxes mount the contents of the store each time they start, +so you can install skills before or after creating them. Use `--skills` with `sbx run` or `sbx create` to choose the access mode when creating a sandbox: @@ -149,10 +148,9 @@ When no mode is specified, the daemon uses `skills.defaultMode`, whose built-in value is `readonly`. An explicit `--skills` value overrides that default. The mode is applied only when a sandbox is created. Upgrading `sbx` or changing -`skills.defaultMode` leaves existing sandbox mounts unchanged, including -read-write mounts created with earlier versions. Remove and recreate a sandbox -to change its mode. Sandboxes created without shared skills also need to be -recreated to mount the store. +`skills.defaultMode` leaves existing sandbox mounts unchanged. Remove and +recreate a sandbox to change its mode. Sandboxes created without shared skills +also need to be recreated to mount the store. > [!WARNING] > A sandbox with `readwrite` access can modify skills that other sandboxes load,