From 6f2dc86699f63ff032e299eefbb635deb19d19cb Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 11 May 2026 15:28:40 +0200 Subject: [PATCH] docs: document sbx organization governance Co-Authored-By: Claude Opus 4.7 (1M context) Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/ai/sandboxes/_index.md | 5 + content/manuals/ai/sandboxes/faq.md | 20 ++- .../manuals/ai/sandboxes/security/_index.md | 14 ++ .../manuals/ai/sandboxes/security/defaults.md | 4 +- .../ai/sandboxes/security/governance.md | 154 ++++++++++++++++++ .../manuals/ai/sandboxes/security/policy.md | 13 ++ .../manuals/ai/sandboxes/troubleshooting.md | 4 + content/manuals/ai/sandboxes/usage.md | 16 ++ 8 files changed, 226 insertions(+), 4 deletions(-) create mode 100644 content/manuals/ai/sandboxes/security/governance.md diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 7aac1a88d34e..e37615551312 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -18,6 +18,11 @@ sandbox gets its own Docker daemon, filesystem, and network — the agent can build containers, install packages, and modify files without touching your host system. +Organization admins can +[centrally manage sandbox network and filesystem policies](security/governance.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 Install the `sbx` CLI and sign in: diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 615976197086..e2d9b0e2b8e5 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -15,14 +15,28 @@ Signing in gives each sandbox a verified identity, which lets Docker: - **Tie sandboxes to a real person.** Governance matters when agents can build containers, install packages, and push code. Your Docker identity is the anchor. -- **Enable team features down the road.** Shared environments, org-level - policies, audit logs. These all need a concept of "who," and building that in - later would be worse for everyone. +- **Enable team features.** Team-scale features like + [organization governance](security/governance.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 daemons, and talk to Docker services. A Docker account makes that seamless. Your Docker account email is only used for authentication, not marketing. +## Can I enforce sandbox policies across my organization? + +Yes. Admins can centrally manage network and filesystem policies from the +Docker Admin Console. Rules defined there apply to every sandbox in the +organization and take precedence over local rules set with `sbx policy`. +Admins can optionally delegate specific rule types back to local control so +developers can add additional allow rules. + +See [Organization governance](security/governance.md). This feature requires +a separate paid subscription — +[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +to get started. + ## Does the CLI collect telemetry? The `sbx` CLI collects basic usage data about CLI invocations: diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index c80f550b04ab..12a2cb72214e 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -81,6 +81,18 @@ See [Workspace trust](workspace/). see the full list of active rules, and remove entries you don't need. See [Default security posture](defaults/). +## Organization-wide control + +On a single developer's machine, network and filesystem policies are +configured locally with `sbx policy`. Admins can also centrally define those +policies in the Docker Admin Console. When organization governance is active, +the centrally defined rules apply uniformly across every sandbox in the +organization and take precedence over local rules. Admins can optionally +delegate specific rule types back to local control so developers can add +additional allow rules. + +See [Organization governance](governance/) for details. + ## Learn more - [Isolation layers](isolation/): how hypervisor, network, Docker, and @@ -89,4 +101,6 @@ see the full list of active rules, and remove entries you don't need. See blocks - [Credentials](credentials/): how to provide and manage API keys - [Policies](policy/): how to customize network access rules +- [Organization governance](governance/): centrally manage policies across + an organization - [Workspace trust](workspace/): what to review after an agent session diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 49d62355b872..fa7c26869a4f 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -19,7 +19,9 @@ ICMP) are blocked at the network layer. Traffic to private IP ranges, loopback addresses, and link-local addresses is also blocked. Run `sbx policy ls` to see the active allow rules for your installation. To -customize network access, see [Policies](policy.md). +customize network access, see [Policies](policy.md). If your organization +manages sandbox policies centrally, those rules apply on top of the defaults +described here. See [Organization governance](governance.md). ## Workspace defaults diff --git a/content/manuals/ai/sandboxes/security/governance.md b/content/manuals/ai/sandboxes/security/governance.md new file mode 100644 index 000000000000..db758e9d1adf --- /dev/null +++ b/content/manuals/ai/sandboxes/security/governance.md @@ -0,0 +1,154 @@ +--- +title: Organization governance +linkTitle: Org governance +weight: 35 +description: Centrally manage sandbox network and filesystem policies for your organization. +keywords: docker sandboxes, governance, organization policy, AI governance, admin console, network access, filesystem access +--- + +> [!NOTE] +> Sandbox organization governance is available on a separate paid +> subscription. +> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +> to request access. + +{{< summary-bar feature_name="Docker Sandboxes sbx" >}} + +This page covers how to configure organization policies in the Docker Admin +Console under AI governance settings. For local sandbox policies that +individual users configure on their own machine, see [Policies](policy.md). + +Sandbox network and filesystem policies defined in the +[Docker Admin Console](https://app.docker.com/admin) apply uniformly to every +sandbox in the organization. Rules are enforced across all developers' +machines, take precedence over local `sbx policy` rules, and can't be +overridden by individual users. Admins can optionally +[delegate](#delegate-rules-to-local-policy) specific rule types back to local +control so developers can add additional allow rules. + +## Network policies + +### Configuring org-level network rules + +Define network allow and deny rules in the Admin Console under +**AI governance > Network access**. Each rule takes a network target (domain, +wildcard, or CIDR range) and an action (allow or deny). You can add multiple +entries at once, one per line. + +Rules support exact domains (`example.com`), wildcard subdomains +(`*.example.com`), and optional port suffixes (`example.com:443`). + +`example.com` doesn't match subdomains, and `*.example.com` doesn't match +the root domain. Specify both to cover both. + +### Delegate rules to local policy + +When organization governance is active, local rules are ignored by default — +only the organization policy is in effect. Admins can delegate a rule type +back to local policy by turning on the **User defined** setting for that +rule type in AI governance settings. Turning the setting on delegates the +rule type: local `sbx policy` rules of that type are evaluated alongside +organization rules, letting users add hosts to the allowlist from their own +machine. + +If a rule type isn't delegated, local rules of that type still appear in +`sbx policy ls` but with an `inactive` status and a note that the +organization hasn't delegated the rule type to local policy: + +```console +$ sbx policy ls +NAME TYPE ORIGIN DECISION STATUS RESOURCES +balanced-dev network local allow inactive — corporate policy takes precedence and does api.anthropic.com + not delegate this rule type to local policy. +allow AI services network remote allow active api.anthropic.com + api.openai.com +allow Docker services network remote allow active *.docker.com + *.docker.io +``` + +Organization rules show up with `remote` in the `ORIGIN` column. + +Delegated local rules can expand access for domains the organization hasn't +explicitly denied, but can't override organization-level deny rules. This +applies to exact matches and wildcard matches alike; if the organization denies +`*.example.com`, a local allow for `api.example.com` has no effect because the +org-level wildcard deny covers it. + +For example, given an organization policy that allows `api.anthropic.com` +and denies `*.corp.internal`: + +- `sbx policy allow network api.example.com` — works, because the + organization hasn't denied `api.example.com` +- `sbx policy allow network build.corp.internal` — no effect, because the + organization denies `*.corp.internal` + +#### Blocked values in delegated rules + +To prevent overly broad rules from undermining the organization's policy, +certain catch-all values are blocked in delegated local rules: + +- Domain patterns: `*`, `**`, `*.com`, `**.com`, `*.*`, `**.**` +- CIDR ranges: `0.0.0.0/0`, `::/0` + +Scoped wildcards like `*.example.com` are still allowed. If a user attempts +to use a blocked value, `sbx policy` returns an error immediately. + +## 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 by defining filesystem allow +and deny rules in the Admin Console under **AI governance > Filesystem +access**. Each rule takes a path pattern and an action (allow or deny). + +> [!CAUTION] +> Use `**` (double wildcard) rather than `*` (single wildcard) when writing +> path patterns to match path segments recursively. A single `*` only matches +> within a single path segment. For example, `~/**` matches all paths under +> the user's home directory, whereas `~/*` matches only paths directly +> under `~`. + +## Precedence + +Within any layer, deny rules beat allow rules. If a domain matches both, it's +blocked regardless of specificity. Outbound traffic is blocked unless a rule +allows it. + +When organization governance is active, local rules are not evaluated. Only +organization rules set in the Admin Console determine what is allowed or +denied. Organization-level denials can't be overridden locally. + +If the admin [delegates](#delegate-rules-to-local-policy) a rule type to +local policy by turning on the **User defined** setting, local rules of +that type are also evaluated alongside organization rules. Delegated local +rules can expand access for domains the organization hasn't explicitly +denied, but can't override organization-level denials. + +The same model applies to filesystem policies: organization-level rules take +precedence over local behavior. + +To unblock a domain, identify where the deny rule comes from. For local +rules, remove it with `sbx policy rm`. For organization-level rules, update +the rule in the Admin Console. + +## Troubleshooting + +### Policy changes not taking effect + +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` +command. + +> [!WARNING] +> `sbx policy reset` deletes all locally configured policy rules. The command +> prompts for confirmation before proceeding. + +### 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/security/policy.md b/content/manuals/ai/sandboxes/security/policy.md index 3e0eb16fbb82..29c33cbb5dc5 100644 --- a/content/manuals/ai/sandboxes/security/policy.md +++ b/content/manuals/ai/sandboxes/security/policy.md @@ -13,6 +13,10 @@ other. A policy system controls what a sandbox can access over the network. Use the `sbx policy` command to configure network access rules. Rules apply to all sandboxes on the machine. +If your organization manages sandbox policies centrally, organization rules +take precedence over the local rules described on this page. See +[Organization governance](governance.md). + ## Network policies The only way traffic can leave a sandbox is through an HTTP/HTTPS proxy on @@ -47,6 +51,11 @@ Choose a default network policy: You can change your effective policy at any time using `sbx policy allow` and `sbx policy deny`, or start over by running `sbx policy reset`. +> [!NOTE] +> If your organization manages sandbox policies centrally, organization rules +> take precedence over the policy you select here. See +> [Organization governance](governance.md). + ### Non-interactive environments In non-interactive environments such as CI pipelines or headless servers, the @@ -207,6 +216,10 @@ regardless of specificity. To unblock a domain, find the deny rule with `sbx policy ls` and remove it with `sbx policy rm`. +If your organization manages sandbox policies centrally, organization rules +take precedence and local rules are not evaluated unless the admin delegates +that rule type. See [Organization governance](governance.md). + ## Troubleshooting ### Policy changes not taking effect diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index d0a592040c40..8e4c1b3006b3 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -52,6 +52,10 @@ To allow all outbound traffic instead: $ 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](security/governance.md). + ## SSH and other non-HTTP connections fail Non-HTTP TCP connections like SSH can be allowed by adding a policy rule for diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 62ea8590487d..50783c6a3a4b 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -371,6 +371,22 @@ the host service. For example, to verify connectivity from a sandbox shell: $ curl http://host.docker.internal:11434 ``` +## Rolling out to a team + +When rolling sandboxes out across a team, two features handle different +needs: + +- [Custom templates and kits](customize/) let you package reusable agent + configurations, MCP servers, base images, and per-project policies. Every + developer pulls them down with their workspace. +- [Organization governance](security/governance.md) lets admins define + network and filesystem rules in the Docker Admin Console. The rules apply + across every developer's sandboxes and take precedence over local policy. + Available on a separate paid subscription. + +Customization gives developers shared starting points. Governance gives +admins centralized enforcement. + ## What persists While a sandbox exists, installed packages, Docker images, configuration