From bf21564646df4a14d1c85fc63bc8f672f7ab8fef Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 09:21:24 +0000 Subject: [PATCH 01/35] docs: stub mcp governance policy docs MCP policy support needed public-facing governance documentation before broader rollout. Add a focused governance stub covering Cedar-based MCP policy concepts, approval gates, organization policy context, and audit-log coverage. --- .../manuals/ai/sandboxes/governance/_index.md | 34 ++++++----- .../manuals/ai/sandboxes/governance/audit.md | 8 ++- .../ai/sandboxes/governance/concepts.md | 60 +++++++++++++++++-- .../manuals/ai/sandboxes/governance/org.md | 57 ++++++++++++------ 4 files changed, 119 insertions(+), 40 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index d3bf414a603d..b59e087e62f1 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -2,22 +2,24 @@ title: Governance weight: 55 description: Control what sandboxes can access, from local developer rules to org-wide enforcement. -keywords: docker sandboxes, governance, policy, network access, filesystem access, organization policy +keywords: docker sandboxes, governance, policy, network access, filesystem access, mcp policy, organization policy --- Sandbox governance covers the policy system that controls what sandboxes can -access over the network and on the filesystem. It operates at two layers, and -only one applies at a time: +access over the network, on the filesystem, and through MCP. It operates at two +layers, and only one applies at a time: **Local policy** is configured per machine using the `sbx policy` CLI. It lets individual developers customize which domains their sandboxes can reach. See [Local policy](local.md). -**Organization policy** is configured centrally in Docker Home or -via the [Governance API](/reference/api/ai-governance/). Rules defined at the org level apply -uniformly across every sandbox in the organization. When organization -governance is active, it replaces local policy entirely: local `sbx policy` -rules are no longer evaluated. See [Organization policy](org.md). +**Organization policy** is configured centrally in the Docker Admin Console. +Network and filesystem policies can also be managed via the +[Governance API](/reference/api/ai-governance/). Rules defined at the org level +apply uniformly across every sandbox in the organization. Organization +governance can also include MCP policies for sandbox MCP activity. When +organization governance is active, it replaces local policy entirely: local +`sbx policy` rules are no longer evaluated. See [Organization policy](org.md). Alongside this access-control policy, admins can require developers to sign in as members of their organization before using sandboxes at all. @@ -32,17 +34,17 @@ personal account. ## Learn more -- [Policy concepts](concepts.md): resource model, rule syntax, evaluation, - and precedence +- [Policy concepts](concepts.md): resource model, rule syntax, MCP policy, + evaluation, and precedence - [Local policy](local.md): configure network and filesystem rules on your machine with the `sbx policy` CLI -- [Organization policy](org.md): centrally manage sandbox policies across - your organization +- [Organization policy](org.md): centrally manage sandbox policies across your + organization from the Admin Console - [Sign-in enforcement](sign-in-enforcement.md): require developers to sign in as organization members, enforced through endpoint management - [Monitoring](monitoring.md): inspect active rules and monitor sandbox network traffic with `sbx policy ls` and `sbx policy log` -- [Audit logs](audit.md): capture a durable, structured record of every - policy decision for SIEM ingestion and compliance -- [API reference](/reference/api/ai-governance/): manage org policies - programmatically via the Governance API +- [Audit logs](audit.md): capture a durable, structured record of policy + decisions for SIEM ingestion and compliance +- [API reference](/reference/api/ai-governance/): manage network and filesystem + org policies programmatically via the Governance API diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index ceaf67dbc0df..bf046e1ebc0a 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -3,7 +3,7 @@ title: Audit logging linkTitle: Audit logs weight: 28 description: Capture a structured, durable record of every sandbox policy decision for SIEM ingestion and compliance. -keywords: docker sandboxes, audit log, audit logging, policy decision, SIEM, compliance, jsonl, splunk, filebeat +keywords: docker sandboxes, audit log, audit logging, policy decision, MCP policy, SIEM, compliance, jsonl, splunk, filebeat --- The sandbox daemon records a structured audit event for every policy decision @@ -40,6 +40,10 @@ The daemon writes two categories of record: Evaluation records share the run's `audit_session_id`, so you can correlate every decision back to a single daemon session. +When MCP policy enforcement is active, MCP evaluations use the same evaluation +record category. The action and resource values identify the MCP request, such +as a tool call or resource read. + A network evaluation record looks like this: ```json @@ -84,7 +88,7 @@ Common fields include: | `resource_id` | The target of the evaluation, such as a host and port. | | `decision` | `AUDIT_DECISION_ALLOW` or `AUDIT_DECISION_DENY`. | | `deny_reason` | Why a denied request was blocked. Present on deny decisions. | -| `agent` | The AI agent driving the sandbox (for example, `claude`, `codex`). Omitted when the agent is unknown. | +| `agent` | The AI agent driving the sandbox (for example, `claude`, `codex`). Omitted when the agent is unknown. | Each record is attributed to the signed-in Docker user and the organization whose governance policy is in effect. diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 2b59e6b2e7aa..6c5f71cc175c 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -2,7 +2,7 @@ title: Policy concepts weight: 5 description: The resource model, rule syntax, and evaluation logic behind Docker sandbox governance. -keywords: docker sandboxes, policy concepts, rule syntax, network rules, filesystem rules, precedence, rule evaluation +keywords: docker sandboxes, policy concepts, rule syntax, network rules, filesystem rules, mcp policy, cedar policy, precedence, rule evaluation --- ## Resource model @@ -15,7 +15,8 @@ Policies exist at two levels: - **Local**: configured per machine using the `sbx policy` CLI. Applies to sandboxes on that machine only. -- **Organization**: configured in Docker Home or via the +- **Organization**: configured in the Docker Admin Console. Network and + filesystem policies can also be managed via the [Governance API](/reference/api/ai-governance/). Applies to sandboxes across the organization. An organization can have several policies, each applying either org-wide or to specific teams. See [Policy scope](#policy-scope). @@ -30,8 +31,10 @@ A **rule** is the unit of access control within a policy. Each rule has: - **Resources**: the targets the rule matches against - **Decision**: `allow` or `deny` -Rules are grouped by domain: all rules in a policy must share the same domain, -either `network` or `filesystem`. +Rules are grouped by domain. Network and filesystem rules in a policy must +share the same domain, either `network` or `filesystem`. MCP policies use Cedar +statements written in the `MCP` namespace instead of the network and filesystem +rule format. ## Policy scope @@ -115,6 +118,52 @@ Use `**` to match a directory tree recursively. A single `*` matches within one path segment and won't cross a path separator. For example, `~/**` matches all paths under the home directory, while `~/*` matches only its direct children. +### MCP policies + +MCP policies control Model Context Protocol activity made available to a +sandbox through Docker's MCP gateway. They are organization policies written in +Cedar using the `MCP` namespace, rather than the network and filesystem rule +format. + +Cedar evaluates each MCP request against a principal, action, resource, and +context. Admins write rules for the action, resource, and context. Policy scope +supplies the principal, so a rule that tries to match a specific user, team, +tenant, or role in the principal doesn't match. + +Governed MCP actions are default deny: an MCP request is blocked unless a +matching `permit` allows it. A matching `forbid` overrides any `permit`, +including a permit that requires approval. + +MCP policies can match actions such as: + +- `register`: Register an MCP server +- `invokeTool`: Call an MCP tool +- `invokePrimordial`: Call a gateway meta-tool +- `readResource`: Read an MCP resource +- `getPrompt`: Retrieve an MCP prompt + +Resources are referenced with `MCP` entity types, such as `MCP::Server`, +`MCP::Tool`, `MCP::Resource`, `MCP::Prompt`, and `MCP::Primordial`. For example, +a tool policy can match the server that exposes the tool, the tool's bare name, +and server-declared tool annotations such as `readOnly` or `destructive`. + +The following policy allows tools that the server declares read-only, and +requires approval before a non-read-only tool can run: + +```cedar +permit (principal, action == MCP::Action::"invokeTool", resource) +when { resource.readOnly == true }; + +@requireApproval("write tool call") +permit (principal, action == MCP::Action::"invokeTool", resource) +when { resource.readOnly == false }; +``` + +The `@requireApproval` annotation applies to `permit` statements. When a request +matches that permit and no matching `forbid` overrides it, the sandbox asks the +user to approve before the request runs. If the request can't be presented to a +user for approval, it is denied. + ## Rule evaluation When organization governance is active, the rules from all of a user's @@ -125,7 +174,8 @@ each request, following two principles: regardless of any matching allow rules. - Default deny: anything an allow rule doesn't match is blocked. Outbound network traffic is blocked unless a network rule allows the destination, and a - host path can't be mounted unless a filesystem rule allows it. + host path can't be mounted unless a filesystem rule allows it. MCP activity is + blocked unless an MCP `permit` allows it. Because every effective policy feeds the same evaluation, allows are additive (a request is allowed if any effective policy allows it) and denies are absolute (a diff --git a/content/manuals/ai/sandboxes/governance/org.md b/content/manuals/ai/sandboxes/governance/org.md index 54dda20e710e..5c03bef88dbe 100644 --- a/content/manuals/ai/sandboxes/governance/org.md +++ b/content/manuals/ai/sandboxes/governance/org.md @@ -2,21 +2,23 @@ title: Organization policy linkTitle: Org policy weight: 20 -description: Centrally manage sandbox network and filesystem policies for your organization. -keywords: docker sandboxes, governance, organization policy, AI governance, Docker Home, network access, filesystem access +description: Centrally manage sandbox network, filesystem, and MCP policies for your organization. +keywords: docker sandboxes, governance, organization policy, AI governance, admin console, network access, filesystem access, mcp policy aliases: - /ai/sandboxes/security/governance/ --- [Local policies](local.md) give individual developers control over what their sandboxes can access. Organization policy moves that control to the admin level: -rules apply to sandboxes across the organization, -either to every member or to specific teams. When organization governance is active, it replaces local `sbx policy` -rules entirely — local rules are no longer evaluated and can't be used to -supplement or override the organization policy. +rules defined in **Admin Console** apply to sandboxes across the organization, +either to every member or to specific teams. When organization governance is +active, it replaces local `sbx policy` rules entirely — local rules are no +longer evaluated and can't be used to supplement or override the organization +policy. -Admins can manage organization policies through the Docker Home UI or -programmatically using the [Governance API](/reference/api/ai-governance/). +Admins can manage organization policies through the Admin Console UI. For +programmatic management of network and filesystem policies, use the +[Governance API](/reference/api/ai-governance/). By default, only organization [owners](/manuals/enterprise/security/roles-and-permissions/core-roles.md) can @@ -33,17 +35,19 @@ with the **Governance** permissions and assign it to a user or team. ## Create a policy -Manage policies from the **AI Platform** section in the left-hand navigation +Manage policies under **Admin Console**, a section in the left-hand navigation of [Docker Home](https://app.docker.com). Network and filesystem policies are managed separately, under **Network access** and **Filesystem access**. +The steps in this section cover network and filesystem policies. MCP policies +use Cedar rather than rule rows; see [MCP policies](#mcp-policies). + To create a policy: 1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -1. In the left-hand navigation, expand **AI Platform** and select - **Network access** or **Filesystem access**. -1. Select **Create policy**. +1. Select **AI Platform**, then the governance section you want. +1. Select **Network access** or **Filesystem access**, then **Create policy**. 1. Enter a **Policy name**. 1. Set the **Scope** to **Organization** or **Teams**. If you select **Teams**, choose the teams the policy applies to. See @@ -82,6 +86,25 @@ rules. Each rule takes a path pattern and an action (allow or deny). For path pattern syntax and how read and write access combine to allow a mount, see [Policy concepts](concepts.md#filesystem-rules). +## MCP policies + +MCP policies control sandbox activity that goes through MCP servers, such as +server registration, tool calls, resource reads, prompts, and gateway +meta-tools. Unlike network and filesystem policies, MCP policies are written in +Cedar using the `MCP` namespace. + +MCP policy is default deny: an MCP request is blocked unless a matching +`permit` allows it. Use `forbid` for rules that must always deny a matching +request. A matching `forbid` overrides a `permit`, including one that requires +approval. + +Use `@requireApproval` on a `permit` statement to require user approval before a +matching request runs. If the sandbox can't ask a user for approval, the request +is denied. + +For the MCP policy model and a starter example, see +[MCP policies](concepts.md#mcp-policies). + ## Scope policies to teams An organization can have more than one policy, and each policy applies either @@ -99,7 +122,7 @@ Team scoping targets your organization's existing exist before you can scope a policy to it. Create teams and manage their members in one of two ways: -- Manually, in Docker Home. +- Manually, in the Admin Console. - Automatically, by using [group mapping](/manuals/enterprise/security/provisioning/scim/group-mapping.md) to synchronize your identity provider's groups with the teams in your @@ -172,21 +195,21 @@ wildcards match. ## Precedence When organization governance is active, local rules are not evaluated. Only -organization rules determine what is allowed or denied, +organization rules set in the Admin Console determine what is allowed or denied, and they can't be supplemented or overridden from a developer's machine. The same applies to filesystem policies: organization rules replace local behavior entirely. For how a user's organization policies are evaluated together, see [Policy concepts](concepts.md#rule-evaluation). To unblock a domain when organization governance is active, update the rule in -Docker Home or via the [API](/reference/api/ai-governance/). Without +the Admin Console or via the [API](/reference/api/ai-governance/). Without organization governance, remove the local rule with `sbx policy rm`. ## Troubleshooting ### Policy changes not taking effect -After updating organization policies, changes take up +After updating organization policies in the Admin Console, changes take up to 5 minutes to propagate to developer machines. To apply changes immediately, users can run `sbx policy reset`, which stops the daemon and forces it to pull the latest organization policies on the next `sbx` @@ -216,5 +239,5 @@ and create a new one. ### Sandbox cannot mount workspace If a sandbox fails to mount with a `mount policy denied` error, verify that -the filesystem allow rule uses `**` rather than `*`. A +the filesystem allow rule in the Admin Console uses `**` rather than `*`. A single `*` doesn't match across directory separators. From 36e4f362f2c26c24e2d832e6f2b7f6949f096133 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 09:56:44 +0000 Subject: [PATCH 02/35] docs: reorganize sandbox governance IA The governance section mixed policy scope, access surfaces, monitoring, enforcement, and reference pages at one level. Group governance docs into access controls, monitor and enforce, and reference; add network, filesystem, and MCP access pages; preserve old URLs with aliases and update inbound links. --- .../organization/manage/manage-licenses.md | 2 +- content/manuals/ai/sandboxes/_index.md | 6 +- .../ai/sandboxes/customize/kit-examples.md | 2 +- content/manuals/ai/sandboxes/faq.md | 8 +- content/manuals/ai/sandboxes/get-started.md | 7 +- .../manuals/ai/sandboxes/governance/_index.md | 56 +++++--- .../governance/access-controls/_index.md | 26 ++++ .../governance/access-controls/filesystem.md | 44 ++++++ .../governance/{ => access-controls}/local.md | 16 ++- .../governance/access-controls/mcp.md | 128 ++++++++++++++++++ .../governance/access-controls/network.md | 60 ++++++++ .../organization.md} | 51 +++---- .../ai/sandboxes/governance/concepts.md | 3 +- .../governance/monitor-and-enforce/_index.md | 16 +++ .../{ => monitor-and-enforce}/audit.md | 13 +- .../{ => monitor-and-enforce}/monitoring.md | 22 +-- .../sign-in-enforcement.md | 15 +- .../sandboxes/governance/reference/_index.md | 13 ++ .../governance/{ => reference}/api.md | 2 +- .../manuals/ai/sandboxes/troubleshooting.md | 6 +- .../subscription/plans/ai-governance.md | 2 +- 21 files changed, 404 insertions(+), 94 deletions(-) create mode 100644 content/manuals/ai/sandboxes/governance/access-controls/_index.md create mode 100644 content/manuals/ai/sandboxes/governance/access-controls/filesystem.md rename content/manuals/ai/sandboxes/governance/{ => access-controls}/local.md (94%) create mode 100644 content/manuals/ai/sandboxes/governance/access-controls/mcp.md create mode 100644 content/manuals/ai/sandboxes/governance/access-controls/network.md rename content/manuals/ai/sandboxes/governance/{org.md => access-controls/organization.md} (85%) create mode 100644 content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md rename content/manuals/ai/sandboxes/governance/{ => monitor-and-enforce}/audit.md (94%) rename content/manuals/ai/sandboxes/governance/{ => monitor-and-enforce}/monitoring.md (85%) rename content/manuals/ai/sandboxes/governance/{ => monitor-and-enforce}/sign-in-enforcement.md (95%) create mode 100644 content/manuals/ai/sandboxes/governance/reference/_index.md rename content/manuals/ai/sandboxes/governance/{ => reference}/api.md (95%) diff --git a/content/manuals/admin/organization/manage/manage-licenses.md b/content/manuals/admin/organization/manage/manage-licenses.md index 295e00f9c51e..5b0f2c035e7a 100644 --- a/content/manuals/admin/organization/manage/manage-licenses.md +++ b/content/manuals/admin/organization/manage/manage-licenses.md @@ -44,5 +44,5 @@ See these docs to explore Docker Core add-ons, or products that need licenses: - [Docker plans](/manuals/subscription/plans/_index.md) to learn about different add-ons - [Manage seats](/manuals/admin/organization/manage/manage-seats.md) to add more seats to your Docker Core subscription -- [AI Governance](/manuals/ai/sandboxes/governance/org.md) to set up organization policies for your organization members +- [AI Governance](/manuals/ai/sandboxes/governance/access-controls/organization.md) to set up organization policies for your organization members - [Docker Offload](/manuals/offload/about.md) to let your developers offload building and running containers to the cloud diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 1a05b57821e4..4b8399b2a20d 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -18,9 +18,9 @@ system. > [organization governance](governance/) requires a separate paid subscription. Organization admins can -[centrally manage sandbox network and filesystem policies](governance/org.md), -so the same rules apply uniformly across every developer's machine. Available -on a separate paid subscription. +[centrally manage sandbox network and filesystem policies](governance/access-controls/organization.md) +from the Docker Admin Console, so the same rules apply uniformly across every +developer's machine. Available on a separate paid subscription. ## Get started diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md index 4f28e25d77a8..72cb74da125c 100644 --- a/content/manuals/ai/sandboxes/customize/kit-examples.md +++ b/content/manuals/ai/sandboxes/customize/kit-examples.md @@ -77,7 +77,7 @@ Install steps run under `sh`, not bash, so bash-only builtins such as (`curl … | bash`) or wrap the step in `bash -c '…'` when you need them. Downloads are subject to the sandbox's -[deny-by-default network policy](../governance/local.md). A domain that +[deny-by-default network policy](../governance/access-controls/local.md). A domain that resolves from your host can still be blocked inside the sandbox — for example, `get.sdkman.io` returns a 403 until you allow it with `sbx policy allow network get.sdkman.io`. A tool may also need base diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 0b0bf00728aa..85db43615c8a 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -12,8 +12,8 @@ professional work, with no per-seat fee. Install it, sign in with a free Docker account, and run sandboxes at no cost. The only paid component is organization governance: centrally managed network -and filesystem policies, [sign-in enforcement](governance/sign-in-enforcement.md), -and [audit logs](governance/audit.md). These +and filesystem policies, [sign-in enforcement](governance/monitor-and-enforce/sign-in-enforcement.md), +and [audit logs](governance/monitor-and-enforce/audit.md). These [organization governance features](governance/) require a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) @@ -29,7 +29,7 @@ Signing in gives each sandbox a verified identity, which lets Docker: containers, install packages, and push code. Your Docker identity is the anchor. - **Enable team features.** Team-scale features like - [organization governance](governance/org.md), shared environments, and + [organization governance](governance/access-controls/organization.md), shared environments, and audit logs need a concept of "who," and adding that later would be worse for everyone. - **Authenticate against Docker infrastructure.** Sandboxes pull images, run @@ -45,7 +45,7 @@ rules apply to every sandbox in the organization. When organization governance is active, it replaces local rules set with `sbx policy` — local rules are no longer evaluated. -See [Organization governance](governance/org.md). This feature requires +See [Organization governance](governance/access-controls/organization.md). This feature requires a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to get started. diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 7289d445f6e2..7875902f4515 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -115,7 +115,7 @@ Use ↑/↓ to navigate, Enter to select, or press 1–3. **Balanced** is a good starting point — it permits traffic to common development services while blocking everything else. You can adjust individual -rules later. See [Policies](governance/local.md) for a full description of each +rules later. See [Policies](governance/access-controls/local.md) for a full description of each option. > [!NOTE] @@ -214,8 +214,9 @@ $ sbx policy allow network registry.npmjs.org With **Balanced**, common development services are allowed by default. With **Locked Down**, everything is blocked until you allow it — including your model provider's API. If the agent can't reach a service it needs, the network -policy is the first place to look. See [Policies](governance/local.md) for the -full rule set and how to customize it. +policy is the first place to look. See +[Policies](governance/access-controls/local.md) for the full rule set and how +to customize it. ## Clean up diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index b59e087e62f1..2f17a10d78a5 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -11,7 +11,7 @@ layers, and only one applies at a time: **Local policy** is configured per machine using the `sbx policy` CLI. It lets individual developers customize which domains their sandboxes can reach. -See [Local policy](local.md). +See [Local access rules](access-controls/local.md). **Organization policy** is configured centrally in the Docker Admin Console. Network and filesystem policies can also be managed via the @@ -19,13 +19,14 @@ Network and filesystem policies can also be managed via the apply uniformly across every sandbox in the organization. Organization governance can also include MCP policies for sandbox MCP activity. When organization governance is active, it replaces local policy entirely: local -`sbx policy` rules are no longer evaluated. See [Organization policy](org.md). +`sbx policy` rules are no longer evaluated. See +[Organization policies](access-controls/organization.md). Alongside this access-control policy, admins can require developers to sign in as members of their organization before using sandboxes at all. -[Sign-in enforcement](sign-in-enforcement.md) is deployed through endpoint -management and ensures developers can't bypass organization policy by using a -personal account. +[Sign-in enforcement](monitor-and-enforce/sign-in-enforcement.md) is deployed +through endpoint management and ensures developers can't bypass organization +policy by using a personal account. > [!NOTE] > Organization governance is available on a separate paid subscription. @@ -34,17 +35,34 @@ personal account. ## Learn more -- [Policy concepts](concepts.md): resource model, rule syntax, MCP policy, - evaluation, and precedence -- [Local policy](local.md): configure network and filesystem rules on your - machine with the `sbx policy` CLI -- [Organization policy](org.md): centrally manage sandbox policies across your - organization from the Admin Console -- [Sign-in enforcement](sign-in-enforcement.md): require developers to sign in - as organization members, enforced through endpoint management -- [Monitoring](monitoring.md): inspect active rules and monitor sandbox - network traffic with `sbx policy ls` and `sbx policy log` -- [Audit logs](audit.md): capture a durable, structured record of policy - decisions for SIEM ingestion and compliance -- [API reference](/reference/api/ai-governance/): manage network and filesystem - org policies programmatically via the Governance API +Start with [Policy concepts](concepts.md) for the resource model, rule syntax, +MCP policy basics, evaluation, and precedence. + +### Access controls + +- [Local access rules](access-controls/local.md): configure network rules on + your machine with the `sbx policy` CLI. +- [Organization policies](access-controls/organization.md): centrally manage + sandbox policies across your organization from the Admin Console. +- [Network access rules](access-controls/network.md): control outbound network + access from sandboxes. +- [Filesystem access rules](access-controls/filesystem.md): control which host + paths sandboxes can mount as workspaces. +- [MCP tool access](access-controls/mcp.md): control MCP server registration, + tool calls, resources, prompts, and approval gates. + +### Monitor and enforce + +- [Monitoring policies](monitor-and-enforce/monitoring.md): inspect active + rules and monitor sandbox network traffic with `sbx policy ls` and + `sbx policy log`. +- [Audit logs](monitor-and-enforce/audit.md): capture a durable, structured + record of policy decisions for SIEM ingestion and compliance. +- [Sign-in enforcement](monitor-and-enforce/sign-in-enforcement.md): require + developers to sign in as organization members, enforced through endpoint + management. + +### Reference + +- [AI Governance API](/reference/api/ai-governance/): manage network and + filesystem org policies programmatically. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/_index.md b/content/manuals/ai/sandboxes/governance/access-controls/_index.md new file mode 100644 index 000000000000..922e84e2de63 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/_index.md @@ -0,0 +1,26 @@ +--- +title: Access controls +weight: 10 +description: Configure local and organization controls for sandbox network, filesystem, and MCP access. +keywords: docker sandboxes, access controls, governance, network access, filesystem access, MCP access +--- + +Access controls define what sandboxes can reach or use. Use these pages to +configure policies by scope, then drill into the access surface you want to +govern. + +## Policy scope + +- [Local access rules](local.md): configure network rules on a developer + machine with the `sbx policy` CLI. +- [Organization policies](organization.md): manage centralized policies for an + organization or team in the Docker Admin Console. + +## Access surfaces + +- [Network access rules](network.md): control outbound network access from + sandboxes. +- [Filesystem access rules](filesystem.md): control which host paths sandboxes + can mount as workspaces. +- [MCP tool access](mcp.md): control MCP server registration, tool calls, + resources, prompts, and approval gates with Cedar policy. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md new file mode 100644 index 000000000000..05076b1ef587 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md @@ -0,0 +1,44 @@ +--- +title: Filesystem access rules +linkTitle: Filesystem access +weight: 40 +description: Control which host paths Docker Sandboxes can mount as workspaces with organization filesystem policies. +keywords: docker sandboxes, filesystem access, filesystem rules, workspace mount, organization policy, governance +--- + +Filesystem access rules control which host paths a sandbox can mount as a +workspace. They help admins restrict sandbox workspaces to approved directories +across an organization. + +Filesystem access is managed with [organization policies](organization.md). When +organization governance is active, filesystem rules replace local behavior for +workspace mounts. + +## Rule syntax + +Filesystem rules use the actions `read` and `write`. Resources are host path +patterns. + +A writable workspace mount must be allowed by both a `read` rule and a `write` +rule. A read-only workspace needs only `read`. + +Examples: + +- `~/**` +- `/data/project/**` +- `C:\data\project\**` +- `\\wsl.localhost\\data\project\**` + +Use `**` to match a directory tree recursively. A single `*` matches only one +path segment. For exact path matching behavior across macOS, Linux, Windows, +and WSL, see [Filesystem rules](../concepts.md#filesystem-rules). + +## Organization filesystem rules + +Admins manage filesystem policies in the Docker Admin Console. A policy can +apply to the whole organization or to selected teams. For setup steps and team +scoping, see [Organization policies](organization.md). + +Filesystem policy is checked when a workspace is mounted, which happens when a +sandbox is created. To apply a filesystem policy change to a running workflow, +remove the sandbox and create a new one. diff --git a/content/manuals/ai/sandboxes/governance/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md similarity index 94% rename from content/manuals/ai/sandboxes/governance/local.md rename to content/manuals/ai/sandboxes/governance/access-controls/local.md index 10fd14f2a8c5..38e2d217eefd 100644 --- a/content/manuals/ai/sandboxes/governance/local.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -1,10 +1,12 @@ --- -title: Local policy +title: Local access rules +linkTitle: Local rules weight: 10 description: Configure network access rules for sandboxes on your local machine. keywords: docker sandboxes, local policy, network access, allow rules, deny rules, sbx policy aliases: - /ai/sandboxes/security/policy/ + - /ai/sandboxes/governance/local/ --- The `sbx policy` command manages network access rules on your local machine. @@ -18,12 +20,13 @@ Local rules apply only when your organization doesn't enforce governance: Local rules are inactive, and `sbx policy allow` and `sbx policy deny` have no effect. To list the inactive local rules, run `sbx policy ls --include-inactive`. See - [Monitoring](monitoring.md#showing-inactive-rules). + [Monitoring](../monitor-and-enforce/monitoring.md#showing-inactive-rules). -See [Organization policy](org.md) for how organization governance works. +See [Organization policies](organization.md) for how organization governance +works. For domain patterns, wildcards, CIDR ranges, and filesystem path syntax, see -[Policy concepts](concepts.md#rule-syntax). +[Policy concepts](../concepts.md#rule-syntax). ## Default preset @@ -61,7 +64,7 @@ v0.35.0, the Balanced preset also allows VS Code domains, Azure Blob Storage > [!NOTE] > If your organization manages sandbox policies centrally, organization rules > take precedence over the preset you select here. See -> [Organization policy](org.md). +> [Organization policies](organization.md). ### Non-interactive environments @@ -117,7 +120,8 @@ To inspect which policies are active and where they come from, use `sbx policy ls`. Use `--source` to filter by origin (`local`, `org`, `kit`), `--decision` to filter by outcome (`allow`, `deny`), and `--wide` for rule-level detail including rule IDs. To inspect a single policy or rule in -full, use `sbx policy inspect`. See [Monitoring](monitoring.md). +full, use `sbx policy inspect`. See +[Monitoring](../monitor-and-enforce/monitoring.md). ## Testing policy diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md new file mode 100644 index 000000000000..4e2744f775ef --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md @@ -0,0 +1,128 @@ +--- +title: Control MCP tool access +linkTitle: MCP tool access +weight: 50 +description: Use Cedar-based MCP policies to control sandbox MCP server registration, tool calls, prompts, resources, and approval gates. +keywords: docker sandboxes, MCP policy, MCP tool access, Cedar policy, requireApproval, AI Governance +--- + +MCP access rules control Model Context Protocol activity made available to a +sandbox through Docker's MCP gateway. Use them to govern server registration, +tool calls, gateway meta-tools, resources, prompts, and approval requirements. + +Unlike [network access rules](network.md) and +[filesystem access rules](filesystem.md), MCP access rules are organization +policies written in Cedar. Docker defines the `MCP` namespace, including the +actions, resource types, attributes, and approval behavior that policies can +match. For the full Cedar language, see the +[Cedar documentation](https://docs.cedarpolicy.com/). + +## How MCP policy works + +Cedar evaluates each request against a principal, action, resource, and context. +For Docker MCP policies: + +- Policy scope supplies the principal. Use organization or team scope instead + of matching users, teams, tenants, or roles in the policy. +- Actions use the `MCP::Action` namespace, such as + `MCP::Action::"invokeTool"`. +- Resources use MCP entity types, such as `MCP::Server`, `MCP::Tool`, + `MCP::Resource`, `MCP::Prompt`, and `MCP::Primordial`. +- Governed MCP activity is default deny. A request is blocked unless a + matching `permit` allows it. +- A matching `forbid` overrides any `permit`, including a permit with + `@requireApproval`. + +## Start with a baseline + +To allow all MCP activity while you build a narrower policy, use an actionless +`permit`: + +```cedar +permit (principal, action, resource); +``` + +This is useful as a temporary baseline. For production policies, prefer +patterns that limit access to approved servers, read-only tools, or +approval-gated tool calls. + +## Allow read-only tools + +Servers can declare tool annotations such as `readOnly` and `destructive`. To +allow tools that a server marks read-only: + +```cedar +permit (principal, action == MCP::Action::"invokeTool", resource) +when { resource.readOnly == true }; +``` + +`readOnly` defaults to `false` for tools that don't declare it, so this pattern +fails closed for unannotated tools. + +## Require approval for writes + +Use `@requireApproval` on a `permit` statement to require user approval before +a matching request runs: + +```cedar +permit (principal, action == MCP::Action::"invokeTool", resource) +when { resource.readOnly == true }; + +@requireApproval("write tool call") +permit (principal, action == MCP::Action::"invokeTool", resource) +when { resource.readOnly == false }; +``` + +If the sandbox can't ask a user for approval, the request is denied. A matching +`forbid` still denies the request without showing an approval prompt. + +## Limit tools to approved servers + +Use `MCP::Server` to match the registered server that exposes a tool: + +```cedar +permit (principal, action == MCP::Action::"invokeTool", resource) +when { + resource.readOnly == true && + (resource in MCP::Server::"github" || resource in MCP::Server::"notion") +}; +``` + +Server names must match the registered MCP server names. + +## Block destructive tools + +Use `forbid` for controls that must always win over permits: + +```cedar +permit (principal, action == MCP::Action::"invokeTool", resource); + +forbid (principal, action == MCP::Action::"invokeTool", resource) +when { resource.destructive == true }; +``` + +`destructive` defaults to `true` for tools that don't declare it, so this +pattern also blocks unannotated tools. + +## Control server registration + +Use the `register` action to control which MCP servers can be registered: + +```cedar +permit (principal, action == MCP::Action::"register", resource) +when { resource in MCP::Server::"github" }; + +permit (principal, action == MCP::Action::"register", resource) +when { resource in MCP::Server::"notion" }; +``` + +For remote server registration, match attributes the gateway provides, such as +server type, identity URL, OAuth requirement, or network requirement. Local +server command and argument attributes don't apply to remote servers. + +## Next steps + +- Use [Policy concepts](../concepts.md#mcp-policies) for the MCP policy model. +- Use [Organization policies](organization.md) to manage policy scope. +- Use [Audit logs](../monitor-and-enforce/audit.md) to collect policy decision + records. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md new file mode 100644 index 000000000000..7a37a95787a8 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -0,0 +1,60 @@ +--- +title: Network access rules +linkTitle: Network access +weight: 30 +description: Control outbound network access from Docker Sandboxes with local and organization policy rules. +keywords: docker sandboxes, network access, network rules, governance, local policy, organization policy +--- + +Network access rules control outbound connections from sandboxes. Use them to +allow the domains, IP ranges, and ports a workflow needs, and to block +destinations that should stay unavailable. + +You can configure network access in two places: + +- [Local access rules](local.md), which apply to sandboxes on one developer + machine when organization governance is not active. +- [Organization policies](organization.md), which apply centrally across an + organization or to selected teams. + +When organization governance is active, organization network rules replace +local rules. Local rules are inactive until organization governance no longer +applies. + +## Rule syntax + +Network rules use the actions `connect:tcp` and `connect:udp`. Resources are +hostnames, CIDR ranges, ports, or hostnames with ports. + +Examples: + +- `api.example.com` +- `*.example.com` +- `**.example.com` +- `example.com:443` +- `10.0.0.0/8` + +For exact wildcard behavior and CIDR support, see +[Network rules](../concepts.md#network-rules). + +## Local network rules + +Use `sbx policy allow network` and `sbx policy deny network` to manage local +network rules: + +```console +$ sbx policy allow network api.example.com +$ sbx policy deny network ads.example.com +``` + +For presets, sandbox-scoped rules, testing, and troubleshooting, see +[Local access rules](local.md). + +## Organization network rules + +Admins manage organization network rules in the Docker Admin Console. A policy +can apply to the whole organization or to selected teams. For setup steps and +team scoping, see [Organization policies](organization.md). + +Use [Monitoring policies](../monitor-and-enforce/monitoring.md) to inspect +which network rules are active on a developer machine. diff --git a/content/manuals/ai/sandboxes/governance/org.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md similarity index 85% rename from content/manuals/ai/sandboxes/governance/org.md rename to content/manuals/ai/sandboxes/governance/access-controls/organization.md index 5c03bef88dbe..e48d7360da82 100644 --- a/content/manuals/ai/sandboxes/governance/org.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -1,11 +1,12 @@ --- -title: Organization policy -linkTitle: Org policy +title: Organization policies +linkTitle: Org policies weight: 20 description: Centrally manage sandbox network, filesystem, and MCP policies for your organization. keywords: docker sandboxes, governance, organization policy, AI governance, admin console, network access, filesystem access, mcp policy aliases: - /ai/sandboxes/security/governance/ + - /ai/sandboxes/governance/org/ --- [Local policies](local.md) give individual developers control over what their @@ -40,7 +41,8 @@ of [Docker Home](https://app.docker.com). Network and filesystem policies are managed separately, under **Network access** and **Filesystem access**. The steps in this section cover network and filesystem policies. MCP policies -use Cedar rather than rule rows; see [MCP policies](#mcp-policies). +use Cedar rather than rule rows. For MCP examples, see +[MCP tool access](mcp.md). To create a policy: @@ -53,7 +55,7 @@ To create a policy: choose the teams the policy applies to. See [Scope policies to teams](#scope-policies-to-teams). 1. Select **Add rule** to add each rule. For rule syntax, see - [Policy concepts](concepts.md#rule-syntax). + [Policy concepts](../concepts.md#rule-syntax). Existing policies are listed with their name, scope, rule count, and last update. Use the action menu (⋮) to edit or delete a policy. @@ -66,13 +68,13 @@ A network rule takes a network target and an action (allow or deny). You can add multiple entries at once, one per line. For the full syntax reference (exact hostnames, wildcard subdomains, port -suffixes, and CIDR ranges), see [Policy concepts](concepts.md#network-rules). +suffixes, and CIDR ranges), see [Network access rules](network.md). When organization governance is active, local network rules are not evaluated. The organization policy is the only policy in effect. `sbx policy ls` hides these inactive local rules by default. See -[Monitoring](monitoring.md#showing-inactive-rules) for how to list them and read -the rule view. +[Monitoring](../monitor-and-enforce/monitoring.md#showing-inactive-rules) for +how to list them and read the rule view. ## Filesystem policies @@ -84,26 +86,15 @@ Admins can restrict which paths are mountable with filesystem allow and deny rules. Each rule takes a path pattern and an action (allow or deny). For path pattern syntax and how read and write access combine to allow a -mount, see [Policy concepts](concepts.md#filesystem-rules). +mount, see [Filesystem access rules](filesystem.md). ## MCP policies MCP policies control sandbox activity that goes through MCP servers, such as server registration, tool calls, resource reads, prompts, and gateway meta-tools. Unlike network and filesystem policies, MCP policies are written in -Cedar using the `MCP` namespace. - -MCP policy is default deny: an MCP request is blocked unless a matching -`permit` allows it. Use `forbid` for rules that must always deny a matching -request. A matching `forbid` overrides a `permit`, including one that requires -approval. - -Use `@requireApproval` on a `permit` statement to require user approval before a -matching request runs. If the sandbox can't ask a user for approval, the request -is denied. - -For the MCP policy model and a starter example, see -[MCP policies](concepts.md#mcp-policies). +Cedar using the `MCP` namespace. For policy patterns and examples, see +[MCP tool access](mcp.md). ## Scope policies to teams @@ -135,12 +126,12 @@ team membership changes, including changes synced from your IdP. ### How org-wide and team-scoped policies combine A user is governed by all of their -[effective policies](concepts.md#policy-scope) at once — every org-wide policy, -plus the team-scoped policies for the teams they belong to. The rules combine -into a single evaluation in which deny always wins, so a team-scoped policy can -grant access on top of the org-wide policies but can't loosen a restriction they -impose. For the full evaluation model, see -[Rule evaluation](concepts.md#rule-evaluation). +[effective policies](../concepts.md#policy-scope) at once — every org-wide +policy, plus the team-scoped policies for the teams they belong to. The rules +combine into a single evaluation in which deny always wins, so a team-scoped +policy can grant access on top of the org-wide policies but can't loosen a +restriction they impose. For the full evaluation model, see +[Rule evaluation](../concepts.md#rule-evaluation). This makes org-wide policies the natural home for guardrails that must hold everywhere. For example, an org-wide policy can deny a category of domains for @@ -158,7 +149,7 @@ The examples that follow show each pattern. ### Grant one team access to a blocked domain -Because access is [denied by default](concepts.md#rule-evaluation), you don't +Because access is [denied by default](../concepts.md#rule-evaluation), you don't need an explicit deny to keep a domain off-limits. Leaving it out of every allow rule is enough. To give a single team access to a domain no one else can reach: @@ -189,7 +180,7 @@ team allow apply to different hostnames, so they never conflict. To block a domain and all its subdomains, deny `**.example.com` instead. With that pattern, deny wins over any team-scoped allow on a subdomain. See -[Hostname patterns](concepts.md#network-rules) for how exact hostnames and +[Hostname patterns](../concepts.md#network-rules) for how exact hostnames and wildcards match. ## Precedence @@ -199,7 +190,7 @@ organization rules set in the Admin Console determine what is allowed or denied, and they can't be supplemented or overridden from a developer's machine. The same applies to filesystem policies: organization rules replace local behavior entirely. For how a user's organization policies are evaluated together, see -[Policy concepts](concepts.md#rule-evaluation). +[Policy concepts](../concepts.md#rule-evaluation). To unblock a domain when organization governance is active, update the rule in the Admin Console or via the [API](/reference/api/ai-governance/). Without diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 6c5f71cc175c..f6ef9449bd68 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -196,7 +196,8 @@ whether your organization has governance enabled: - Organization governance active: organization rules apply across all developer machines, and local and kit-defined rules are not evaluated. `sbx policy ls` hides these inactive rules by default; see - [Monitoring](monitoring.md#showing-inactive-rules) for how to list them. + [Monitoring](monitor-and-enforce/monitoring.md#showing-inactive-rules) for how + to list them. When organization governance is active, a user's organization policies are evaluated together, as described in [Rule evaluation](#rule-evaluation). diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md new file mode 100644 index 000000000000..e8a66facbc6f --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md @@ -0,0 +1,16 @@ +--- +title: Monitor and enforce +weight: 20 +description: Inspect active sandbox governance rules, collect audit records, and enforce organization sign-in. +keywords: docker sandboxes, governance monitoring, audit logs, sign-in enforcement, policy enforcement +--- + +After policies are configured, use monitoring, audit records, and sign-in +enforcement to verify how governance behaves across developer machines. + +- [Monitoring policies](monitoring.md): inspect active policy rules and monitor + sandbox network traffic. +- [Audit logs](audit.md): collect structured records of policy decisions for + SIEM ingestion and compliance. +- [Sign-in enforcement](sign-in-enforcement.md): require users to sign in as + members of approved Docker organizations. diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/audit.md similarity index 94% rename from content/manuals/ai/sandboxes/governance/audit.md rename to content/manuals/ai/sandboxes/governance/monitor-and-enforce/audit.md index bf046e1ebc0a..7434ea20d2ae 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/audit.md @@ -1,9 +1,11 @@ --- title: Audit logging linkTitle: Audit logs -weight: 28 +weight: 20 description: Capture a structured, durable record of every sandbox policy decision for SIEM ingestion and compliance. keywords: docker sandboxes, audit log, audit logging, policy decision, MCP policy, SIEM, compliance, jsonl, splunk, filebeat +aliases: + - /ai/sandboxes/governance/audit/ --- The sandbox daemon records a structured audit event for every policy decision @@ -21,10 +23,11 @@ Docker doesn't collect or ingest audit data. Audit logging is active only while your organization enforces a centralized governance policy. The subscription alone doesn't produce records. If your -organization hasn't configured and enforced an [organization policy](org.md), -the daemon writes no audit logs. To confirm governance is active, run `sbx -policy ls` — the output begins with a `Policy rules` header listing a -`Governance Managed by ` line when an organization policy is in effect. +organization hasn't configured and enforced an +[organization policy](../access-controls/organization.md), the daemon writes no +audit logs. To confirm governance is active, run `sbx policy ls` — the output +begins with a `Policy rules` header listing a `Governance Managed by ` +line when an organization policy is in effect. Audit logging complements [monitoring](monitoring.md). Monitoring with `sbx policy ls` and `sbx policy log` is for live, interactive debugging. Audit diff --git a/content/manuals/ai/sandboxes/governance/monitoring.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md similarity index 85% rename from content/manuals/ai/sandboxes/governance/monitoring.md rename to content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md index f4c1291d0119..39d84890e15e 100644 --- a/content/manuals/ai/sandboxes/governance/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md @@ -1,8 +1,10 @@ --- title: Monitoring policies -weight: 25 +weight: 10 description: Inspect active policy rules and monitor sandbox network traffic with sbx policy ls and sbx policy log. keywords: docker sandboxes, policy monitoring, sbx policy ls, sbx policy log, network traffic, policy debugging +aliases: + - /ai/sandboxes/governance/monitoring/ --- `sbx policy ls` and `sbx policy log` give you a combined view of all active @@ -27,7 +29,7 @@ The columns are: - `POLICY`: the policy name. - `SOURCE`: where the policy came from. `local` means your local configuration — a preset or rules you added with `sbx policy`. `kit` means a - [kit](../customize/kits.md#control-network-access). `org` means your + [kit](../../customize/kits.md#control-network-access). `org` means your organization. - `APPLIES TO`: which sandboxes the policy applies to. `all` means the policy is global. `sandbox:` scopes it to a single sandbox; a profile name @@ -113,7 +115,7 @@ A writable workspace mount must be allowed by both a `filesystem:read` and a `filesystem:write` rule; a read-only mount needs only `filesystem:read`. The default local policy allows read and write access to all paths, shown as the two `default-fs-*` rules above. For the rule syntax and path patterns, see -[Policy concepts](concepts.md#filesystem-rules). +[Policy concepts](../concepts.md#filesystem-rules). ## Monitoring traffic @@ -135,13 +137,13 @@ my-sandbox network app.example.com browser-open The `PROXY` column shows how the request left the sandbox: -| Value | Description | -| ----- | ----------- | -| `forward` | Routed through the forward proxy. Supports [credential injection](../security/credentials.md). | -| `forward-bypass` | Routed through the forward proxy without credential injection. | -| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. | -| `network` | Non-HTTP traffic (raw TCP, UDP, ICMP). TCP can be allowed with a policy rule; UDP and ICMP are always blocked. | -| `browser-open` | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL. | +| Value | Description | +| ---------------- | -------------------------------------------------------------------------------------------------------------- | +| `forward` | Routed through the forward proxy. Supports [credential injection](../../security/credentials.md). | +| `forward-bypass` | Routed through the forward proxy without credential injection. | +| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. | +| `network` | Non-HTTP traffic (raw TCP, UDP, ICMP). TCP can be allowed with a policy rule; UDP and ICMP are always blocked. | +| `browser-open` | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL. | The `RULE` column identifies the policy rule that matched the request. The `REASON` column includes extra context when the daemon records one. diff --git a/content/manuals/ai/sandboxes/governance/sign-in-enforcement.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md similarity index 95% rename from content/manuals/ai/sandboxes/governance/sign-in-enforcement.md rename to content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md index 74c72d44c008..ea955a9d6d85 100644 --- a/content/manuals/ai/sandboxes/governance/sign-in-enforcement.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md @@ -1,9 +1,11 @@ --- title: Sign-in enforcement linkTitle: Sign-in enforcement -weight: 22 +weight: 30 description: Require Docker Sandboxes users to sign in as members of your organization, enforced through endpoint management. keywords: docker sandboxes, sign-in enforcement, organization enforcement, sbx login, MDM, configuration profile, registry key, allowedOrgs +aliases: + - /ai/sandboxes/governance/sign-in-enforcement/ --- Sign-in enforcement restricts Docker Sandboxes to users who are members of @@ -13,8 +15,9 @@ membership after the user authenticates. If the check fails, credentials are immediately revoked and the user can't run sandboxes. Without this enforcement, a developer can sign in with a personal account and -bypass organization [governance policies](org.md). Sign-in enforcement closes -that gap at the endpoint, where users can't override it. +bypass organization [governance policies](../access-controls/organization.md). +Sign-in enforcement closes that gap at the endpoint, where users can't override +it. > [!NOTE] > Sign-in enforcement is part of Docker's AI Governance offering. @@ -261,9 +264,9 @@ For access, contact ACME IT Security: ## Related pages -- [Organization policy](org.md): centrally manage sandbox network and - filesystem rules -- [Governance overview](_index.md): how local and organization governance fit +- [Organization policies](../access-controls/organization.md): centrally manage + sandbox network and filesystem rules from the Docker Admin Console +- [Governance overview](../_index.md): how local and organization governance fit together - [Enforce sign-in for Docker Desktop](/manuals/enterprise/security/enforce-sign-in/_index.md): the equivalent control for Docker Desktop diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md new file mode 100644 index 000000000000..25c13d38bd80 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -0,0 +1,13 @@ +--- +title: Reference +weight: 30 +description: Reference material for Docker AI Governance policy APIs and policy syntax. +keywords: docker sandboxes, governance reference, governance API, policy reference +--- + +Use reference material when you need API details or exact policy syntax. + +- [Policy concepts](../concepts.md): resource model, rule syntax, policy + evaluation, and precedence. +- [AI Governance API](api.md): HTTP API reference for network and filesystem + organization policies. diff --git a/content/manuals/ai/sandboxes/governance/api.md b/content/manuals/ai/sandboxes/governance/reference/api.md similarity index 95% rename from content/manuals/ai/sandboxes/governance/api.md rename to content/manuals/ai/sandboxes/governance/reference/api.md index dcbb778b8aee..5618b5f3b4dd 100644 --- a/content/manuals/ai/sandboxes/governance/api.md +++ b/content/manuals/ai/sandboxes/governance/reference/api.md @@ -2,7 +2,7 @@ title: AI Governance API linkTitle: API reference description: Programmatic management of Docker AI Governance policies and rules via HTTP+JSON. -weight: 30 +weight: 10 build: render: never sidebar: diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 7be080191a21..c5cc71da9d91 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -44,7 +44,7 @@ data. Create fresh sandboxes afterwards. ## Agent can't install packages or reach an API -Sandboxes use a [deny-by-default network policy](governance/local.md). +Sandboxes use a [deny-by-default network policy](governance/access-controls/local.md). If the agent fails to install packages or call an external API, the target domain is likely not in the allow list. Check which requests are being blocked: @@ -66,7 +66,7 @@ $ sbx policy allow network "**" If `sbx policy allow` doesn't unblock the request, your organization may manage sandbox policies centrally and take precedence over local rules. See -[Organization governance](governance/org.md). +[Organization governance](governance/access-controls/organization.md). ## Kit fails to install: source not in allowlist @@ -141,7 +141,7 @@ If credentials are configured correctly but API calls still fail, check the `transparent` proxy don't get credential injection. This can happen when a client inside the sandbox (such as a process in a Docker container) isn't configured to use the forward proxy. See -[Monitoring network activity](governance/monitoring.md) +[Monitoring network activity](governance/monitor-and-enforce/monitoring.md) for details. ## API calls fail with a certificate error diff --git a/content/manuals/subscription/plans/ai-governance.md b/content/manuals/subscription/plans/ai-governance.md index 80149e061901..c569fd3b656b 100644 --- a/content/manuals/subscription/plans/ai-governance.md +++ b/content/manuals/subscription/plans/ai-governance.md @@ -20,7 +20,7 @@ aliases: ## Usage -AI Governance lets organization owners enforce [governance policies](/manuals/ai/sandboxes/governance/org.md) to license-holding members. Organization policies override the local policies of a license-holding member. +AI Governance lets organization owners enforce [governance policies](/manuals/ai/sandboxes/governance/access-controls/organization.md) to license-holding members. Organization policies override the local policies of a license-holding member. You can [assign AI Governance licenses](/manuals/admin/organization/manage/manage-licenses.md) to any organization member, even if they don't occupy a Docker Team or Docker Business seat. For best practice, review available licenses as you add new members since members without an AI Governance license can still use Docker AI products. From 490624dffc8edab84b4405c891877007668863ee Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 10:02:24 +0000 Subject: [PATCH 03/35] docs: slim organization governance page The organization policy page repeated policy evaluation and access-rule details covered by the concepts and access-control pages. Trim it to admin-console management, policy type selection, team scoping, and propagation troubleshooting, and move filesystem mount troubleshooting to the filesystem access page. --- .../governance/access-controls/filesystem.md | 8 ++ .../access-controls/organization.md | 130 +++--------------- 2 files changed, 29 insertions(+), 109 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md index 05076b1ef587..4830cbec537a 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md @@ -42,3 +42,11 @@ scoping, see [Organization policies](organization.md). Filesystem policy is checked when a workspace is mounted, which happens when a sandbox is created. To apply a filesystem policy change to a running workflow, remove the sandbox and create a new one. + +## Troubleshooting + +### Sandbox cannot mount workspace + +If a sandbox fails to mount with a `mount policy denied` error, verify that the +filesystem allow rule in the Admin Console uses `**` rather than `*`. A single +`*` doesn't match across directory separators. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md index e48d7360da82..2d05fcee2417 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -54,47 +54,27 @@ To create a policy: 1. Set the **Scope** to **Organization** or **Teams**. If you select **Teams**, choose the teams the policy applies to. See [Scope policies to teams](#scope-policies-to-teams). -1. Select **Add rule** to add each rule. For rule syntax, see - [Policy concepts](../concepts.md#rule-syntax). +1. Select **Add rule** to add each rule. For rule syntax, use the relevant + access-control page in [Choose a policy type](#choose-a-policy-type). Existing policies are listed with their name, scope, rule count, and last update. Use the action menu (⋮) to edit or delete a policy. -## Network policies +## Choose a policy type -### Configuring org-level network rules +Organization policies are managed by access surface. Use the access-control +pages for syntax, examples, and enforcement details: -A network rule takes a network target and an action (allow or deny). You can -add multiple entries at once, one per line. +- [Network access rules](network.md): control outbound network access from + sandboxes. +- [Filesystem access rules](filesystem.md): control which host paths sandboxes + can mount as workspaces. +- [MCP tool access](mcp.md): control MCP server registration, tool calls, + resources, prompts, and approval gates with Cedar policy. -For the full syntax reference (exact hostnames, wildcard subdomains, port -suffixes, and CIDR ranges), see [Network access rules](network.md). - -When organization governance is active, local network rules are not evaluated. -The organization policy is the only policy in effect. `sbx policy ls` hides -these inactive local rules by default. See -[Monitoring](../monitor-and-enforce/monitoring.md#showing-inactive-rules) for -how to list them and read the rule view. - -## Filesystem policies - -Filesystem policies control which host paths a sandbox can mount as -workspaces. By default, sandboxes can mount any directory the user has -access to. - -Admins can restrict which paths are mountable with filesystem allow and deny -rules. Each rule takes a path pattern and an action (allow or deny). - -For path pattern syntax and how read and write access combine to allow a -mount, see [Filesystem access rules](filesystem.md). - -## MCP policies - -MCP policies control sandbox activity that goes through MCP servers, such as -server registration, tool calls, resource reads, prompts, and gateway -meta-tools. Unlike network and filesystem policies, MCP policies are written in -Cedar using the `MCP` namespace. For policy patterns and examples, see -[MCP tool access](mcp.md). +When organization governance is active, local and kit-defined rules are not +evaluated. To see which rules are active on a developer machine, use +[Monitoring policies](../monitor-and-enforce/monitoring.md). ## Scope policies to teams @@ -123,78 +103,16 @@ in one of two ways: Because policies apply by team, a user's policies update automatically as their team membership changes, including changes synced from your IdP. -### How org-wide and team-scoped policies combine +### How scoped policies combine A user is governed by all of their -[effective policies](../concepts.md#policy-scope) at once — every org-wide -policy, plus the team-scoped policies for the teams they belong to. The rules -combine into a single evaluation in which deny always wins, so a team-scoped -policy can grant access on top of the org-wide policies but can't loosen a -restriction they impose. For the full evaluation model, see -[Rule evaluation](../concepts.md#rule-evaluation). - -This makes org-wide policies the natural home for guardrails that must hold -everywhere. For example, an org-wide policy can deny a category of domains for -all members, while a team-scoped policy grants a research team access to extra -package mirrors. Research-team members get the extra access, but the org-wide -deny still applies. - -In practice, three patterns cover most layering: - -- Deny by default: leave a domain out of every allow rule to keep it blocked. -- Allow when needed: add a team-scoped allow to grant an exception. -- Explicit deny: deny a domain outright when no team should ever reach it. - -The examples that follow show each pattern. - -### Grant one team access to a blocked domain +[effective policies](../concepts.md#policy-scope): every org-wide policy, plus +the team-scoped policies for the teams they belong to. Use org-wide policies +for guardrails that must apply everywhere, and team-scoped policies for access +that only some teams need. -Because access is [denied by default](../concepts.md#rule-evaluation), you don't -need an explicit deny to keep a domain off-limits. Leaving it out of every allow -rule is enough. To give a single team access to a domain no one else can reach: - -1. Don't add an allow rule for the domain at the organization level. Default - deny keeps it blocked for everyone. -1. Create a team-scoped policy that allows the domain, and scope it to that team. - -Only members of that team can reach the domain. Everyone else is still blocked -by default. - -### Block a domain everywhere as a guardrail - -Use an explicit org-wide deny when a domain must be off-limits to everyone, -including teams that have broad allow rules. Because deny wins, an org-wide deny -on `**.example.com` blocks `example.com` and every subdomain for all members, -and no team-scoped allow can grant access to it. - -Reserve explicit deny rules for domains you want to block outright. For -everything else, rely on default deny and add allow rules only where access is -needed. - -### An exact deny doesn't cover subdomains - -A deny rule matches only the hostnames its pattern matches. A deny on the exact -hostname `example.com` doesn't match `api.example.com`, so a team-scoped allow -on `api.example.com` still grants that team access. The org-wide deny and the -team allow apply to different hostnames, so they never conflict. - -To block a domain and all its subdomains, deny `**.example.com` instead. With -that pattern, deny wins over any team-scoped allow on a subdomain. See -[Hostname patterns](../concepts.md#network-rules) for how exact hostnames and -wildcards match. - -## Precedence - -When organization governance is active, local rules are not evaluated. Only -organization rules set in the Admin Console determine what is allowed or denied, -and they can't be supplemented or overridden from a developer's machine. The -same applies to filesystem policies: organization rules replace local behavior -entirely. For how a user's organization policies are evaluated together, see -[Policy concepts](../concepts.md#rule-evaluation). - -To unblock a domain when organization governance is active, update the rule in -the Admin Console or via the [API](/reference/api/ai-governance/). Without -organization governance, remove the local rule with `sbx policy rm`. +For precedence between local and organization policies, and for how allow and +deny rules combine, see [Policy concepts](../concepts.md). ## Troubleshooting @@ -226,9 +144,3 @@ Network policy and filesystem policy differ in when a change takes effect: To apply a filesystem policy change immediately, remove the running sandbox and create a new one. - -### Sandbox cannot mount workspace - -If a sandbox fails to mount with a `mount policy denied` error, verify that -the filesystem allow rule in the Admin Console uses `**` rather than `*`. A -single `*` doesn't match across directory separators. From 41076716fec4aeb3853a046fa77a590ee7a81678 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 10:09:26 +0000 Subject: [PATCH 04/35] docs: add mcp policy reference MCP governance policy docs needed a Docker-specific reference for the Cedar namespace surface without teaching the full Cedar language. Add an MCP policy reference page and link it from the governance reference, concepts, and MCP access-control pages. --- .../governance/access-controls/mcp.md | 8 +- .../ai/sandboxes/governance/concepts.md | 3 + .../sandboxes/governance/reference/_index.md | 2 + .../governance/reference/mcp-policy.md | 157 ++++++++++++++++++ 4 files changed, 168 insertions(+), 2 deletions(-) create mode 100644 content/manuals/ai/sandboxes/governance/reference/mcp-policy.md diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md index 4e2744f775ef..44280f19c4de 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md @@ -14,8 +14,10 @@ Unlike [network access rules](network.md) and [filesystem access rules](filesystem.md), MCP access rules are organization policies written in Cedar. Docker defines the `MCP` namespace, including the actions, resource types, attributes, and approval behavior that policies can -match. For the full Cedar language, see the -[Cedar documentation](https://docs.cedarpolicy.com/). +match. For Docker's MCP policy actions, resources, attributes, context fields, +and approval behavior, see the +[MCP policy reference](../reference/mcp-policy.md). For Cedar syntax and +language semantics, see the [Cedar documentation](https://docs.cedarpolicy.com/). ## How MCP policy works @@ -123,6 +125,8 @@ server command and argument attributes don't apply to remote servers. ## Next steps - Use [Policy concepts](../concepts.md#mcp-policies) for the MCP policy model. +- Use the [MCP policy reference](../reference/mcp-policy.md) for exact action, + resource, attribute, context, and approval behavior. - Use [Organization policies](organization.md) to manage policy scope. - Use [Audit logs](../monitor-and-enforce/audit.md) to collect policy decision records. diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index f6ef9449bd68..d68e1292a203 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -147,6 +147,9 @@ Resources are referenced with `MCP` entity types, such as `MCP::Server`, a tool policy can match the server that exposes the tool, the tool's bare name, and server-declared tool annotations such as `readOnly` or `destructive`. +For exact action, resource, context, and approval behavior, see the +[MCP policy reference](reference/mcp-policy.md). + The following policy allows tools that the server declares read-only, and requires approval before a non-read-only tool can run: diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md index 25c13d38bd80..56e0eb28c513 100644 --- a/content/manuals/ai/sandboxes/governance/reference/_index.md +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -11,3 +11,5 @@ Use reference material when you need API details or exact policy syntax. evaluation, and precedence. - [AI Governance API](api.md): HTTP API reference for network and filesystem organization policies. +- [MCP policy reference](mcp-policy.md): Docker MCP policy actions, resources, + attributes, context fields, and approval behavior. diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md new file mode 100644 index 000000000000..d3606ca0a180 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md @@ -0,0 +1,157 @@ +--- +title: MCP policy reference +linkTitle: MCP policy +weight: 20 +description: Reference for Docker MCP policy actions, resources, attributes, context fields, and approval behavior. +keywords: docker sandboxes, MCP policy, Cedar policy, MCP actions, MCP resources, requireApproval, AI Governance +--- + +MCP policies are organization policies written in Cedar using Docker's `MCP` +namespace. This reference defines the Docker-specific policy surface for Model +Context Protocol (MCP) activity made available to sandboxes through Docker's +MCP gateway. + +Use this reference with [Control MCP tool access](../access-controls/mcp.md) +for common policy patterns. For the Cedar language, see the +[Cedar documentation](https://docs.cedarpolicy.com/). + +## Evaluation model + +Cedar evaluates MCP requests against a principal, action, resource, and context. +For Docker MCP policies, policy scope supplies the principal. Write policies +against the action, resource, and context. Clauses that reference principal +attributes, such as `principal in ...`, `principal.role`, or +`principal.tenant`, don't match. + +Governed MCP activity is default deny. A request is blocked unless a matching +`permit` allows it. A matching `forbid` overrides any `permit`, including a +permit annotated with `@requireApproval`. + +An actionless `permit` covers every MCP action: + +```cedar +permit (principal, action, resource); +``` + +## Actions + +| Action | Governs | Notes | +| ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `register` | MCP server registration | Remote server registration needs an explicit `permit`. Use `forbid` rules to block local server registration patterns. | +| `invokeTool` | MCP tool calls | Most tool access policies target this action. | +| `invokePrimordial` | Gateway meta-tool calls | Applies to gateway-injected meta-tools such as `mcp-add` and `code-mode`. | +| `readResource` | MCP resource reads | Cedar policy is enforced inside the sandbox. Remote server reads aren't evaluated by Cedar policy. | +| `getPrompt` | MCP prompt retrieval | Remote prompt access is governed by gateway config, not Cedar policy. | +| `listTools` | MCP tool listing | Not Cedar-gated. Tool listings can include tools denied at invocation. | +| `listResources` | MCP resource listing | Not Cedar-gated. | +| `subscribeResource` | MCP resource subscription | Not Cedar-gated. | + +## Resources + +Match resources with the MCP entity type and attributes for the request. + +| Entity | Match with | Notes | +| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `MCP::Server` | Registered server name | The server URL is the `resource.identityURL` attribute, not the entity ID. | +| `MCP::Tool` | Bare tool name | Use `resource.name`. Display prefixes aren't included. A bare-name match applies to every server exposing a tool with that name. | +| `MCP::Resource` | Resource URI | Use `resource.uri`. | +| `MCP::Prompt` | Prompt name | Use `resource.name`. | +| `MCP::Primordial` | Gateway meta-tool name | Match a specific primordial with an entity reference. | + +Examples: + +```cedar +resource in MCP::Server::"notion" +resource.name == "move_file" +resource.uri like "*/docs/*" +resource in MCP::Primordial::"code-mode" +``` + +## Resource attributes + +Tool annotation attributes are server-declared and advisory. + +| Attribute | Applies to | Notes | +| -------------------------- | ------------------------- | ------------------------------------------------------------------------------- | +| `resource.name` | Tools and prompts | For tools, this is the bare tool name, not a display-prefixed name. | +| `resource.uri` | Resources | Use with string operators such as `like`. | +| `resource.readOnly` | Tools | Defaults to `false` when a tool doesn't declare it. | +| `resource.destructive` | Tools | Defaults to `true` when a tool doesn't declare it. | +| `resource.idempotent` | Tools | Server-declared tool annotation. | +| `resource.openWorld` | Tools | Server-declared tool annotation. | +| `resource.type` | Server registration | Use for remote server registration rules. | +| `resource.identityURL` | Server registration | The server URL. Use for remote server registration rules. | +| `resource.requiresOAuth` | Server registration | Use for remote server registration rules. | +| `resource.requiresNetwork` | Server registration | Use for remote server registration rules. | +| `resource.command` | Local server registration | Local stdio server command. Remote servers don't provide this value. | +| `resource.args` | Local server registration | Local stdio server arguments. This is a set, so `.contains()` can match values. | + +Use `like` for string attributes. In Cedar, `like` uses `*` as its wildcard, +matches the full string, treats `?` as a literal character, and treats `\*` as +a literal asterisk. + +Use `.contains()` only on set attributes, such as `resource.args`. On string +attributes, use `like`. + +## Context fields + +| Field | Notes | +| ---------------------- | ---------------------------------------------------------------------------------------------- | +| `context.request_time` | Bound at each enforcement point. Use it for time-window rules. | +| `context.args` | Tool-call arguments. Bound inside the sandbox. Gateway enforcement doesn't receive this field. | + +Guard tool-call argument rules with `context has args` and a field check: + +```cedar +permit (principal, action == MCP::Action::"invokeTool", resource) +when { + resource.name == "approve_expense" && + context has args && + context.args has amount && + context.args.amount <= 500 +}; +``` + +A `permit` gated on missing arguments doesn't match, so the request falls to +default deny. A `forbid` gated on missing arguments doesn't match, so it +doesn't block the request. + +## Approval annotation + +Use `@requireApproval("reason")` on a `permit` statement to require user +approval before a matching request runs: + +```cedar +@requireApproval("write tool call") +permit (principal, action == MCP::Action::"invokeTool", resource) +when { resource.readOnly == false }; +``` + +When a request matches the annotated `permit` and no `forbid` overrides it, the +policy engine returns an approval-required outcome. The annotation string is +shown as the approval reason. + +Approval requires a client session that can present an MCP elicitation request +to the user. If the request can't be presented for approval, the request is +denied. Approval is an in-session confirmation, not an out-of-band approval +workflow. + +Only the exact annotation name `@requireApproval` applies approval behavior. +Other annotation names, such as `@requireConsent` or `@requireConfirmation`, +don't require approval. + +## Limitations + +- Tool and resource listing actions aren't Cedar-gated. Listings can include + entries that a policy denies when the sandbox tries to use them. +- `readResource` is evaluated by Cedar policy inside the sandbox, not for + remote server reads. +- `getPrompt` for remote servers is governed by gateway config, not Cedar + policy. +- Tool-call argument rules using `context.args` apply inside the sandbox only. +- Server command and argument rules using `resource.command` or `resource.args` + apply to local stdio servers only. +- Principal-based rules don't take effect. Use organization and team policy + scope to target users. +- Server groups and tool categories aren't supported in MCP policy. Reference + servers and tools individually. From b4d2ef41e8a120ed17de5eb6f8185ba0b4fcf0d5 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 10:21:34 +0000 Subject: [PATCH 05/35] docs: align mcp policy reference with gateway source The MCP policy reference included stale behavior from the original runbook for context args, resource reads, prompt access, and tool category/default semantics. Update the reference against docker/mcp-gateway-enterprise source to document current Cedar actions, attributes, context fields, and gateway limitations. --- .../governance/reference/mcp-policy.md | 84 ++++++++++--------- 1 file changed, 44 insertions(+), 40 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md index d3606ca0a180..4165089955fc 100644 --- a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md +++ b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md @@ -27,7 +27,7 @@ Governed MCP activity is default deny. A request is blocked unless a matching `permit` allows it. A matching `forbid` overrides any `permit`, including a permit annotated with `@requireApproval`. -An actionless `permit` covers every MCP action: +An actionless `permit` matches every MCP action that reaches Cedar evaluation: ```cedar permit (principal, action, resource); @@ -35,16 +35,16 @@ permit (principal, action, resource); ## Actions -| Action | Governs | Notes | -| ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `register` | MCP server registration | Remote server registration needs an explicit `permit`. Use `forbid` rules to block local server registration patterns. | -| `invokeTool` | MCP tool calls | Most tool access policies target this action. | -| `invokePrimordial` | Gateway meta-tool calls | Applies to gateway-injected meta-tools such as `mcp-add` and `code-mode`. | -| `readResource` | MCP resource reads | Cedar policy is enforced inside the sandbox. Remote server reads aren't evaluated by Cedar policy. | -| `getPrompt` | MCP prompt retrieval | Remote prompt access is governed by gateway config, not Cedar policy. | -| `listTools` | MCP tool listing | Not Cedar-gated. Tool listings can include tools denied at invocation. | -| `listResources` | MCP resource listing | Not Cedar-gated. | -| `subscribeResource` | MCP resource subscription | Not Cedar-gated. | +| Action | Governs | Notes | +| ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------- | +| `register` | MCP server registration | Remote server registration needs an explicit `permit`. Use server attributes to scope registration. | +| `invokeTool` | MCP tool calls | Most tool access policies target this action. | +| `invokePrimordial` | Gateway meta-tool calls | Applies to gateway-injected meta-tools such as `mcp-add` and `code-mode`. | +| `readResource` | MCP resource reads | Rules match `MCP::Resource` and `resource.uri`. | +| `getPrompt` | MCP prompt retrieval | Rules match `MCP::Prompt` and `resource.name`. | +| `listTools` | MCP tool listing | Defined in the schema but not Cedar-gated. Tool listings can include tools denied at invocation. | +| `listResources` | MCP resource listing | Defined in the schema but not Cedar-gated. Resource listings can include resources denied by policy. | +| `subscribeResource` | MCP resource subscription | Defined in the schema but not Cedar-gated. | ## Resources @@ -52,7 +52,7 @@ Match resources with the MCP entity type and attributes for the request. | Entity | Match with | Notes | | ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `MCP::Server` | Registered server name | The server URL is the `resource.identityURL` attribute, not the entity ID. | +| `MCP::Server` | Registered server name | The server URL or source is the `resource.identityURL` attribute, not the entity ID. | | `MCP::Tool` | Bare tool name | Use `resource.name`. Display prefixes aren't included. A bare-name match applies to every server exposing a tool with that name. | | `MCP::Resource` | Resource URI | Use `resource.uri`. | | `MCP::Prompt` | Prompt name | Use `resource.name`. | @@ -69,22 +69,24 @@ resource in MCP::Primordial::"code-mode" ## Resource attributes -Tool annotation attributes are server-declared and advisory. - -| Attribute | Applies to | Notes | -| -------------------------- | ------------------------- | ------------------------------------------------------------------------------- | -| `resource.name` | Tools and prompts | For tools, this is the bare tool name, not a display-prefixed name. | -| `resource.uri` | Resources | Use with string operators such as `like`. | -| `resource.readOnly` | Tools | Defaults to `false` when a tool doesn't declare it. | -| `resource.destructive` | Tools | Defaults to `true` when a tool doesn't declare it. | -| `resource.idempotent` | Tools | Server-declared tool annotation. | -| `resource.openWorld` | Tools | Server-declared tool annotation. | -| `resource.type` | Server registration | Use for remote server registration rules. | -| `resource.identityURL` | Server registration | The server URL. Use for remote server registration rules. | -| `resource.requiresOAuth` | Server registration | Use for remote server registration rules. | -| `resource.requiresNetwork` | Server registration | Use for remote server registration rules. | -| `resource.command` | Local server registration | Local stdio server command. Remote servers don't provide this value. | -| `resource.args` | Local server registration | Local stdio server arguments. This is a set, so `.contains()` can match values. | +Tool annotation attributes come from MCP tool annotations or catalog metadata +and are advisory. + +| Attribute | Applies to | Notes | +| -------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------- | +| `resource.name` | Tools and prompts | For tools, this is the bare tool name, not a display-prefixed name. | +| `resource.uri` | Resources | Use with string operators such as `like`. | +| `resource.readOnly` | Tools | Defaults to `false` when a tool doesn't declare it. | +| `resource.destructive` | Tools | Defaults to `true` when a tool doesn't declare it. | +| `resource.idempotent` | Tools | Defaults to `false` when a tool doesn't declare it. | +| `resource.openWorld` | Tools | Defaults to `true` when a tool doesn't declare it. | +| `resource.category` | Tools | Server or catalog category copied onto the tool resource. Tools don't self-declare categories. | +| `resource.type` | Servers | Use for server registration rules. | +| `resource.identityURL` | Servers | The server URL or source. Use for server registration rules. | +| `resource.requiresOAuth` | Servers | Use for server registration rules. | +| `resource.requiresNetwork` | Servers | Use for server registration rules. | +| `resource.command` | Local server registration | Local stdio server command. The MCP gateway sends an empty value. | +| `resource.args` | Local server registration | Local stdio server arguments. This is a set, so `.contains()` can match values. | Use `like` for string attributes. In Cedar, `like` uses `*` as its wildcard, matches the full string, treats `?` as a literal character, and treats `\*` as @@ -95,10 +97,11 @@ attributes, use `like`. ## Context fields -| Field | Notes | -| ---------------------- | ---------------------------------------------------------------------------------------------- | -| `context.request_time` | Bound at each enforcement point. Use it for time-window rules. | -| `context.args` | Tool-call arguments. Bound inside the sandbox. Gateway enforcement doesn't receive this field. | +| Field | Notes | +| ---------------------- | ------------------------------------------------------------------------------------------------- | +| `context.request_time` | Bound at each enforcement point. Use it for time-window rules. | +| `context.oauth_scopes` | OAuth scopes for the caller. Present as a set, even when empty. | +| `context.args` | Tool-call arguments for `invokeTool`. Present when arguments are available as a supported object. | Guard tool-call argument rules with `context has args` and a field check: @@ -116,6 +119,9 @@ A `permit` gated on missing arguments doesn't match, so the request falls to default deny. A `forbid` gated on missing arguments doesn't match, so it doesn't block the request. +Only object-shaped tool arguments are represented in `context.args`. +Unsupported, malformed, or too deeply nested arguments are omitted. + ## Approval annotation Use `@requireApproval("reason")` on a `permit` statement to require user @@ -144,14 +150,12 @@ don't require approval. - Tool and resource listing actions aren't Cedar-gated. Listings can include entries that a policy denies when the sandbox tries to use them. -- `readResource` is evaluated by Cedar policy inside the sandbox, not for - remote server reads. -- `getPrompt` for remote servers is governed by gateway config, not Cedar - policy. -- Tool-call argument rules using `context.args` apply inside the sandbox only. - Server command and argument rules using `resource.command` or `resource.args` - apply to local stdio servers only. + apply where local stdio server details are available. The MCP gateway sends + empty values for those attributes. - Principal-based rules don't take effect. Use organization and team policy scope to target users. -- Server groups and tool categories aren't supported in MCP policy. Reference - servers and tools individually. +- Server groups aren't supported in MCP policy. Reference servers individually. +- Tool categories aren't self-declared by MCP tools. When available, + `resource.category` is server or catalog metadata copied onto the tool + resource. From 433789f8296266cdadef5072a6dea78c2648754a Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:04:09 +0000 Subject: [PATCH 06/35] docs: tidy sandbox governance IA and prose The sandbox governance docs needed a final prose and sidebar-ordering pass after adding MCP policy coverage. Normalize governance subtree weights to 10-point increments, add missing reference links and API keywords, and smooth wording in the new governance pages. --- content/manuals/ai/sandboxes/governance/_index.md | 2 ++ .../ai/sandboxes/governance/access-controls/_index.md | 7 +++---- .../ai/sandboxes/governance/access-controls/mcp.md | 8 ++++---- .../sandboxes/governance/access-controls/organization.md | 4 ++-- content/manuals/ai/sandboxes/governance/concepts.md | 8 ++++---- .../ai/sandboxes/governance/monitor-and-enforce/_index.md | 2 +- .../manuals/ai/sandboxes/governance/reference/_index.md | 2 +- content/manuals/ai/sandboxes/governance/reference/api.md | 1 + 8 files changed, 18 insertions(+), 16 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 2f17a10d78a5..e9046c5b85ed 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -66,3 +66,5 @@ MCP policy basics, evaluation, and precedence. - [AI Governance API](/reference/api/ai-governance/): manage network and filesystem org policies programmatically. +- [MCP policy reference](reference/mcp-policy.md): look up Docker MCP policy + actions, resources, attributes, context fields, and approval behavior. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/_index.md b/content/manuals/ai/sandboxes/governance/access-controls/_index.md index 922e84e2de63..badbf03971f2 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/_index.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/_index.md @@ -1,13 +1,12 @@ --- title: Access controls -weight: 10 +weight: 20 description: Configure local and organization controls for sandbox network, filesystem, and MCP access. keywords: docker sandboxes, access controls, governance, network access, filesystem access, MCP access --- -Access controls define what sandboxes can reach or use. Use these pages to -configure policies by scope, then drill into the access surface you want to -govern. +Access controls define what sandboxes can reach or use. Choose a policy scope, +then choose the access surface you want to govern. ## Policy scope diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md index 44280f19c4de..e470c61d23da 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md @@ -14,10 +14,10 @@ Unlike [network access rules](network.md) and [filesystem access rules](filesystem.md), MCP access rules are organization policies written in Cedar. Docker defines the `MCP` namespace, including the actions, resource types, attributes, and approval behavior that policies can -match. For Docker's MCP policy actions, resources, attributes, context fields, -and approval behavior, see the -[MCP policy reference](../reference/mcp-policy.md). For Cedar syntax and -language semantics, see the [Cedar documentation](https://docs.cedarpolicy.com/). +match. For Docker's MCP policy actions, resources, attributes, and context +fields, see the [MCP policy reference](../reference/mcp-policy.md). For Cedar +syntax and language semantics, see the +[Cedar documentation](https://docs.cedarpolicy.com/). ## How MCP policy works diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md index 2d05fcee2417..b919fec91df2 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -11,7 +11,7 @@ aliases: [Local policies](local.md) give individual developers control over what their sandboxes can access. Organization policy moves that control to the admin level: -rules defined in **Admin Console** apply to sandboxes across the organization, +rules defined in the Admin Console apply to sandboxes across the organization, either to every member or to specific teams. When organization governance is active, it replaces local `sbx policy` rules entirely — local rules are no longer evaluated and can't be used to supplement or override the organization @@ -41,7 +41,7 @@ of [Docker Home](https://app.docker.com). Network and filesystem policies are managed separately, under **Network access** and **Filesystem access**. The steps in this section cover network and filesystem policies. MCP policies -use Cedar rather than rule rows. For MCP examples, see +use Cedar rather than the network and filesystem rule form. For MCP examples, see [MCP tool access](mcp.md). To create a policy: diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index d68e1292a203..3a0509153ec3 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -1,6 +1,6 @@ --- title: Policy concepts -weight: 5 +weight: 10 description: The resource model, rule syntax, and evaluation logic behind Docker sandbox governance. keywords: docker sandboxes, policy concepts, rule syntax, network rules, filesystem rules, mcp policy, cedar policy, precedence, rule evaluation --- @@ -126,9 +126,9 @@ Cedar using the `MCP` namespace, rather than the network and filesystem rule format. Cedar evaluates each MCP request against a principal, action, resource, and -context. Admins write rules for the action, resource, and context. Policy scope -supplies the principal, so a rule that tries to match a specific user, team, -tenant, or role in the principal doesn't match. +context. Admins write policy statements for the action, resource, and context. +Policy scope supplies the principal, so a statement that tries to match a +specific user, team, tenant, or role in the principal doesn't match. Governed MCP actions are default deny: an MCP request is blocked unless a matching `permit` allows it. A matching `forbid` overrides any `permit`, diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md index e8a66facbc6f..6db42c60ca4c 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md @@ -1,6 +1,6 @@ --- title: Monitor and enforce -weight: 20 +weight: 30 description: Inspect active sandbox governance rules, collect audit records, and enforce organization sign-in. keywords: docker sandboxes, governance monitoring, audit logs, sign-in enforcement, policy enforcement --- diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md index 56e0eb28c513..5b4ae1b0d523 100644 --- a/content/manuals/ai/sandboxes/governance/reference/_index.md +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -1,6 +1,6 @@ --- title: Reference -weight: 30 +weight: 40 description: Reference material for Docker AI Governance policy APIs and policy syntax. keywords: docker sandboxes, governance reference, governance API, policy reference --- diff --git a/content/manuals/ai/sandboxes/governance/reference/api.md b/content/manuals/ai/sandboxes/governance/reference/api.md index 5618b5f3b4dd..36e6297f165b 100644 --- a/content/manuals/ai/sandboxes/governance/reference/api.md +++ b/content/manuals/ai/sandboxes/governance/reference/api.md @@ -2,6 +2,7 @@ title: AI Governance API linkTitle: API reference description: Programmatic management of Docker AI Governance policies and rules via HTTP+JSON. +keywords: docker sandboxes, AI Governance API, governance API, policy API, organization policies weight: 10 build: render: never From 73a78e0d43cee2248429d568eaa1f142c72d961e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:11:03 +0000 Subject: [PATCH 07/35] docs: fix sandbox governance reference link --- content/manuals/ai/sandboxes/governance/reference/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md index 5b4ae1b0d523..819feab16011 100644 --- a/content/manuals/ai/sandboxes/governance/reference/_index.md +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -9,7 +9,7 @@ Use reference material when you need API details or exact policy syntax. - [Policy concepts](../concepts.md): resource model, rule syntax, policy evaluation, and precedence. -- [AI Governance API](api.md): HTTP API reference for network and filesystem - organization policies. +- [AI Governance API](/reference/api/ai-governance/): HTTP API reference for + network and filesystem organization policies. - [MCP policy reference](mcp-policy.md): Docker MCP policy actions, resources, attributes, context fields, and approval behavior. From 8f760ab015e2887082178c87fc076d9a60443f7c Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:16:32 +0000 Subject: [PATCH 08/35] docs: refine sandbox governance cross-links --- .../admin/organization/manage/manage-licenses.md | 2 +- .../ai/sandboxes/customize/kit-examples.md | 2 +- content/manuals/ai/sandboxes/faq.md | 7 +++---- content/manuals/ai/sandboxes/get-started.md | 16 ++++++++-------- content/manuals/ai/sandboxes/troubleshooting.md | 5 +++-- .../manuals/subscription/plans/ai-governance.md | 2 +- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/content/manuals/admin/organization/manage/manage-licenses.md b/content/manuals/admin/organization/manage/manage-licenses.md index 5b0f2c035e7a..aab4a0e776e0 100644 --- a/content/manuals/admin/organization/manage/manage-licenses.md +++ b/content/manuals/admin/organization/manage/manage-licenses.md @@ -44,5 +44,5 @@ See these docs to explore Docker Core add-ons, or products that need licenses: - [Docker plans](/manuals/subscription/plans/_index.md) to learn about different add-ons - [Manage seats](/manuals/admin/organization/manage/manage-seats.md) to add more seats to your Docker Core subscription -- [AI Governance](/manuals/ai/sandboxes/governance/access-controls/organization.md) to set up organization policies for your organization members +- [AI Governance plan](/manuals/subscription/plans/ai-governance.md) to learn about AI Governance license usage and billing - [Docker Offload](/manuals/offload/about.md) to let your developers offload building and running containers to the cloud diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md index 72cb74da125c..0cec9987c798 100644 --- a/content/manuals/ai/sandboxes/customize/kit-examples.md +++ b/content/manuals/ai/sandboxes/customize/kit-examples.md @@ -77,7 +77,7 @@ Install steps run under `sh`, not bash, so bash-only builtins such as (`curl … | bash`) or wrap the step in `bash -c '…'` when you need them. Downloads are subject to the sandbox's -[deny-by-default network policy](../governance/access-controls/local.md). A domain that +[network access rules](../governance/access-controls/network.md). A domain that resolves from your host can still be blocked inside the sandbox — for example, `get.sdkman.io` returns a 403 until you allow it with `sbx policy allow network get.sdkman.io`. A tool may also need base diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 85db43615c8a..8e0de294359f 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -29,9 +29,8 @@ Signing in gives each sandbox a verified identity, which lets Docker: containers, install packages, and push code. Your Docker identity is the anchor. - **Enable team features.** Team-scale features like - [organization governance](governance/access-controls/organization.md), shared environments, and - audit logs need a concept of "who," and adding that later would be worse for - everyone. + [organization governance](governance/), shared environments, and audit logs + need a concept of "who," and adding that later would be worse for everyone. - **Authenticate against Docker infrastructure.** Sandboxes pull images, run daemons, and talk to Docker services. A Docker account authenticates those requests. @@ -45,7 +44,7 @@ rules apply to every sandbox in the organization. When organization governance is active, it replaces local rules set with `sbx policy` — local rules are no longer evaluated. -See [Organization governance](governance/access-controls/organization.md). This feature requires +See [Organization policies](governance/access-controls/organization.md). This feature requires a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to get started. diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 7875902f4515..e1723249f0f7 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -115,8 +115,9 @@ Use ↑/↓ to navigate, Enter to select, or press 1–3. **Balanced** is a good starting point — it permits traffic to common development services while blocking everything else. You can adjust individual -rules later. See [Policies](governance/access-controls/local.md) for a full description of each -option. +rules later. See +[default network presets](governance/access-controls/local.md#default-preset) +for a full description of each option. > [!NOTE] > See the [FAQ](faq.md) for details on why sign-in is required and what @@ -211,12 +212,11 @@ To allow a specific host: $ sbx policy allow network registry.npmjs.org ``` -With **Balanced**, common development services are allowed by default. With -**Locked Down**, everything is blocked until you allow it — including your -model provider's API. If the agent can't reach a service it needs, the network -policy is the first place to look. See -[Policies](governance/access-controls/local.md) for the full rule set and how -to customize it. +With **Locked Down**, even your model provider API is blocked unless you +explicitly allow it. With **Balanced**, common development services are +permitted by default. See +[local access rules](governance/access-controls/local.md) for the full rule set +and how to customize it. ## Clean up diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index c5cc71da9d91..112f5b596f3a 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -44,7 +44,8 @@ data. Create fresh sandboxes afterwards. ## Agent can't install packages or reach an API -Sandboxes use a [deny-by-default network policy](governance/access-controls/local.md). +Sandboxes use [network access rules](governance/access-controls/network.md) to +control outbound traffic. If the agent fails to install packages or call an external API, the target domain is likely not in the allow list. Check which requests are being blocked: @@ -66,7 +67,7 @@ $ sbx policy allow network "**" If `sbx policy allow` doesn't unblock the request, your organization may manage sandbox policies centrally and take precedence over local rules. See -[Organization governance](governance/access-controls/organization.md). +[Organization policies](governance/access-controls/organization.md). ## Kit fails to install: source not in allowlist diff --git a/content/manuals/subscription/plans/ai-governance.md b/content/manuals/subscription/plans/ai-governance.md index c569fd3b656b..4b28959aef2f 100644 --- a/content/manuals/subscription/plans/ai-governance.md +++ b/content/manuals/subscription/plans/ai-governance.md @@ -20,7 +20,7 @@ aliases: ## Usage -AI Governance lets organization owners enforce [governance policies](/manuals/ai/sandboxes/governance/access-controls/organization.md) to license-holding members. Organization policies override the local policies of a license-holding member. +AI Governance lets organization owners enforce [organization policies](/manuals/ai/sandboxes/governance/access-controls/organization.md) for license-holding members. Organization policies override a license-holding member's local policies. You can [assign AI Governance licenses](/manuals/admin/organization/manage/manage-licenses.md) to any organization member, even if they don't occupy a Docker Team or Docker Business seat. For best practice, review available licenses as you add new members since members without an AI Governance license can still use Docker AI products. From 154409ae779c30b4adfd6d9092dd2278f2f9709e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:44:50 +0000 Subject: [PATCH 09/35] docs: clarify sandbox governance terminology --- content/manuals/ai/sandboxes/get-started.md | 2 +- .../manuals/ai/sandboxes/governance/_index.md | 8 ++++---- .../governance/access-controls/_index.md | 12 +++++++----- .../governance/access-controls/filesystem.md | 4 ++-- .../governance/access-controls/local.md | 18 +++++++++--------- .../governance/access-controls/mcp.md | 10 +++++----- .../governance/access-controls/network.md | 12 ++++++------ .../governance/access-controls/organization.md | 4 ++-- .../governance/reference/mcp-policy.md | 4 ++-- 9 files changed, 38 insertions(+), 36 deletions(-) diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index e1723249f0f7..d133db7ef390 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -215,7 +215,7 @@ $ sbx policy allow network registry.npmjs.org With **Locked Down**, even your model provider API is blocked unless you explicitly allow it. With **Balanced**, common development services are permitted by default. See -[local access rules](governance/access-controls/local.md) for the full rule set +[local policy](governance/access-controls/local.md) for the full rule set and how to customize it. ## Clean up diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index e9046c5b85ed..bbedf37e9ef7 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -11,7 +11,7 @@ layers, and only one applies at a time: **Local policy** is configured per machine using the `sbx policy` CLI. It lets individual developers customize which domains their sandboxes can reach. -See [Local access rules](access-controls/local.md). +See [Local policy](access-controls/local.md). **Organization policy** is configured centrally in the Docker Admin Console. Network and filesystem policies can also be managed via the @@ -40,15 +40,15 @@ MCP policy basics, evaluation, and precedence. ### Access controls -- [Local access rules](access-controls/local.md): configure network rules on - your machine with the `sbx policy` CLI. +- [Local policy](access-controls/local.md): configure network rules on your + machine with the `sbx policy` CLI. - [Organization policies](access-controls/organization.md): centrally manage sandbox policies across your organization from the Admin Console. - [Network access rules](access-controls/network.md): control outbound network access from sandboxes. - [Filesystem access rules](access-controls/filesystem.md): control which host paths sandboxes can mount as workspaces. -- [MCP tool access](access-controls/mcp.md): control MCP server registration, +- [MCP access policies](access-controls/mcp.md): control MCP server registration, tool calls, resources, prompts, and approval gates. ### Monitor and enforce diff --git a/content/manuals/ai/sandboxes/governance/access-controls/_index.md b/content/manuals/ai/sandboxes/governance/access-controls/_index.md index badbf03971f2..2ad120c036d0 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/_index.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/_index.md @@ -5,13 +5,15 @@ description: Configure local and organization controls for sandbox network, file keywords: docker sandboxes, access controls, governance, network access, filesystem access, MCP access --- -Access controls define what sandboxes can reach or use. Choose a policy scope, -then choose the access surface you want to govern. +Access controls are expressed as policies. Local and organization pages +describe where policies apply. Network and filesystem pages describe the rules +inside those policies. MCP policies use Cedar statements instead of the network +and filesystem rule format. ## Policy scope -- [Local access rules](local.md): configure network rules on a developer - machine with the `sbx policy` CLI. +- [Local policy](local.md): configure network rules on a developer machine with + the `sbx policy` CLI. - [Organization policies](organization.md): manage centralized policies for an organization or team in the Docker Admin Console. @@ -21,5 +23,5 @@ then choose the access surface you want to govern. sandboxes. - [Filesystem access rules](filesystem.md): control which host paths sandboxes can mount as workspaces. -- [MCP tool access](mcp.md): control MCP server registration, tool calls, +- [MCP access policies](mcp.md): control MCP server registration, tool calls, resources, prompts, and approval gates with Cedar policy. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md index 4830cbec537a..80d96452df27 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md @@ -7,8 +7,8 @@ keywords: docker sandboxes, filesystem access, filesystem rules, workspace mount --- Filesystem access rules control which host paths a sandbox can mount as a -workspace. They help admins restrict sandbox workspaces to approved directories -across an organization. +workspace. Organization filesystem policies contain one or more rules that +restrict sandbox workspaces to approved directories. Filesystem access is managed with [organization policies](organization.md). When organization governance is active, filesystem rules replace local behavior for diff --git a/content/manuals/ai/sandboxes/governance/access-controls/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md index 38e2d217eefd..ed309aaed514 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -1,22 +1,22 @@ --- -title: Local access rules -linkTitle: Local rules +title: Local policy weight: 10 -description: Configure network access rules for sandboxes on your local machine. +description: Configure local network access rules for sandboxes on your machine. keywords: docker sandboxes, local policy, network access, allow rules, deny rules, sbx policy aliases: - /ai/sandboxes/security/policy/ - /ai/sandboxes/governance/local/ --- -The `sbx policy` command manages network access rules on your local machine. -Rules apply to all sandboxes on the machine when you use the global scope, or -to a single sandbox when scoped by name. +The `sbx policy` command manages the local policy on your machine. The local +policy contains network access rules. Rules apply to all sandboxes on the +machine when you use the global scope, or to a single sandbox when scoped by +name. -Local rules apply only when your organization doesn't enforce governance: +Local policy applies only when your organization doesn't enforce governance: -- **No org governance**: local rules fully control what sandboxes can access. -- **Org governance active**: the organization policy replaces local policy. +- **No org governance**: the local policy controls what sandboxes can access. +- **Org governance active**: organization policies replace local policy. Local rules are inactive, and `sbx policy allow` and `sbx policy deny` have no effect. To list the inactive local rules, run `sbx policy ls --include-inactive`. See diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md index e470c61d23da..9dcc66c9b0e3 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md @@ -1,17 +1,17 @@ --- -title: Control MCP tool access -linkTitle: MCP tool access +title: MCP access policies +linkTitle: MCP access weight: 50 description: Use Cedar-based MCP policies to control sandbox MCP server registration, tool calls, prompts, resources, and approval gates. -keywords: docker sandboxes, MCP policy, MCP tool access, Cedar policy, requireApproval, AI Governance +keywords: docker sandboxes, MCP policy, MCP access, Cedar policy, requireApproval, AI Governance --- -MCP access rules control Model Context Protocol activity made available to a +MCP policies control Model Context Protocol activity made available to a sandbox through Docker's MCP gateway. Use them to govern server registration, tool calls, gateway meta-tools, resources, prompts, and approval requirements. Unlike [network access rules](network.md) and -[filesystem access rules](filesystem.md), MCP access rules are organization +[filesystem access rules](filesystem.md), MCP policies are organization policies written in Cedar. Docker defines the `MCP` namespace, including the actions, resource types, attributes, and approval behavior that policies can match. For Docker's MCP policy actions, resources, attributes, and context diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index 7a37a95787a8..dee1df9575be 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -6,14 +6,14 @@ description: Control outbound network access from Docker Sandboxes with local an keywords: docker sandboxes, network access, network rules, governance, local policy, organization policy --- -Network access rules control outbound connections from sandboxes. Use them to -allow the domains, IP ranges, and ports a workflow needs, and to block -destinations that should stay unavailable. +Network access rules control outbound connections from sandboxes. Network +policies contain one or more rules that allow the domains, IP ranges, and ports +a workflow needs, or block destinations that should stay unavailable. You can configure network access in two places: -- [Local access rules](local.md), which apply to sandboxes on one developer - machine when organization governance is not active. +- [Local policy](local.md), which applies to sandboxes on one developer machine + when organization governance is not active. - [Organization policies](organization.md), which apply centrally across an organization or to selected teams. @@ -48,7 +48,7 @@ $ sbx policy deny network ads.example.com ``` For presets, sandbox-scoped rules, testing, and troubleshooting, see -[Local access rules](local.md). +[Local policy](local.md). ## Organization network rules diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md index b919fec91df2..f9cbe55252f3 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -42,7 +42,7 @@ managed separately, under **Network access** and **Filesystem access**. The steps in this section cover network and filesystem policies. MCP policies use Cedar rather than the network and filesystem rule form. For MCP examples, see -[MCP tool access](mcp.md). +[MCP access policies](mcp.md). To create a policy: @@ -69,7 +69,7 @@ pages for syntax, examples, and enforcement details: sandboxes. - [Filesystem access rules](filesystem.md): control which host paths sandboxes can mount as workspaces. -- [MCP tool access](mcp.md): control MCP server registration, tool calls, +- [MCP access policies](mcp.md): control MCP server registration, tool calls, resources, prompts, and approval gates with Cedar policy. When organization governance is active, local and kit-defined rules are not diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md index 4165089955fc..22ea2981dcea 100644 --- a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md +++ b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md @@ -11,8 +11,8 @@ namespace. This reference defines the Docker-specific policy surface for Model Context Protocol (MCP) activity made available to sandboxes through Docker's MCP gateway. -Use this reference with [Control MCP tool access](../access-controls/mcp.md) -for common policy patterns. For the Cedar language, see the +Use this reference with [MCP access policies](../access-controls/mcp.md) for +common policy patterns. For the Cedar language, see the [Cedar documentation](https://docs.cedarpolicy.com/). ## Evaluation model From bf9d89f13246b16c788b658e27eb08a5b57ae9d3 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:48:26 +0000 Subject: [PATCH 10/35] docs: align sandbox access policy labels --- content/manuals/ai/sandboxes/governance/_index.md | 6 +++--- .../ai/sandboxes/governance/access-controls/_index.md | 6 +++--- .../ai/sandboxes/governance/access-controls/filesystem.md | 8 ++++---- .../ai/sandboxes/governance/access-controls/mcp.md | 4 ++-- .../ai/sandboxes/governance/access-controls/network.md | 8 ++++---- .../sandboxes/governance/access-controls/organization.md | 6 +++--- 6 files changed, 19 insertions(+), 19 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index bbedf37e9ef7..2ed2b6949a35 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -44,10 +44,10 @@ MCP policy basics, evaluation, and precedence. machine with the `sbx policy` CLI. - [Organization policies](access-controls/organization.md): centrally manage sandbox policies across your organization from the Admin Console. -- [Network access rules](access-controls/network.md): control outbound network +- [Network access policies](access-controls/network.md): control outbound network access from sandboxes. -- [Filesystem access rules](access-controls/filesystem.md): control which host - paths sandboxes can mount as workspaces. +- [Filesystem access policies](access-controls/filesystem.md): control which + host paths sandboxes can mount as workspaces. - [MCP access policies](access-controls/mcp.md): control MCP server registration, tool calls, resources, prompts, and approval gates. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/_index.md b/content/manuals/ai/sandboxes/governance/access-controls/_index.md index 2ad120c036d0..cc812c609f54 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/_index.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/_index.md @@ -19,9 +19,9 @@ and filesystem rule format. ## Access surfaces -- [Network access rules](network.md): control outbound network access from +- [Network access policies](network.md): control outbound network access from sandboxes. -- [Filesystem access rules](filesystem.md): control which host paths sandboxes - can mount as workspaces. +- [Filesystem access policies](filesystem.md): control which host paths + sandboxes can mount as workspaces. - [MCP access policies](mcp.md): control MCP server registration, tool calls, resources, prompts, and approval gates with Cedar policy. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md index 80d96452df27..551f21404bfb 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md @@ -1,14 +1,14 @@ --- -title: Filesystem access rules +title: Filesystem access policies linkTitle: Filesystem access weight: 40 description: Control which host paths Docker Sandboxes can mount as workspaces with organization filesystem policies. keywords: docker sandboxes, filesystem access, filesystem rules, workspace mount, organization policy, governance --- -Filesystem access rules control which host paths a sandbox can mount as a -workspace. Organization filesystem policies contain one or more rules that -restrict sandbox workspaces to approved directories. +Filesystem access policies control which host paths a sandbox can mount as a +workspace. Each policy contains one or more rules that restrict sandbox +workspaces to approved directories. Filesystem access is managed with [organization policies](organization.md). When organization governance is active, filesystem rules replace local behavior for diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md index 9dcc66c9b0e3..cbc283e87c34 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md @@ -10,8 +10,8 @@ MCP policies control Model Context Protocol activity made available to a sandbox through Docker's MCP gateway. Use them to govern server registration, tool calls, gateway meta-tools, resources, prompts, and approval requirements. -Unlike [network access rules](network.md) and -[filesystem access rules](filesystem.md), MCP policies are organization +Unlike [network access policies](network.md) and +[filesystem access policies](filesystem.md), MCP policies are organization policies written in Cedar. Docker defines the `MCP` namespace, including the actions, resource types, attributes, and approval behavior that policies can match. For Docker's MCP policy actions, resources, attributes, and context diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index dee1df9575be..70615a122b70 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -1,14 +1,14 @@ --- -title: Network access rules +title: Network access policies linkTitle: Network access weight: 30 description: Control outbound network access from Docker Sandboxes with local and organization policy rules. keywords: docker sandboxes, network access, network rules, governance, local policy, organization policy --- -Network access rules control outbound connections from sandboxes. Network -policies contain one or more rules that allow the domains, IP ranges, and ports -a workflow needs, or block destinations that should stay unavailable. +Network access policies control outbound connections from sandboxes. Each +policy contains one or more rules that allow the domains, IP ranges, and ports a +workflow needs, or block destinations that should stay unavailable. You can configure network access in two places: diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md index f9cbe55252f3..7c79f2c0f667 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -65,10 +65,10 @@ update. Use the action menu (⋮) to edit or delete a policy. Organization policies are managed by access surface. Use the access-control pages for syntax, examples, and enforcement details: -- [Network access rules](network.md): control outbound network access from +- [Network access policies](network.md): control outbound network access from sandboxes. -- [Filesystem access rules](filesystem.md): control which host paths sandboxes - can mount as workspaces. +- [Filesystem access policies](filesystem.md): control which host paths + sandboxes can mount as workspaces. - [MCP access policies](mcp.md): control MCP server registration, tool calls, resources, prompts, and approval gates with Cedar policy. From 514bbf391da81de3aa953f2c61587b97b8f12ef9 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 07:42:01 +0000 Subject: [PATCH 11/35] docs: add sandbox mcp gateway usage Document the local MCP gateway workflow for Docker Sandboxes, including server registration, OAuth handling, static and dynamic sandbox modes, live loading, bundles, and governance cross-links. Reorder the top-level Sandboxes section weights so the new MCP gateway page has a stable place in the sidebar. --- content/manuals/ai/sandboxes/_index.md | 4 +- content/manuals/ai/sandboxes/agents/_index.md | 2 +- content/manuals/ai/sandboxes/architecture.md | 2 +- .../manuals/ai/sandboxes/customize/_index.md | 2 +- content/manuals/ai/sandboxes/faq.md | 2 +- .../manuals/ai/sandboxes/governance/_index.md | 7 +- .../governance/access-controls/mcp.md | 2 + .../ai/sandboxes/governance/concepts.md | 6 +- .../governance/reference/mcp-policy.md | 2 +- content/manuals/ai/sandboxes/mcp-gateway.md | 264 ++++++++++++++++++ content/manuals/ai/sandboxes/release-notes.md | 3 +- .../manuals/ai/sandboxes/security/_index.md | 2 +- .../manuals/ai/sandboxes/troubleshooting.md | 2 +- 13 files changed, 285 insertions(+), 15 deletions(-) create mode 100644 content/manuals/ai/sandboxes/mcp-gateway.md diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 4b8399b2a20d..1b8c5642534a 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -18,7 +18,7 @@ system. > [organization governance](governance/) requires a separate paid subscription. Organization admins can -[centrally manage sandbox network and filesystem policies](governance/access-controls/organization.md) +[centrally manage sandbox network, filesystem, and MCP policies](governance/access-controls/organization.md) from the Docker Admin Console, so the same rules apply uniformly across every developer's machine. Available on a separate paid subscription. @@ -73,6 +73,8 @@ the [usage guide](usage.md) for basic commands. ## Learn more - [Agents](agents/) — supported agents and per-agent configuration +- [MCP gateway](mcp-gateway.md) — register MCP servers and connect them to + sandboxed agents - [Customize](customize/) — reusable templates and declarative kits for extending or tailoring sandboxes - [Architecture](architecture.md) — microVM isolation, workspace mounting, diff --git a/content/manuals/ai/sandboxes/agents/_index.md b/content/manuals/ai/sandboxes/agents/_index.md index ad8fecf38657..edaaec96abc1 100644 --- a/content/manuals/ai/sandboxes/agents/_index.md +++ b/content/manuals/ai/sandboxes/agents/_index.md @@ -1,7 +1,7 @@ --- title: Supported agents linkTitle: Agents -weight: 30 +weight: 50 description: AI coding agents supported by Docker Sandboxes. keywords: docker sandboxes, ai agents, claude code, codex, cursor, gemini --- diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index ef44743e1111..363864cfb134 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -1,6 +1,6 @@ --- title: Architecture -weight: 40 +weight: 70 description: Technical architecture of Docker Sandboxes; workspace mounting, storage, networking, and sandbox lifecycle. keywords: docker sandboxes, architecture, microVM, workspace mounting, sandbox lifecycle --- diff --git a/content/manuals/ai/sandboxes/customize/_index.md b/content/manuals/ai/sandboxes/customize/_index.md index d5df8e2365ae..0656152a770c 100644 --- a/content/manuals/ai/sandboxes/customize/_index.md +++ b/content/manuals/ai/sandboxes/customize/_index.md @@ -3,7 +3,7 @@ title: Customizing sandboxes linkTitle: Customize description: Build reusable sandbox images, extend agents with tools and credentials, and define custom agents using templates and kits. keywords: sandboxes, sbx, customize, templates, kits, mixins, custom agents -weight: 35 +weight: 60 aliases: - /ai/sandboxes/agents/custom-environments/ params: diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 8e0de294359f..91624a1ced83 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -1,6 +1,6 @@ --- title: FAQ -weight: 70 +weight: 110 description: Frequently asked questions about Docker Sandboxes. keywords: docker sandboxes, sbx, faq, sign in, telemetry, clipboard, image paste, pricing, commercial use, allowlist, firewall, domains, proxy --- diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 2ed2b6949a35..684b051c2e41 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -1,13 +1,14 @@ --- title: Governance -weight: 55 +weight: 90 description: Control what sandboxes can access, from local developer rules to org-wide enforcement. keywords: docker sandboxes, governance, policy, network access, filesystem access, mcp policy, organization policy --- Sandbox governance covers the policy system that controls what sandboxes can -access over the network, on the filesystem, and through MCP. It operates at two -layers, and only one applies at a time: +access over the network, on the filesystem, and through MCP. For MCP setup and +server registration, see [MCP gateway](../mcp-gateway.md). Governance operates +at two layers, and only one applies at a time: **Local policy** is configured per machine using the `sbx policy` CLI. It lets individual developers customize which domains their sandboxes can reach. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md index cbc283e87c34..a22c555620c7 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md @@ -9,6 +9,8 @@ keywords: docker sandboxes, MCP policy, MCP access, Cedar policy, requireApprova MCP policies control Model Context Protocol activity made available to a sandbox through Docker's MCP gateway. Use them to govern server registration, tool calls, gateway meta-tools, resources, prompts, and approval requirements. +To register MCP servers and connect them to sandboxes, see +[MCP gateway](../../mcp-gateway.md). Unlike [network access policies](network.md) and [filesystem access policies](filesystem.md), MCP policies are organization diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 3a0509153ec3..486401ce3ee2 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -121,9 +121,9 @@ paths under the home directory, while `~/*` matches only its direct children. ### MCP policies MCP policies control Model Context Protocol activity made available to a -sandbox through Docker's MCP gateway. They are organization policies written in -Cedar using the `MCP` namespace, rather than the network and filesystem rule -format. +sandbox through Docker's [MCP gateway](../mcp-gateway.md). They are +organization policies written in Cedar using the `MCP` namespace, rather than +the network and filesystem rule format. Cedar evaluates each MCP request against a principal, action, resource, and context. Admins write policy statements for the action, resource, and context. diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md index 22ea2981dcea..7c693a66a37b 100644 --- a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md +++ b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md @@ -9,7 +9,7 @@ keywords: docker sandboxes, MCP policy, Cedar policy, MCP actions, MCP resources MCP policies are organization policies written in Cedar using Docker's `MCP` namespace. This reference defines the Docker-specific policy surface for Model Context Protocol (MCP) activity made available to sandboxes through Docker's -MCP gateway. +[MCP gateway](../../mcp-gateway.md). Use this reference with [MCP access policies](../access-controls/mcp.md) for common policy patterns. For the Cedar language, see the diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md new file mode 100644 index 000000000000..57781ffa219d --- /dev/null +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -0,0 +1,264 @@ +--- +title: MCP gateway +description: Register MCP servers, authorize OAuth-backed servers, and connect MCP tools to Docker Sandboxes. +keywords: docker sandboxes, sbx, MCP gateway, Model Context Protocol, MCP servers, sbx mcp, static MCP, OAuth +weight: 30 +--- + +Docker Sandboxes includes an MCP gateway for connecting agents to Model Context +Protocol servers. The gateway runs with the sandbox and presents one MCP +endpoint to the agent. Use `sbx mcp` on the host to register servers, manage +OAuth credentials, and attach registered servers to running sandboxes. + +This page focuses on local gateway mode, where MCP traffic is handled by a +gateway running on your machine. Use `sbx mcp status` to check the effective +gateway for your account. + +## Prerequisites + +- Sign in with `sbx login`. +- Use an agent integration that configures MCP at startup: Claude Code, Codex, + Gemini, Kiro, or OpenCode. +- For remote servers that require OAuth, use MCP servers that support OAuth + Dynamic Client Registration. + +The Docker Desktop MCP Toolkit isn't required for sandbox MCP support. + +## Check the gateway mode + +Run `sbx mcp status` to see the effective MCP gateway: + +```console +$ sbx mcp status +Gateway mode: local +Gateway URL: (none) +Source: mcp-saas gateway-mode API (resolved by daemon) +``` + +The output can also include `Decision` and `Reason` fields. These fields show +the raw gateway decision and why that decision produced the effective gateway. + +The daemon resolves the gateway mode and caches the result for its lifetime. If +you change sign-in state or an MCP gateway setting, restart the daemon before +checking again: + +```console +$ sbx daemon stop +$ sbx mcp status +``` + +## Register an MCP server + +Register servers on the host before you connect them to a sandbox. Server names +can contain letters, numbers, dots, hyphens, and underscores. + +For a remote MCP endpoint, pass the server URL: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp +$ sbx mcp add linear --url https://mcp.linear.app/mcp +``` + +You can also register a server from an MCP registry URL, a `server.json` or +`server.yaml` manifest URL, or a Docker Hardened Image reference that carries +an MCP server manifest: + +```console +$ sbx mcp add fetch \ + --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest + +$ sbx mcp add opine --url https://example.com/mcp/opine/server.yaml + +$ sbx mcp add fetch --url dhi.io/fetch-mcp:latest +``` + +To run a registry server locally as a container, add `--local`. This is useful +for stdio-based servers packaged as containers: + +```console +$ sbx mcp add fetch --local \ + --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest +``` + +You can also register a local stdio command: + +```console +$ sbx mcp add playwright --command npx --args @playwright/mcp@latest +$ sbx mcp add local-image-server --command docker \ + --args run --args -i --args your/image +``` + +> [!WARNING] +> Local stdio commands run on the host, outside the sandbox. They run with your +> host user's permissions and can access host files, host network resources, and +> credentials available to that user. Use `--command` only with executables you +> trust. + +`sbx mcp add` registers the server. It doesn't attach the server to a running +sandbox by itself. To connect registered servers to a sandbox, use dynamic mode, +static mode, or `sbx mcp load`. + +## Authorize OAuth-backed servers + +If a registered remote server requires OAuth, `sbx mcp add` starts the +authorization flow by default: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp +Resolving MCP server "notion"... +Open this URL to authorize MCP server "notion": +https://api.notion.com/v1/oauth/authorize?... +MCP server "notion" authorized +MCP server "notion" registered (type: remote) +``` + +OAuth credentials stay on the host. In local gateway mode, `sbx` stores tokens +in the host operating system's credential store. + +To register an OAuth-backed server without authorizing it, pass `--skip_auth`: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp --skip_auth +``` + +When a server isn't authorized, the gateway exposes a helper tool named +`-authorize`, such as `notion-authorize`. The agent can call that tool +from inside the sandbox when it needs the server. The gateway also exposes +`-revoke-auth` for OAuth-backed servers. + +You can manage OAuth credentials from the host: + +```console +$ sbx mcp auth status notion +$ sbx mcp auth notion +$ sbx mcp auth rm notion +``` + +Use `--all` to apply `auth`, `auth status`, or `auth rm` to all registered +OAuth-backed servers. Use `--format=json` for machine-readable output. + +## Start a sandbox with MCP + +Every sandbox starts an MCP gateway. When the sandbox starts, supported agent +integrations read the gateway URL and register it with the agent. + +A sandbox can use MCP in dynamic mode or static mode. The mode is selected when +the sandbox is created. + +| Mode | How to use it | Behavior | +| ------- | ------------------------- | ------------------------------------------------------------------------- | +| Dynamic | Omit `--static-mcp` | The registered catalog is searchable from the agent through gateway tools | +| Static | Pass `--static-mcp` names | Only the named servers are pre-loaded, and discovery tools are disabled | + +### Dynamic mode + +Dynamic mode is the default. Start a sandbox without `--static-mcp`: + +```console +$ sbx run claude --name my-session +``` + +In dynamic mode, the agent can search the registered MCP catalog and connect +servers during the session. The gateway exposes discovery tools such as +`mcp-find` and `mcp-add`. + +### Static mode + +Use static mode when you want a fixed MCP server set for the sandbox: + +```console +$ sbx mcp add notion --url https://mcp.notion.com/mcp +$ sbx mcp add linear --url https://mcp.linear.app/mcp +$ sbx run claude --name my-session --static-mcp notion,linear +``` + +You can pass `--static-mcp` as a comma-separated list or repeat the flag: + +```console +$ sbx run claude --name my-session \ + --static-mcp notion --static-mcp linear +``` + +Every name in the static set must already be registered with `sbx mcp add`. The +static set is fixed at sandbox creation time. To use a different static set, +create a new sandbox. + +## Add a server to a running sandbox + +To attach an already-registered server to a running sandbox, use `sbx mcp +load`: + +```console +$ sbx mcp add linear --url https://mcp.linear.app/mcp +$ sbx mcp load linear --sandbox my-session +MCP server "linear" loaded into sandbox "my-session" (live) +``` + +Connected agent sessions receive a tool-list update, so the agent can discover +the added tools without reconnecting. + +## Manage registrations + +List registered servers: + +```console +$ sbx mcp ls +``` + +Inspect a registered server: + +```console +$ sbx mcp inspect notion +``` + +Remove a registered server: + +```console +$ sbx mcp rm notion +``` + +For OAuth-backed servers, `sbx mcp rm` removes the OAuth credential before it +removes the server registration. To remove only the OAuth credential, use +`sbx mcp auth rm`. + +## Register a bundle + +An MCP bundle is a JSON array of server definitions fetched from a URL. Each +entry maps to one `sbx mcp add` registration. + +```json +[ + { "name": "notion", "url": "https://mcp.notion.com/mcp" }, + { "name": "linear", "url": "https://mcp.linear.app/mcp" }, + { + "name": "github", + "command": "npx", + "args": ["@modelcontextprotocol/server-github"] + } +] +``` + +Fetch and register a bundle: + +```console +$ sbx mcp bundle add core --url https://example.com/mcp-bundle.json +``` + +List registered bundles: + +```console +$ sbx mcp bundle ls +``` + +Remove a bundle and the servers it registered: + +```console +$ sbx mcp bundle rm core +``` + +## Governance + +Organizations with AI Governance can use +[MCP access policies](governance/access-controls/mcp.md) to control MCP server +registration, tool calls, gateway meta-tools, resources, prompts, and approval +requirements. MCP access policies are organization policies written in Cedar. diff --git a/content/manuals/ai/sandboxes/release-notes.md b/content/manuals/ai/sandboxes/release-notes.md index 4a53befc15d7..d0224516a9e5 100644 --- a/content/manuals/ai/sandboxes/release-notes.md +++ b/content/manuals/ai/sandboxes/release-notes.md @@ -3,6 +3,7 @@ title: Docker Sandboxes release notes linkTitle: Release notes description: New features, bug fixes, and changes in Docker Sandboxes keywords: docker sandboxes, sbx, release notes, changelog +weight: 130 toc_min: 1 toc_max: 2 tags: @@ -23,7 +24,7 @@ the full release history, including pre-releases and downloads, see the ### Highlights -This release revamps **policy tooling** with a concise `sbx policy ls`, a new `sbx policy inspect`, and a `sbx policy check network` command for testing whether the current policy would allow an access request before you run. +This release revamps **policy tooling** with a concise `sbx policy ls`, a new `sbx policy inspect`, and a `sbx policy check network` command for testing whether the current policy would allow an access request before you run. Networking gains a **SOCKS5 upstream-proxy transport**. Secrets get a new **`sbx secret import`** with clearer env-source visibility. diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 2991f9bcf81a..93c4da85085f 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -1,7 +1,7 @@ --- title: Security model linkTitle: Security model -weight: 50 +weight: 80 description: Trust boundaries, isolation layers, and security properties of Docker Sandboxes. keywords: docker sandboxes, security model, isolation, trust boundaries, microVM --- diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 112f5b596f3a..57b7312769a1 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -1,6 +1,6 @@ --- title: Troubleshooting -weight: 60 +weight: 100 description: Resolve common issues when using Docker Sandboxes. keywords: docker sandboxes, sbx, troubleshooting, diagnostics, reset, network policy, git, ssh --- From 76628a02b03192810f57cc2b35b5ab204ce17dec Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 08:42:26 +0000 Subject: [PATCH 12/35] docs: restructure sandbox mcp gateway page Improve the MCP gateway usage page with progressive disclosure: explain the gateway model first, add a quick start, move registration details after the first run, and remove gateway-mode diagnostics from the public local-mode flow. Add an upfront note that the Docker Sandboxes MCP gateway is separate from the Docker Desktop MCP Toolkit. --- content/manuals/ai/sandboxes/mcp-gateway.md | 73 ++++++++++++--------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index 57781ffa219d..67c009f46906 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -6,13 +6,21 @@ weight: 30 --- Docker Sandboxes includes an MCP gateway for connecting agents to Model Context -Protocol servers. The gateway runs with the sandbox and presents one MCP -endpoint to the agent. Use `sbx mcp` on the host to register servers, manage -OAuth credentials, and attach registered servers to running sandboxes. - -This page focuses on local gateway mode, where MCP traffic is handled by a -gateway running on your machine. Use `sbx mcp status` to check the effective -gateway for your account. +Protocol servers. The gateway gives the agent inside the sandbox one MCP +endpoint, while `sbx` manages the registered servers, OAuth credentials, and +sandbox lifecycle on the host. + +This is different from configuring an MCP server directly in an agent such as +Claude Code. Direct MCP setup configures that agent's own MCP client. With +Docker Sandboxes, you register MCP servers once on the host, and the sandbox +gateway exposes them to supported agents inside isolated sandboxes. That +host-managed gateway provides a single path for credentials, dynamic or fixed +server sets, live server loading, and organization governance. + +> [!NOTE] +> The Docker Sandboxes MCP gateway is separate from the Docker Desktop MCP +> Toolkit. You don't need the Docker Desktop MCP Toolkit to use `sbx mcp`, and +> MCP Toolkit server settings aren't shared with Docker Sandboxes. ## Prerequisites @@ -22,35 +30,42 @@ gateway for your account. - For remote servers that require OAuth, use MCP servers that support OAuth Dynamic Client Registration. -The Docker Desktop MCP Toolkit isn't required for sandbox MCP support. - -## Check the gateway mode +## Quick start -Run `sbx mcp status` to see the effective MCP gateway: +Start by registering one MCP server on the host: ```console -$ sbx mcp status -Gateway mode: local -Gateway URL: (none) -Source: mcp-saas gateway-mode API (resolved by daemon) +$ sbx mcp add notion --url https://mcp.notion.com/mcp ``` -The output can also include `Decision` and `Reason` fields. These fields show -the raw gateway decision and why that decision produced the effective gateway. +If the server requires OAuth, `sbx` opens an authorization flow before it stores +the registration. After registration, verify that the server is in your local +MCP catalog: + +```console +$ sbx mcp ls +NAME TYPE URL/COMMAND +notion remote https://mcp.notion.com/mcp +``` -The daemon resolves the gateway mode and caches the result for its lifetime. If -you change sign-in state or an MCP gateway setting, restart the daemon before -checking again: +Then start a sandbox: ```console -$ sbx daemon stop -$ sbx mcp status +$ sbx run claude --name mcp-demo ``` +The sandbox starts with an MCP gateway. In the default dynamic mode, the agent +can discover registered MCP servers through gateway tools and use them during +the session. The registration remains on the host and can be reused by other +sandboxes. + ## Register an MCP server -Register servers on the host before you connect them to a sandbox. Server names -can contain letters, numbers, dots, hyphens, and underscores. +`sbx mcp add` registers an MCP server by name. The registration records the +server definition on the host. It doesn't attach the server to a running sandbox +by itself. + +Server names can contain letters, numbers, dots, hyphens, and underscores. For a remote MCP endpoint, pass the server URL: @@ -94,10 +109,6 @@ $ sbx mcp add local-image-server --command docker \ > credentials available to that user. Use `--command` only with executables you > trust. -`sbx mcp add` registers the server. It doesn't attach the server to a running -sandbox by itself. To connect registered servers to a sandbox, use dynamic mode, -static mode, or `sbx mcp load`. - ## Authorize OAuth-backed servers If a registered remote server requires OAuth, `sbx mcp add` starts the @@ -137,7 +148,7 @@ $ sbx mcp auth rm notion Use `--all` to apply `auth`, `auth status`, or `auth rm` to all registered OAuth-backed servers. Use `--format=json` for machine-readable output. -## Start a sandbox with MCP +## Expose servers to a sandbox Every sandbox starts an MCP gateway. When the sandbox starts, supported agent integrations read the gateway URL and register it with the agent. @@ -185,8 +196,8 @@ create a new sandbox. ## Add a server to a running sandbox -To attach an already-registered server to a running sandbox, use `sbx mcp -load`: +To attach an already-registered server to a running sandbox outside the initial +dynamic or static setup, use `sbx mcp load`: ```console $ sbx mcp add linear --url https://mcp.linear.app/mcp From cd8418dacb937589a71e70a13fd84132c483f9ff Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 08:49:29 +0000 Subject: [PATCH 13/35] docs: clarify sandbox mcp registration options Segment the sbx mcp registration paths into remote endpoint, MCP registry, server manifest, Docker Hardened Image, local container, and local stdio options. Clarify that registration before sandbox start seeds the initial MCP catalog, while already-running sandboxes need sbx mcp load. --- content/manuals/ai/sandboxes/mcp-gateway.md | 45 +++++++++++++++++---- 1 file changed, 37 insertions(+), 8 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index 67c009f46906..f1277aa0ab48 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -56,17 +56,22 @@ $ sbx run claude --name mcp-demo The sandbox starts with an MCP gateway. In the default dynamic mode, the agent can discover registered MCP servers through gateway tools and use them during -the session. The registration remains on the host and can be reused by other -sandboxes. +the session. Because you registered the server before starting the sandbox, it +is part of that sandbox's initial MCP catalog. The registration remains on the +host and can be reused by other sandboxes. ## Register an MCP server `sbx mcp add` registers an MCP server by name. The registration records the server definition on the host. It doesn't attach the server to a running sandbox -by itself. +by itself. A server registered before sandbox creation is available when that +sandbox's gateway starts. To add a server to a sandbox that's already running, +use [`sbx mcp load`](#add-a-server-to-a-running-sandbox). Server names can contain letters, numbers, dots, hyphens, and underscores. +### Remote endpoint URL + For a remote MCP endpoint, pass the server URL: ```console @@ -74,27 +79,51 @@ $ sbx mcp add notion --url https://mcp.notion.com/mcp $ sbx mcp add linear --url https://mcp.linear.app/mcp ``` -You can also register a server from an MCP registry URL, a `server.json` or -`server.yaml` manifest URL, or a Docker Hardened Image reference that carries -an MCP server manifest: +### MCP registry URL + +You can register a server from the MCP community registry: ```console $ sbx mcp add fetch \ --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest +``` + +### Server manifest URL +You can register a server from a URL that returns a `server.json` or +`server.yaml` document. A server manifest describes the MCP server and how the +gateway should connect to it. This is the same general shape used by the MCP +community registry, and it works for manifests hosted on GitHub raw URLs, +internal HTTP servers, or CDNs. + +```console $ sbx mcp add opine --url https://example.com/mcp/opine/server.yaml +``` +### Docker Hardened Image reference + +You can register a Docker Hardened Image reference when the image carries an +MCP server manifest in its attestation: + +```console $ sbx mcp add fetch --url dhi.io/fetch-mcp:latest ``` -To run a registry server locally as a container, add `--local`. This is useful -for stdio-based servers packaged as containers: +Generic image references, such as `docker.io/example/server:latest`, aren't +accepted. Use a server manifest URL instead. + +### Registry server as a local container + +To run a registry server locally as a container, add `--local` to a registry or +manifest URL. This is useful for stdio-based servers packaged as containers: ```console $ sbx mcp add fetch --local \ --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest ``` +### Local stdio command + You can also register a local stdio command: ```console From 2b95858ed4f5c0a6249b7e2a734b8edde8623ec0 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 09:00:28 +0000 Subject: [PATCH 14/35] docs: clarify sandbox mcp local server registration --- content/manuals/ai/sandboxes/mcp-gateway.md | 73 ++++++++++----------- 1 file changed, 35 insertions(+), 38 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index f1277aa0ab48..ef696e86eca4 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -29,6 +29,8 @@ server sets, live server loading, and organization governance. Gemini, Kiro, or OpenCode. - For remote servers that require OAuth, use MCP servers that support OAuth Dynamic Client Registration. +- For local containerized MCP servers, use a host with Docker installed and + running. ## Quick start @@ -79,64 +81,59 @@ $ sbx mcp add notion --url https://mcp.notion.com/mcp $ sbx mcp add linear --url https://mcp.linear.app/mcp ``` -### MCP registry URL +### Local stdio server -You can register a server from the MCP community registry: +Some MCP servers communicate over stdio instead of exposing a remote HTTP +endpoint. Docker Sandboxes can register local stdio servers in two ways: by +resolving a package from registry or manifest metadata, or by running an +explicit command. -```console -$ sbx mcp add fetch \ - --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest -``` - -### Server manifest URL +#### From registry or manifest metadata -You can register a server from a URL that returns a `server.json` or -`server.yaml` document. A server manifest describes the MCP server and how the -gateway should connect to it. This is the same general shape used by the MCP -community registry, and it works for manifests hosted on GitHub raw URLs, -internal HTTP servers, or CDNs. +Use `--local` with an MCP community registry URL or a URL that returns a +`server.json` or `server.yaml` document. The registry entry or manifest must +describe an OCI package that uses stdio transport. `sbx` resolves the image from +the metadata and starts it on the host with Docker. ```console -$ sbx mcp add opine --url https://example.com/mcp/opine/server.yaml -``` - -### Docker Hardened Image reference - -You can register a Docker Hardened Image reference when the image carries an -MCP server manifest in its attestation: - -```console -$ sbx mcp add fetch --url dhi.io/fetch-mcp:latest +$ sbx mcp add fetch --local \ + --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest ``` -Generic image references, such as `docker.io/example/server:latest`, aren't -accepted. Use a server manifest URL instead. - -### Registry server as a local container +For local gateway usage, include `--local`. Without `--local`, registry and +manifest URLs resolve to OCI-backed server registrations for hosted gateway +modes, which this page doesn't cover. -To run a registry server locally as a container, add `--local` to a registry or -manifest URL. This is useful for stdio-based servers packaged as containers: +A server manifest describes the MCP server package and how to start it. It can +be hosted on a GitHub raw URL, internal HTTP server, or CDN. ```console -$ sbx mcp add fetch --local \ - --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest +$ sbx mcp add opine --local --url https://example.com/mcp/opine/server.yaml ``` -### Local stdio command +#### From an explicit command -You can also register a local stdio command: +Use `--command` when you already know the executable and arguments, or when you +need custom Docker flags. The command can be a package runner such as `npx` or +a Docker container command: ```console $ sbx mcp add playwright --command npx --args @playwright/mcp@latest $ sbx mcp add local-image-server --command docker \ - --args run --args -i --args your/image + --args run --args -i --args --rm --args your/image ``` +Use registry or manifest metadata when you have a published server definition +and don't need to customize `docker run`. Use `--command` for local +development, private servers, or custom container flags. + > [!WARNING] -> Local stdio commands run on the host, outside the sandbox. They run with your -> host user's permissions and can access host files, host network resources, and -> credentials available to that user. Use `--command` only with executables you -> trust. +> Local stdio servers run on the host, outside sandbox isolation. If the command +> starts a Docker container, that container uses host Docker isolation, not +> sandbox isolation. The process or container can access host files, host +> network resources, and credentials made available to it. Use trusted commands +> and images, and avoid mounting host paths or passing credentials unless the +> server needs them. ## Authorize OAuth-backed servers From 87eb95951085f9907f7fab1dcad93631d14b080d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 11:06:27 +0000 Subject: [PATCH 15/35] docs: clarify sbx mcp local registry flow The previous wording exposed hosted gateway internals while explaining --local. This clarifies that --local runs registry or manifest entries as host-side stdio servers and rejects non-stdio packages. --- content/manuals/ai/sandboxes/mcp-gateway.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index ef696e86eca4..1e728e8205fc 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -100,9 +100,9 @@ $ sbx mcp add fetch --local \ --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest ``` -For local gateway usage, include `--local`. Without `--local`, registry and -manifest URLs resolve to OCI-backed server registrations for hosted gateway -modes, which this page doesn't cover. +The `--local` flag tells `sbx` to run the registry or manifest entry as a +host-side stdio server. If the entry doesn't publish a stdio package, `sbx` +rejects the registration instead of starting it locally. A server manifest describes the MCP server package and how to start it. It can be hosted on a GitHub raw URL, internal HTTP server, or CDN. From a0939b1f2ceaf5e921105282b7b72aeb55553fbd Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 11:11:05 +0000 Subject: [PATCH 16/35] docs: explain sbx mcp registration inputs The MCP gateway page described flags without separating endpoint URLs from metadata URLs. This adds the registration input model and clarifies that local stdio servers run on the host, not inside the sandbox. --- content/manuals/ai/sandboxes/mcp-gateway.md | 32 ++++++++++++++------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index 1e728e8205fc..a650c814ab3e 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -72,6 +72,20 @@ use [`sbx mcp load`](#add-a-server-to-a-running-sandbox). Server names can contain letters, numbers, dots, hyphens, and underscores. +The `--url` flag can point to different kinds of input. The execution location +depends on what you register: + +- **Remote endpoint URL**: The URL is the running MCP server endpoint. The + server runs remotely, and the sandbox gateway connects to it. +- **Metadata URL with `--local`**: The URL returns a registry entry, + `server.json`, or `server.yaml` that describes an OCI-packaged stdio server. + `sbx` resolves the image and runs it on the host with Docker. +- **Explicit command**: `sbx` runs the command on the host as a stdio MCP + server. + +Local stdio servers run on the host, not inside the sandbox. The agent inside +the sandbox connects only to the MCP gateway. + ### Remote endpoint URL For a remote MCP endpoint, pass the server URL: @@ -84,25 +98,23 @@ $ sbx mcp add linear --url https://mcp.linear.app/mcp ### Local stdio server Some MCP servers communicate over stdio instead of exposing a remote HTTP -endpoint. Docker Sandboxes can register local stdio servers in two ways: by -resolving a package from registry or manifest metadata, or by running an -explicit command. +endpoint. Use a local stdio server when `sbx` should launch the MCP server on +the host. You can provide a metadata URL or an explicit command. #### From registry or manifest metadata -Use `--local` with an MCP community registry URL or a URL that returns a -`server.json` or `server.yaml` document. The registry entry or manifest must -describe an OCI package that uses stdio transport. `sbx` resolves the image from -the metadata and starts it on the host with Docker. +Use `--local --url` when you have an MCP community registry URL or a URL that +returns a `server.json` or `server.yaml` document. The registry entry or +manifest must describe an OCI package that uses stdio transport. `sbx` resolves +the image from the metadata and starts it on the host with Docker. ```console $ sbx mcp add fetch --local \ --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest ``` -The `--local` flag tells `sbx` to run the registry or manifest entry as a -host-side stdio server. If the entry doesn't publish a stdio package, `sbx` -rejects the registration instead of starting it locally. +If the entry doesn't publish a stdio package, `sbx` rejects the registration +instead of starting it locally. A server manifest describes the MCP server package and how to start it. It can be hosted on a GitHub raw URL, internal HTTP server, or CDN. From 2f1cbe9adc5b88e7815fa20e3666f16c27772744 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 11:17:59 +0000 Subject: [PATCH 17/35] docs: clarify local mcp package requirements The MCP gateway page did not state that metadata-based local registration only supports OCI stdio packages. This clarifies the OCI and host Docker requirements for --local --url registrations. --- content/manuals/ai/sandboxes/mcp-gateway.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index a650c814ab3e..ff2773227dbc 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -29,8 +29,9 @@ server sets, live server loading, and organization governance. Gemini, Kiro, or OpenCode. - For remote servers that require OAuth, use MCP servers that support OAuth Dynamic Client Registration. -- For local containerized MCP servers, use a host with Docker installed and - running. +- For `--local --url` registrations that resolve to OCI packages, use a host + with Docker installed and running. Docker is also required for explicit + `--command docker ...` registrations. ## Quick start @@ -105,16 +106,20 @@ the host. You can provide a metadata URL or an explicit command. Use `--local --url` when you have an MCP community registry URL or a URL that returns a `server.json` or `server.yaml` document. The registry entry or -manifest must describe an OCI package that uses stdio transport. `sbx` resolves -the image from the metadata and starts it on the host with Docker. +manifest must describe an OCI package that uses stdio transport. `sbx` doesn't +launch non-OCI package types, such as `npm`, from metadata. To use those +servers, register an explicit command. + +This path resolves the image from the metadata and starts it on the host with +Docker, so Docker must be installed and running on the host. ```console $ sbx mcp add fetch --local \ --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest ``` -If the entry doesn't publish a stdio package, `sbx` rejects the registration -instead of starting it locally. +If the entry doesn't publish an OCI stdio package, `sbx` rejects the +registration instead of starting it locally. A server manifest describes the MCP server package and how to start it. It can be hosted on a GitHub raw URL, internal HTTP server, or CDN. From b530baed051e7a462547c7cee5003da6e5387702 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 11:34:41 +0000 Subject: [PATCH 18/35] docs: document sandbox mcp gateway trust boundary The Sandboxes security and architecture pages did not explain where MCP gateway traffic and local MCP servers sit relative to the VM boundary. This adds the gateway placement, host-side local server caveat, and MCP policy enforcement point. --- content/manuals/ai/sandboxes/architecture.md | 16 ++++++++++++++++ .../sandboxes/governance/access-controls/mcp.md | 10 ++++++++++ content/manuals/ai/sandboxes/security/_index.md | 13 +++++++++++++ .../manuals/ai/sandboxes/security/isolation.md | 6 ++++++ 4 files changed, 45 insertions(+) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 363864cfb134..083b432af7a7 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -100,6 +100,22 @@ One limitation applies: `HTTP_PROXY`, `HTTPS_PROXY`, or `DOCKER_SANDBOXES_PROXY` environment variables explicitly. +## MCP gateway + +Supported agents connect to a single MCP gateway endpoint for the sandbox. The +gateway runs on the host side of the sandbox boundary and brokers access to +registered MCP servers. + +Registered MCP servers can be remote endpoints, or they can be local stdio +servers launched on the host. Local stdio servers don't run inside the sandbox +VM. If a local stdio server is packaged as an OCI image, or if you register an +explicit `docker` command, it uses Docker on the host. + +When MCP policies apply, enforcement happens on the MCP gateway path, separate +from the HTTP/HTTPS network proxy. Server registration is checked before the +server is stored, and governed MCP requests are checked by the gateway before +tool calls, resource reads, prompt retrieval, or gateway meta-tool execution. + ## Lifecycle `sbx run` initializes a VM with a workspace for a specified agent and starts diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md index a22c555620c7..070c3c947efc 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/mcp.md @@ -37,6 +37,16 @@ For Docker MCP policies: - A matching `forbid` overrides any `permit`, including a permit with `@requireApproval`. +MCP policies are enforced on the MCP gateway path, not by the sandbox network +proxy. During `sbx mcp add`, Docker Sandboxes evaluates the resolved server +definition against `MCP::Action::"register"` before storing the registration. +When a sandbox uses MCP, the gateway evaluates governed MCP requests before +tool calls, resource reads, prompt retrieval, and gateway meta-tool execution. + +Tool and resource listings can include entries that policy later denies at use +time. Use the [MCP policy reference](../reference/mcp-policy.md) for the exact +actions and limitations. + ## Start with a baseline To allow all MCP activity while you build a narrower policy, use an actionless diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 93c4da85085f..b69d2d16de0b 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -26,6 +26,8 @@ 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. +- **MCP gateway traffic:** supported agents connect to a host-side MCP gateway + endpoint. The gateway brokers access to registered MCP servers. What crosses the boundary back to the host: @@ -38,6 +40,12 @@ Everything else is blocked. The agent cannot access your host filesystem localhost, other sandboxes, or any domain not in the allow list. Raw TCP, UDP, and ICMP are blocked at the network layer. +MCP servers are an explicit integration point. Remote MCP servers run outside +Docker Sandboxes, and local stdio MCP servers run on the host, not inside the +sandbox VM. An agent can invoke the tools those servers expose through the MCP +gateway, subject to MCP policies when organization governance is active. Treat +local MCP servers as trusted host integrations. + ![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) ## Isolation layers @@ -91,6 +99,11 @@ 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). +Local stdio MCP servers run outside the sandbox VM. If you register a local MCP +server that starts a host process or host Docker container, that process or +container uses host permissions and host isolation, not sandbox isolation. See +[MCP gateway](../mcp-gateway.md). + ## Organization-wide control On a single developer's machine, security and policy are configured locally — diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 5d72cea66660..b4946ef75f61 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -64,6 +64,12 @@ your host. When the agent runs `docker build` or `docker compose up`, those commands execute against that engine. The agent has no path to your host Docker daemon. +This Docker Engine boundary applies to processes running inside the sandbox VM. +It doesn't apply to local stdio MCP servers registered through the +[MCP gateway](../mcp-gateway.md). Those servers run on the host, outside the +sandbox VM. If a local MCP server starts a Docker container, it uses Docker on +the host. + Each sandbox VM runs its own Docker Engine. The agent runs inside the VM, alongside that engine, and drives it to create containers, all within the VM: From f7fa0843e5ee8c4332d5c5a43d9541f1a8a433f8 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 11:53:23 +0000 Subject: [PATCH 19/35] docs: address mcp governance self-review --- content/manuals/ai/sandboxes/architecture.md | 2 +- content/manuals/ai/sandboxes/faq.md | 15 ++++---- content/manuals/ai/sandboxes/get-started.md | 4 +-- .../governance/access-controls/mcp.md | 4 +++ .../sign-in-enforcement.md | 3 +- .../governance/reference/mcp-policy.md | 36 ++++++++++--------- content/manuals/ai/sandboxes/mcp-gateway.md | 2 +- .../manuals/ai/sandboxes/security/_index.md | 4 +-- .../manuals/ai/sandboxes/security/defaults.md | 5 +-- .../ai/sandboxes/security/isolation.md | 9 ++--- 10 files changed, 47 insertions(+), 37 deletions(-) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 083b432af7a7..a04f801b4cf4 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -52,7 +52,7 @@ $ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run