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,79 @@
+---
+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 limits you set. It has two parts:
+local policy, which applies to one machine, and organization governance, which
+applies across an organization and also records what sandboxes did in audit
+logs.
+
+> [!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).
+
+## Who sets the rules
+
+A rule allows or denies one kind of access, such as a network destination, and
+a policy is a set of rules. The two parts of governance differ in who sets the
+rules and who the rules apply to.
+
+### You, with local policy and kits
+
+[Local policy](local/_index.md) is the policy you set on your machine with the
+`sbx policy` CLI. You start from a preset, then allow or block the network
+destinations your sandboxes need. Local policy is available to everyone on their
+machine.
+
+The kits your sandboxes use, including the built-in agent kits, can add network
+rules too, such as the API endpoints an agent needs. Kit rules work like the
+rules you add yourself.
+
+### Your organization, with organization governance
+
+With [organization governance](organization/_index.md), administrators set
+policies for the members of their organization who hold an AI Governance
+license. Organization policies control network access, the host paths
+sandboxes can mount, and MCP activity. Organization governance requires an
+[AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md).
+
+## How the rules are enforced
+
+When a sandbox tries to reach a network destination, the request is checked
+against your rules. With organization policy, the same check also applies when
+a sandbox mounts a host path or uses an MCP server.
+
+The rules are enforced outside the sandbox, so an agent running inside it
+can't change or bypass them. For where network rules are enforced as a request
+leaves the sandbox, see [Networking](../sandboxes/architecture.md#networking).
+
+Local, kit, and organization rules combine differently depending on whether an
+organization policy is enforced for you. 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).
+
+## 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 licenses, sign-in enforcement, policies, and audit logs for your
+organization.

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

@@ -0,0 +1,92 @@
+---
+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 lets you, the developer, decide which network destinations the
+sandboxes on your machine can reach. You manage it with the `sbx policy`
+command. You start from a preset, add rules of your own, and kits add the rules
+their agents need. Local policy covers network access only. Unless an
+organization policy applies to you, sandboxes can mount any host path and use
+any MCP server you register.
+
+## How local policy works
+
+Rules usually match a hostname, and HTTP traffic can also be matched by method,
+path, and query parameters. Non-HTTP TCP traffic, including SSH, can be allowed
+with a hostname rule, for example `sbx policy allow network "myhost:22"`, or
+with an address-based rule. UDP requires the experimental feature and policy
+rules described in
+[Allow outbound UDP](network-rules.md#allow-outbound-udp). ICMP is blocked.
+
+For domain patterns, wildcards, and CIDR ranges, 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, code hosts, container registries, and common cloud services. |
+| 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. 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).
+
+## Add rules from kits
+
+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. Kit rules work like the
+rules you add yourself, and they apply under any preset, including **Locked
+Down**. A preset isn't an explicit deny rule, so it doesn't override the allow
+rules a kit adds.
+
+To list the rules a kit added to a sandbox, see
+[Filter the listing](inspect.md#filter-the-listing). For more details on kits,
+see [Use kits](../../sandboxes/customize/use-kits.md).
+
+## How rules combine
+
+Without organization governance, your rules and your kits' rules combine: a
+destination is allowed if any rule allows it, and a deny rule from any source
+takes precedence over an allow 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).
+
+Approvals, inspection, and testing work the same way whether a rule comes from
+you, a kit, or your organization.
+
+## 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: an organization network 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. Under organization governance 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).