From e7229578e7bee3f269dd02ea3e537c2cb0d87314 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:19:44 +0000 Subject: [PATCH 1/2] docs: explain sensitive-state mount restrictions in Sandboxes Workspace guidance omitted the restriction on host mounts that overlap Sandboxes configuration, state, or credentials. Document the explicit opt-in, its policy constraints, and the access retained after disabling it. --- .../configuration/environment-files.md | 5 ++++ .../ai/sandboxes/configuration/settings.md | 30 +++++++++++++++++++ .../manuals/ai/sandboxes/security/defaults.md | 7 +++++ 3 files changed, 42 insertions(+) diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index b4d8b78d88e6..aa68297bff92 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -770,6 +770,11 @@ clone mode. Omit `workspace` to create a sandbox without a host bind mount. Set `workspace: .` to mount the directory that contains the environment file that declares it. +For local sandboxes, workspace paths must satisfy the +[host mount restrictions](settings.md#mountsallowsensitivestate). These +restrictions also apply to `additionalWorkspaces`, including read-only mounts, +and explicit kit `mounts` bindings. + For environment file placement and write protection, see [Protect the environment file](#protect-the-environment-file). diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md index 83be65bba68e..2083ac4b4d0f 100644 --- a/content/manuals/ai/sandboxes/configuration/settings.md +++ b/content/manuals/ai/sandboxes/configuration/settings.md @@ -218,6 +218,36 @@ permissions, outside the sandbox. Leave the setting at `false` to require approval on every invocation, or use `--force` to approve only one invocation. See [environment lifecycle commands](environment-files.md#lifecycle). +#### mounts.allowSensitiveState {.wrap-anywhere} + +{{< setting-metadata type="boolean" default="false" >}} + +Local sandboxes reject host mounts whose resolved paths overlap Docker Sandboxes +configuration, state, or filesystem credential directories. This includes +read-only mounts and broad workspaces, such as a home directory that contains +protected directories. Choose a narrower host source to avoid exposing this data. + +If you intend to grant that access, enable the setting before creating the +sandbox, adding the mount, or introducing a protected mount through a kit change: + +```console +$ sbx settings set mounts.allowSensitiveState true +``` + +Organization mount policy still applies. +Enabling this setting can expose sensitive host data to sandboxed processes. + +Set it to `false` to block further mounts that overlap protected directories: + +```console +$ sbx settings set mounts.allowSensitiveState false +``` + +Disabling the setting doesn't revoke access through mounts already admitted. +Remove those mounts or remove the sandbox to withdraw that access. Creating or +recreating a sandbox with protected mounts requires the setting to be enabled +again. + #### sandbox.fuse {.wrap-anywhere} {{< setting-metadata type="boolean" default="true" >}} diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 8f879c3c9143..6f11c2c2d883 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -30,6 +30,13 @@ rules. See [Sandbox governance](../../governance/_index.md). The agent can read, write, and delete any file within that directory, including hidden files, configuration files, build scripts, and Git hooks. +Workspaces and extra host mounts are rejected by default if their resolved +paths overlap Docker Sandboxes configuration, state, or filesystem credential +directories, even for read-only access. A home-directory workspace can include +these directories. Choose a narrower project directory, or explicitly grant +access with +[`mounts.allowSensitiveState`](../configuration/settings.md#mountsallowsensitivestate). + When you omit the workspace path from `sbx create`, the sandbox doesn't mount a host workspace. The agent uses the sandbox template's default working directory. Docker-provided agent templates use `/home/agent/workspace`. If the From cd435d20754774eae9d5dac842e6bd50a6e044d7 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:42:50 +0000 Subject: [PATCH 2/2] docs: clarify filesystem policy restrictions on sandbox mounts Workspace guidance omitted filesystem policy checks alongside sensitive-state restrictions. Explain required read and write permissions and link to organization policy guidance, including from the sensitive-state setting. --- .../ai/sandboxes/configuration/environment-files.md | 8 +++++--- content/manuals/ai/sandboxes/configuration/settings.md | 3 ++- content/manuals/ai/sandboxes/security/defaults.md | 7 +++++++ 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index aa68297bff92..d6d075c63f9d 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -771,9 +771,11 @@ clone mode. Omit `workspace` to create a sandbox without a host bind mount. Set that declares it. For local sandboxes, workspace paths must satisfy the -[host mount restrictions](settings.md#mountsallowsensitivestate). These -restrictions also apply to `additionalWorkspaces`, including read-only mounts, -and explicit kit `mounts` bindings. +[host mount restrictions](settings.md#mountsallowsensitivestate) and any +[organization filesystem policy](../../governance/organization/policies/filesystem.md). +A policy can block a mount based on its host path and whether it needs read or +write access. These checks also apply to `additionalWorkspaces`, including +read-only mounts, and explicit kit `mounts` bindings. For environment file placement and write protection, see [Protect the environment file](#protect-the-environment-file). diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md index 2083ac4b4d0f..d75d76823c94 100644 --- a/content/manuals/ai/sandboxes/configuration/settings.md +++ b/content/manuals/ai/sandboxes/configuration/settings.md @@ -234,7 +234,8 @@ sandbox, adding the mount, or introducing a protected mount through a kit change $ sbx settings set mounts.allowSensitiveState true ``` -Organization mount policy still applies. +[Organization filesystem policy](../../governance/organization/policies/filesystem.md) +still applies and can block a mount even when this setting is enabled. Enabling this setting can expose sensitive host data to sandboxed processes. Set it to `false` to block further mounts that overlap protected directories: diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 6f11c2c2d883..c24b56025ad1 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -37,6 +37,13 @@ these directories. Choose a narrower project directory, or explicitly grant access with [`mounts.allowSensitiveState`](../configuration/settings.md#mountsallowsensitivestate). +[Organization filesystem policies](../../governance/organization/policies/filesystem.md) +can also block workspace and extra host mounts. If you're governed, the policy +must allow the host path for the access the mount needs: `read` for a read-only +mount, or both `read` and `write` for a writable mount. A deny rule takes +precedence over an allow. Enabling `mounts.allowSensitiveState` doesn't bypass +these policies. + When you omit the workspace path from `sbx create`, the sandbox doesn't mount a host workspace. The agent uses the sandbox template's default working directory. Docker-provided agent templates use `/home/agent/workspace`. If the