sbx: restructure governance docs and add API reference

content/manuals/ai/sandboxes/_index.md

@@ -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.
 

content/manuals/ai/sandboxes/architecture.md

@@ -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

content/manuals/ai/sandboxes/faq.md

@@ -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
@@ -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.
@@ -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

content/manuals/ai/sandboxes/get-started.md

@@ -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]
@@ -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
@@ -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

content/manuals/ai/sandboxes/governance/_index.md

@@ -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](/reference/api/ai-governance/). Rules defined at the org level 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 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](/reference/api/ai-governance/): manage org policies
+  programmatically via the Governance API

content/manuals/ai/sandboxes/governance/api.md

@@ -0,0 +1,10 @@
+---
+title: AI Governance API
+linkTitle: AI Governance
+description: Programmatic management of Docker AI Governance policies and rules via HTTP+JSON.
+weight: 30
+build:
+  render: never
+sidebar:
+  goto: /reference/api/ai-governance/
+---

content/manuals/ai/sandboxes/governance/concepts.md

@@ -0,0 +1,106 @@
+---
+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
+---
+
+## Resource model
+
+Docker sandbox governance is built around two resource types: **policies** and
+**rules**.
+
+A **policy** is a named collection of rules that controls sandbox access.
+Policies exist at different levels:
+
+- **Local**: configured per machine using the `sbx policy` CLI. Applies to
+  sandboxes on that machine only.
+- **Organization**: configured in the Docker Admin Console or via the
+  [Governance API](/reference/api/ai-governance/). Applies uniformly across every sandbox in the
+  organization.
+- **Team**: applies to sandboxes used by a specific team within an
+  organization. Coming soon.
+
+When multiple levels are active, organization policies take precedence over
+local policies. See [Precedence](#precedence).
+
+A **rule** is the unit of access control within a policy. Each rule has:
+
+- **Name**: a human-readable label
+- **Actions**: the type of access the rule controls
+- **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`.
+
+## Rule syntax
+
+### Network rules
+
+Network rules use the actions `connect:tcp` and `connect:udp`. Resources are
+hostnames, CIDR ranges, or ports.
+
+**Hostname patterns**
+
+| Pattern | Example | Matches |
+| ------- | ------- | ------- |
+| Exact hostname | `example.com` | `example.com` only, not subdomains |
+| Single-level wildcard | `*.example.com` | One subdomain level: `api.example.com` |
+| Multi-level wildcard | `**.example.com` | Any depth: `api.example.com`, `v2.api.example.com` |
+| Hostname with port | `example.com:443` | `example.com` on port 443 only |
+
+`example.com` and `*.example.com` don't cover each other. Specify both if you
+need to match the root domain and its subdomains.
+
+**CIDR ranges**
+
+Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`,
+`2001:db8::/32`.
+
+### Filesystem rules
+
+Filesystem rules use the actions `read` and `write`. Resources are host paths
+that sandboxes can mount as workspaces.
+
+| Pattern | Example | Matches |
+| ------- | ------- | ------- |
+| Exact path | `/data` | `/data` only |
+| Segment wildcard | `/data/*` | `/data/project`, one path segment only, not subdirectories |
+| Recursive wildcard | `/data/**` | `/data/project`, `/data/project/src`, any depth |
+
+Use `**` when you intend to match a directory tree recursively. A single `*`
+only matches within one path segment and won't cross directory boundaries.
+For example, `~/**` matches all paths under the home directory, while `~/*`
+matches only direct children of `~`.
+
+## Rule evaluation
+
+All rules in a policy are evaluated against every request. The outcome follows
+two principles:
+
+**Deny wins.** If any rule matches with `decision: deny`, the request is
+denied regardless of any matching allow rules.
+
+**Default deny.** Outbound traffic is blocked unless an explicit allow rule
+matches.
+
+These principles apply within each policy level independently. A deny in an
+organization policy can't be overridden by a local allow.
+
+## Precedence
+
+When only local policies are active, local rules determine what sandboxes can
+access.
+
+When organization governance is active:
+
+- Organization rules take effect across all developer machines.
+- Local rules are not evaluated by default.
+- Admins can [delegate](org.md#delegate-rules-to-local-policy) specific rule
+  types back to local control. Delegated local rules can expand access for
+  targets the organization hasn't explicitly denied, but can't override
+  organization-level deny rules.
+
+Within any level, deny rules beat allow rules regardless of specificity or
+order.

content/manuals/ai/sandboxes/governance/local.md

@@ -0,0 +1,159 @@
+---
+title: Local policy
+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/
+---
+
+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.
+
+Local rules work differently depending on whether your organization uses
+governance:
+
+- **No org governance**: local rules fully control what sandboxes can access.
+- **Org governance, delegation enabled**: local rules of the delegated type
+  are evaluated alongside org rules. You can extend access for domains your org
+  hasn't explicitly denied, but org-level denials still take precedence.
+- **Org governance, no delegation**: local rules are inactive. `sbx policy
+  allow` and `sbx policy deny` have no effect for that rule type.
+
+See [Organization policy](org.md) for how admins configure delegation.
+
+For domain patterns, wildcards, CIDR ranges, and filesystem path syntax, see
+[Policy concepts](concepts.md#rule-syntax).
+
+## Default preset
+
+The only way traffic can leave a sandbox is through an HTTP/HTTPS proxy on
+your host, which enforces access rules on every outbound request. Non-HTTP TCP
+traffic, including SSH, can be allowed by adding a policy rule for the
+destination IP and port (for example, `sbx policy allow network -g
+"10.1.2.3:22"`). UDP and ICMP are blocked at the network layer and can't be
+unblocked with policy rules.
+
+On first start, and after running `sbx policy reset`, the daemon prompts you
+to choose a network preset:
+
+```plaintext
+Choose a default network policy:
+
+     1. Open         — All network traffic allowed, no restrictions.
+     2. Balanced     — Default deny, with common dev sites allowed.
+     3. Locked Down  — All network traffic blocked unless you allow it.
+
+  Use ↑/↓ to navigate, Enter to select, or press 1–3.
+```
+
+| Preset | Description |
+| ------ | ----------- |
+| Open | All outbound traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network -g "**"`. |
+| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. |
+| Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need. |
+
+The **Balanced** preset's baseline allowlist is a good starting point for most
+workflows. Run `sbx policy ls` to see exactly which rules it includes.
+
+> [!NOTE]
+> If your organization manages sandbox policies centrally, organization rules
+> take precedence over the preset you select here. See
+> [Organization policy](org.md).
+
+### Non-interactive environments
+
+In non-interactive environments such as CI pipelines or headless servers, the
+interactive prompt can't be displayed. Use `sbx policy set-default` to set the
+preset before running any other `sbx` commands:
+
+```console
+$ sbx policy set-default balanced
+```
+
+Available values are `allow-all`, `balanced`, and `deny-all`.
+
+## Managing rules
+
+Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and
+[`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add or restrict access
+on top of the active preset. Changes take effect immediately. Pass `-g` to
+apply a rule globally to all sandboxes:
+
+```console
+$ sbx policy allow network -g api.anthropic.com
+$ sbx policy deny network -g ads.example.com
+```
+
+Pass a sandbox name to scope a rule to one sandbox:
+
+```console
+$ sbx policy allow network my-sandbox api.example.com
+$ sbx policy deny network my-sandbox ads.example.com
+```
+
+Specify multiple hosts in one command with a comma-separated list:
+
+```console
+$ sbx policy allow network -g "api.anthropic.com,*.npmjs.org,*.pypi.org"
+```
+
+Remove a rule by resource or by rule ID:
+
+```console
+$ sbx policy rm network -g --resource ads.example.com
+$ sbx policy rm network -g --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
+```
+
+To remove a sandbox-scoped rule, include the sandbox name:
+
+```console
+$ sbx policy rm network my-sandbox --resource api.example.com
+```
+
+To inspect which rules are active and where they come from, use
+`sbx policy ls`. See [Monitoring](monitoring.md).
+
+### Resetting
+
+To remove all custom rules and start fresh with a new preset, use
+`sbx policy reset`:
+
+```console
+$ sbx policy reset
+```
+
+This deletes the local policy store and stops the daemon. When the daemon
+restarts on the next command, you are prompted to choose a new preset. Running
+sandboxes stop when the daemon shuts down. Pass `--force` to skip the
+confirmation prompt:
+
+```console
+$ sbx policy reset --force
+```
+
+## Troubleshooting
+
+### Local rules have no effect
+
+If rules you add with `sbx policy allow` or `sbx policy deny` don't change
+sandbox behavior, your organization likely has governance enabled without
+delegating that rule type to local control. Run `sbx policy ls` to check: if
+the output starts with a `Governance: managed by <org>` header, org governance
+is active. If your rules appear with `inactive` status, org governance is
+suppressing them.
+
+To use local rules alongside org rules, ask your admin to enable delegation for
+the relevant rule type in the Admin Console. See
+[Delegate rules to local policy](org.md#delegate-rules-to-local-policy).
+
+### A domain is still blocked after adding an allow rule
+
+If a domain remains blocked after you add a local allow rule, an org-level deny
+rule may be covering it. [Delegation](org.md#delegate-rules-to-local-policy)
+lets local rules expand access, but org deny rules always take precedence. Run `sbx policy ls` to check whether a rule
+with `remote` origin and `deny` decision matches the domain. If so, the block
+can only be lifted by updating the org policy in the Admin Console or via the
+[API](/reference/api/ai-governance/).
+