Skip to content

sbx: restructure governance docs and add API reference #25162

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dvdksn wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

sbx: restructure governance docs and add API reference #25162

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/manuals/ai/sandboxes/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ 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)
[centrally manage sandbox network and filesystem policies](governance/org.md)
from the Docker Admin Console, so the same rules apply uniformly across every
developer's machine. Available on a separate paid subscription.

Expand Down
2 changes: 1 addition & 1 deletion content/manuals/ai/sandboxes/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ layers, and volumes, and this grows as you build images and install packages.

All outbound traffic from the sandbox routes through an HTTP/HTTPS proxy on
your host. Agents are configured to use the proxy automatically. The proxy
enforces [network access policies](security/policy.md) and handles
enforces [network access policies](governance/local.md) and handles
[credential injection](security/credentials.md). See
[Network isolation](security/isolation.md#network-isolation) for how this
works and [Default security posture](security/defaults.md) for what is
Expand Down
6 changes: 3 additions & 3 deletions content/manuals/ai/sandboxes/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,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](security/governance.md), shared environments, and
[organization governance](governance/org.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
Expand All @@ -30,7 +30,7 @@ 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
See [Organization governance](governance/org.md). This feature requires
a separate paid subscription —
[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales)
to get started.
Expand Down Expand Up @@ -99,7 +99,7 @@ $ echo $BRAVE_API_KEY
## Why do agents run without approval prompts?

The sandbox itself is the safety boundary. Because agents run inside an
isolated microVM with [network policies](security/policy.md),
isolated microVM with [network policies](governance/local.md),
[credential isolation](security/credentials.md), and no access to your host
system outside the workspace, the usual reasons for approval prompts (preventing
destructive commands, network access, file modifications) are handled by the
Expand Down
6 changes: 3 additions & 3 deletions content/manuals/ai/sandboxes/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,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](security/policy.md) for a full description of each
rules later. See [Policies](governance/local.md) for a full description of each
option.

> [!NOTE]
Expand Down Expand Up @@ -233,7 +233,7 @@ $ sbx policy allow network -g 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 [Policies](security/policy.md) for the full rule
permitted by default. See [Policies](governance/local.md) for the full rule
set and how to customize it.

## Clean up
Expand Down Expand Up @@ -269,4 +269,4 @@ working tree are unaffected.
with kits
- [Credentials](security/credentials.md) — credential storage and management
- [Workspace trust](security/workspace.md) — review agent changes safely
- [Policies](security/policy.md) — control outbound access
- [Policies](governance/local.md) — control outbound access
39 changes: 39 additions & 0 deletions content/manuals/ai/sandboxes/governance/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
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
---

Sandbox governance covers the policy system that controls what sandboxes can
access over the network and on the filesystem. It operates at two layers that
build on each other:

**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 the Docker Admin Console or
via the [Governance API](api.md). Rules defined at the org level apply
Copy link
Copy Markdown

@docker-agent docker-agent May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Links to api.md will fail — API reference lives at api/index.md (leaf bundle)

Multiple files in content/manuals/ai/sandboxes/governance/ link to api.md as a sibling file:

_index.md line 17:  [Governance API](api.md)
_index.md line 38:  [API reference](api.md)
org.md line 18:     [Governance API](api.md)
org.md line 110:    [API](api.md)
local.md line 158:  [API](api.md)
concepts.md line 19: [Governance API](api.md)

No sibling api.md file exists — the API reference is a leaf bundle at governance/api/index.md. Hugo link checking will report these as broken links. Change the links to api/ (or api/index.md) to correctly point at the bundle's index page.

Copy link
Copy Markdown
Contributor Author

@dvdksn dvdksn May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the link resolves correctly it seems, but that's just luck. Agree that we should link to the actual file.

Copy link
Copy Markdown

@docker-agent docker-agent May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right that Hugo is likely resolving it — Hugo's link resolver is forgiving and will often find the target even with imprecise paths. But as you noted, relying on that is fragile. Using api/ (or api/index.md) makes the intent explicit and ensures the link works predictably across different contexts (ref lookups, relrefs, etc.).

Thanks for confirming the fix makes sense!

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 extend the org policy with additional allow rules.
See [Organization policy](org.md).

> [!NOTE]
> Organization governance is available on a separate paid subscription.
> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales)
> to request access.

## Learn more

- [Policy concepts](concepts.md): resource model, rule syntax, 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
- [Monitoring](monitoring.md): inspect active rules and monitor sandbox
network traffic with `sbx policy ls` and `sbx policy log`
- [API reference](api.md): manage org policies programmatically via the
Governance API
Loading