ai-gov: rearrange and feedback

content/get-started/tutorials/admin-set-up.md

@@ -84,5 +84,5 @@ Continue with these guides when you're ready to expand the deployment:
   for additional policies and deployment controls
 - [Set up SSO and provisioning](/manuals/security/authentication/single-sign-on/_index.md)
   for centralized identity management
-- [Govern Docker Sandboxes](/manuals/ai/sandboxes/governance/_index.md) for
-  organization-wide agent policies
+- [Govern Docker Sandboxes](/manuals/ai/governance/organization/_index.md)
+  for organization-wide agent policies

content/get-started/tutorials/run-an-agent.md

@@ -99,7 +99,7 @@ The first time you run a sandbox, `sbx` asks you to choose a default network
 policy. This policy controls which external services your sandboxes can reach.
 Select **Balanced** to permit common development services and block other
 destinations by default. You can change these rules later with
-[`sbx policy`](/manuals/ai/sandboxes/governance/access-controls/local.md).
+[`sbx policy`](/manuals/ai/governance/local/network-rules.md).
 
 The built-in integrations start coding agents in their full-autonomy mode. For
 example, Codex bypasses approvals, Claude Code skips permission prompts, and

content/guides/firecrawl-sandbox-kit.md

@@ -170,10 +170,10 @@ API, including structured extraction with a schema, see the
 
 Without organization governance, your default network policy and kit-defined
 rules determine which domains the sandbox can access. Under organization
-governance, organization policy controls which domains can be allowed; local
-and kit-defined allow rules are inactive, while deny rules can still restrict
+governance, organization policy controls which domains can be allowed; local and
+kit-defined allow rules are inactive, while deny rules can still restrict
 access. See
-[Network policy precedence](/manuals/ai/sandboxes/governance/concepts.md#precedence).
+[How organization policy relates to local and kit rules](/manuals/ai/governance/organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules).
 
 The Firecrawl kit requests access to PyPI during installation and
 `api.firecrawl.dev` at runtime. Its credential declaration tells the proxy to

content/manuals/_index.md

@@ -27,6 +27,10 @@ params:
     description: Create and manage cloud sandboxes from your applications.
     icon: code-bracket
     link: /ai/sandboxes-api/
+  - title: Sandbox governance
+    description: Control what agents in sandboxes can reach, and audit what they did.
+    icon: lock-closed
+    link: /ai/governance/
   - title: MCP Catalog and Toolkit
     description: Augment your AI workflow with MCP servers.
     icon: /icons/toolkit.svg

content/manuals/accounts/organization/activity-logs.md

@@ -27,7 +27,7 @@ Organization owners and members with a custom role that includes the
 > Use activity logs for an admin audit trail of your organization and
 > repositories, including AI Governance policy and settings changes. For
 > enforcement events, such as policy decisions and sandbox sessions, see
-> [AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md).
+> [AI Governance Audit Logs](/manuals/ai/governance/organization/audit/_index.md).
 
 ## Access activity logs
 
@@ -234,7 +234,7 @@ The following table lists Offload events that cover lease start and end.
 The following table lists governance events that cover the AI Governance
 admin audit trail, such as policy and settings changes. For enforcement
 events, such as policy decisions and sandbox sessions, see
-[AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md).
+[AI Governance Audit Logs](/manuals/ai/governance/organization/audit/_index.md).
 
 | Event | Description |
 |:------|:------------|
@@ -249,7 +249,7 @@ events, such as policy decisions and sandbox sessions, see
 
 - [Roles and permissions](/manuals/security/roles-and-permissions/_index.md) for
   the **View activity logs** permission and custom roles
-- [AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md) for
+- [AI Governance Audit Logs](/manuals/ai/governance/organization/audit/_index.md) for
   enforcement events such as policy decisions and sandbox sessions
 - [Audit logs API](/reference/api/hub/latest/#tag-audit-logs) to query events
   programmatically

content/manuals/agentic-platform/policies.md

@@ -58,8 +58,11 @@ removed, and review the allow rules in the remaining policies and kit.
 If the combined allow list contains any rules, destinations outside that list
 are blocked. This default behavior isn't an explicit deny rule: adding an
 allow rule in another policy permits the matching destinations. If the
-combined allow list is empty or absent, the sandbox can reach any destination
-except those blocked by deny rules.
+combined allow list is empty or absent, your account's default network mode
+applies. The default is deny all, so the sandbox can't reach any destination
+until an allow rule permits it. Accounts created before deny all became the
+default have an explicit allow all default instead, so their sandboxes can
+reach any destination except those blocked by deny rules.
 
 ## Policy rules
 

content/manuals/ai-overview.md

@@ -3,7 +3,7 @@ title: Docker AI overview
 linkTitle: Overview
 description: Docker's AI tools help you build, run, and manage AI-powered applications and workflows.
 weight: 1
-keywords: docker, ai, gordon, docker agent, sandboxes, agentic platform, model runner, mcp
+keywords: docker, ai, gordon, docker agent, sandboxes, governance, agentic platform, model runner, mcp
 params:
   sidebar:
     group: AI and agents
@@ -17,6 +17,7 @@ Each tool serves a different purpose.
 | I want to...                                                    | Use                                                      | Interface        |
 | --------------------------------------------------------------- | -------------------------------------------------------- | ---------------- |
 | Run coding agents in isolated environments                      | [Docker Sandboxes](./ai/sandboxes/)                      | `sbx`            |
+| Control what sandbox agents can reach, and audit what they did  | [Sandbox governance](./ai/governance/)                   | `sbx policy`, Docker Home |
 | Run agents in cloud sandboxes through a web Console | [Docker Agentic Platform](./agentic-platform/_index.md) (experimental) | Web Console |
 | Get AI help with Docker tasks (containers, images, Dockerfiles) | [Gordon](./ai/gordon/)                                   | `docker ai`      |
 | Run AI models locally with an OpenAI-compatible API             | [Model Runner](./ai/model-runner/)                       | `docker model`   |

content/manuals/ai/governance/_index.md

@@ -0,0 +1,67 @@
+---
+title: AI governance
+weight: 20
+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
+params:
+  sidebar:
+    group: AI and agents
+aliases:
+  - /ai/sandboxes/governance/
+  - /ai/sandboxes/governance/access-controls/
+  - /ai/sandboxes/governance/monitor-and-enforce/
+  - /ai/sandboxes/governance/reference/
+---
+
+Agents in [Docker Sandboxes](../sandboxes/_index.md) work on their own. They
+install packages, call APIs, and use tools without asking you first.
+Governance lets an agent work freely within rules that limit what it can
+access. The rules are enforced outside the sandbox, so the agent can't change or
+bypass them. They come from three sources: your local policy, the kits your
+sandboxes use, and your organization.
+
+> [!NOTE]
+> This section covers sandboxes that run on your machine. Cloud sandboxes use
+> the same kinds of allow and deny rules, but they don't use local policy or
+> organization policy. They use
+> [cloud network policy](../sandboxes/cloud/network-policy.md), which is stored in your
+> Docker account and managed with `sbx --cloud policy` or in the Docker Agentic
+> Platform [Console](/manuals/agentic-platform/policies.md).
+
+## Where the rules come from
+
+You set your local policy and choose which kits your sandboxes use. Your
+organization's administrators set its organization policies.
+
+### Local policy and kits
+
+With [local policy](local/_index.md), you decide which network destinations
+your sandboxes can reach. You start from a preset, then use `sbx policy` to
+allow what your work needs and block what sandboxes shouldn't reach.
+
+[Kits](../sandboxes/customize/use-kits.md), including the built-in agent kits,
+bring rules of their own. Whoever authors a kit defines the rules its agent
+needs, such as access to the agent's API, and the rules come with the kit
+whether you build it yourself or pull it from a registry or Git repository.
+They apply only to the sandboxes that use the kit.
+
+### Organization governance
+
+If your organization has an
+[AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md),
+administrators set rules centrally with
+[organization governance](organization/_index.md). Their policies apply to the
+sandboxes of licensed members and go beyond the network, controlling which
+host paths sandboxes can mount and which MCP servers they can use.
+Administrators then review the decisions those policies make in audit logs.
+
+## Get started
+
+If you're a developer, start with
+[Try out local policy](local/try-it-out.md), an example that allows and blocks
+destinations for one sandbox.
+
+If you're an administrator, start with
+[Get started with organization governance](organization/get-started.md) to set
+up policies, audit logs, licenses, sign-in enforcement, and Docker Sandboxes
+for your organization.

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

@@ -0,0 +1,94 @@
+---
+title: Local policy
+weight: 10
+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/access-controls/local/
+  - /ai/sandboxes/governance/local/
+---
+
+Local policy is how you, the developer, control which network destinations the
+sandboxes on your machine can reach. You start from a preset that sets how much
+access sandboxes have, then use the `sbx policy` command to allow what your work
+needs and block what sandboxes shouldn't reach. If a sandbox uses a kit, the kit
+brings the rules its agent needs, so you don't have to add them yourself.
+
+Local policy covers only the network. You already decide which host paths a
+sandbox mounts when you create it, and which MCP servers it can use when you
+register them. Unless an organization policy applies to you, nothing restricts
+those choices.
+
+## How local policy works
+
+Every outbound TCP request from a sandbox, including HTTP and SSH, passes
+through a proxy on your host, which checks the request against your rules
+before it leaves your machine. A rule names a destination and says whether to
+allow or deny it. Other protocols are blocked by default. UDP needs the
+experimental feature described in
+[Allow outbound UDP](network-rules.md#allow-outbound-udp), and ICMP is always
+blocked.
+
+Most rules match a hostname, such as `api.github.com`, or an IP address or CIDR
+range. For HTTP traffic, a rule can also match the request's method, path, and
+query parameters, so you can allow part of an API without allowing all of it. A
+rule for other TCP traffic, such as SSH, can name a port, for example
+`sbx policy allow network "myhost:22"`. For the full pattern syntax, including
+wildcards, see [Network and HTTP rule syntax](../reference/network-rules.md).
+
+## Start from a preset
+
+Local policy starts from a network preset, which sets how much network access
+sandboxes have before you add rules of your own. If you haven't chosen a preset,
+the CLI prompts you to choose one when you run a sandbox in an interactive
+terminal. If a preset is already set, including one carried over from an
+earlier installation, the CLI uses it without prompting.
+
+| Preset      | CLI value   | Description                                                                                                                                                                                 |
+| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Open        | `allow-all` | All outbound TCP traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`.                                                                       |
+| Balanced    | `balanced`  | Default deny, with a baseline allowlist covering AI provider APIs, package managers, OS package repositories, code hosts, container registries, cloud services, and certificate validation. |
+| Locked Down | `deny-all`  | No baseline allow rules. Destinations need an allow rule from you or a kit.                                                                                                                 |
+
+The **Balanced** preset's baseline allowlist is a good starting point for most
+workflows. After you choose it, run `sbx policy ls` to see exactly which rules
+it includes.
+
+To set the preset without the prompt, or to choose again later, see
+[Set or reset the preset](network-rules.md#set-or-reset-the-preset).
+
+## Add your own rules
+
+The preset sets your global rules, which apply to every sandbox on your
+machine. On top of the preset, you can add your own allow and deny rules,
+either globally or scoped to one sandbox by name. For more details, see
+[Manage local network rules](network-rules.md).
+
+## Use kits that add rules
+
+Kits, including the built-in agent kits, can add network rules to the sandboxes
+that use them, such as the API endpoints an agent needs. For more details, see
+[Use kits](../../sandboxes/customize/use-kits.md).
+
+## How rules combine
+
+Without organization governance, your rules and kit rules combine: a
+destination is allowed if any rule allows it, and a deny rule from any source
+takes precedence over an allow rule. Kit rules apply under any preset,
+including **Locked Down**, because a preset isn't an explicit deny rule.
+
+How a request that no rule matches is handled depends on your preset. Under
+**Open**, every destination is allowed. Under **Balanced** and **Locked Down**,
+the request is blocked and asks for your approval instead of being denied
+outright, so you can open access to each destination as a sandbox needs it.
+For more details, see [Respond to approval requests](approvals.md).
+
+When an organization policy is enforced for you, it changes which of your
+local rules apply. For more details, see
+[How organization policy relates to local and kit rules](../organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules).
+
+## Try it out
+
+[Try out local policy](try-it-out.md) walks you through an example that allows
+and blocks destinations for one sandbox.

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

@@ -0,0 +1,113 @@
+---
+title: Respond to approval requests
+linkTitle: Respond to approvals
+weight: 30
+description: Approve or dismiss sandbox network requests that need your confirmation, under local policy or an organization policy.
+keywords: docker sandboxes, approval required, approve network access, sbx policy approval, local policy, organization policy
+---
+
+When a sandbox tries to reach a destination that needs your approval, the
+request is blocked and `sbx` records an approval request. Approve it to allow
+the destination for that sandbox, or dismiss it to keep the destination
+blocked. You respond the same way whether local policy or an organization
+policy asks for the approval.
+
+A request needs approval in these cases:
+
+- Local policy: under the Balanced or Locked Down
+  [preset](_index.md#start-from-a-preset), a sandbox reaches a destination that
+  no rule allows or denies. A request never asks for approval under the Open
+  preset, because Open allows every destination. This applies only when no
+  organization policy is enforced for you.
+- Organization policy: a network access policy allows the destination
+  but requires approval first. For more details, see
+  [Approval-required access](../organization/policies/network.md#approval-required-access).
+
+A request that a deny rule matches is blocked without
+asking.
+
+## List pending approval requests
+
+When a request needs approval, the sandbox receives a message naming the
+destination:
+
+```plaintext
+Approval required for api.example.com.
+
+Review and respond with:
+  sbx policy approval ls
+```
+
+List the destinations waiting for a response:
+
+```console
+$ sbx policy approval ls
+APPROVAL                                              SANDBOX      TITLE                 DETAIL                                                                              OPTIONS
+network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY   my-sandbox   api.example.com:443   Protocol: TCP Resource type: domain approval required by policy "default network"   allow (Allow), dismiss (Dismiss)
+```
+
+Each entry names the destination, the sandbox that asked for it, and why it
+needs approval. When an organization policy is enforced for you, that reason
+names the policy, as shown. Under local policy, the reason is that no matching allow rule covers the
+destination. A request that an HTTP rule matches also shows the method and
+path, such as `GET api.example.com:443/v1/data`.
+
+Repeated attempts collapse into a single entry, so a sandbox retrying in a loop
+leaves one request to answer, not a queue of duplicates.
+
+To see the details of a single entry, pass its ID to
+`sbx policy approval inspect`:
+
+```console
+$ sbx policy approval inspect network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY
+```
+
+## Approve or dismiss a request
+
+Respond by selecting one of the options the entry offers:
+
+```console
+$ sbx policy approval respond network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY --option allow
+```
+
+Choosing `allow` grants access to that destination. Choosing `dismiss` leaves
+it blocked, and the destination is requested again the next time the sandbox
+tries to reach it.
+
+The request that triggered the approval doesn't wait for your answer. It's
+denied, and approving the destination affects later requests. Agents that
+retry a failed request pick up the new access on their next attempt. For other
+tools, run the operation again.
+
+Approving records a rule that allows the destination the sandbox actually asked
+for, scoped to the sandbox that asked:
+
+- The rule covers one destination, not a pattern. A policy that allows
+  `*.example.com` with approval asks about `api.example.com` and
+  `cdn.example.com` separately.
+- A destination includes its port, so `api.example.com:443` and
+  `api.example.com:8443` are approved separately.
+- Another sandbox reaching the same destination asks again.
+
+When an [HTTP rule](../reference/network-rules.md#http-method-and-path) in the
+policy matches the request, approving covers the method and exact path the
+sandbox requested rather than the whole destination. `GET /v1/data` and
+`POST /v1/data` on the same host are approved separately. A request whose
+method or path can't be recorded as a rule, such as a path with
+percent-encoding, is blocked without an entry to respond to.
+
+## Review and remove approved destinations
+
+Approved destinations stay allowed until you remove the rule. List them:
+
+```console
+$ sbx policy ls --wide --created-via approval
+```
+
+Remove one by its rule ID, the same way as any other local rule:
+
+```console
+$ sbx policy rm network --sandbox my-sandbox --id <RULE_ID>
+```
+
+For more details, see [Remove a rule](network-rules.md#remove-a-rule).