diff --git a/.github/workflows/sync-custom-role-permissions.yml b/.github/workflows/sync-custom-role-permissions.yml
new file mode 100644
index 0000000000..d3b50559e7
--- /dev/null
+++ b/.github/workflows/sync-custom-role-permissions.yml
@@ -0,0 +1,71 @@
+name: Sync custom role permissions
+
+# Vendors the IAM source of truth (custom-role-metadata.yaml in
+# docker/iam-services) into data/custom_role_permissions.yaml and opens a PR for
+# review. The permissions reference page renders that file with an inline
+# shortcode, so the site build never needs access to the private upstream
+# repository.
+# Triggered by the "Sync docs permissions" workflow in docker/iam-services when
+# that file changes on main; can also be run manually.
+
+on:
+ workflow_dispatch:
+ inputs:
+ ref:
+ description: "The git ref in docker/iam-services to read custom-role-metadata.yaml from."
+ type: string
+ required: false
+ default: "main"
+
+concurrency:
+ group: sync-custom-role-permissions
+ cancel-in-progress: true
+
+jobs:
+ sync:
+ name: Sync custom role permissions data
+ runs-on: ubuntu-latest
+ steps:
+ - id: setup
+ uses: docker/actions/setup@707e5d98a430d92e8e6c2d34faa5bfb2a9149e9b
+ with:
+ app_id: ${{ secrets.HUB_PLATFORM_APP_ID }}
+ app_private_key: ${{ secrets.HUB_PLATFORM_APP_PRIVATE_KEY }}
+
+ - name: Checkout docs
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+ with:
+ token: ${{ steps.setup.outputs.token }}
+ show-progress: false
+
+ - name: Vendor custom-role-metadata.yaml from iam-services
+ env:
+ GH_TOKEN: ${{ steps.setup.outputs.token }}
+ REF: ${{ inputs.ref }}
+ run: |
+ gh api \
+ "repos/docker/iam-services/contents/internal/services/access_control/config/custom-role-metadata.yaml?ref=${REF}" \
+ -H "Accept: application/vnd.github.raw+json" \
+ > data/custom_role_permissions.yaml
+
+ - name: Create PR
+ uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0
+ with:
+ token: ${{ steps.setup.outputs.token }}
+ title: "⚙️ Sync custom role permissions data"
+ body: |
+ Automatically generated from
+ [`custom-role-metadata.yaml`](https://github.com/docker/iam-services/blob/main/internal/services/access_control/config/custom-role-metadata.yaml)
+ in `docker/iam-services` by the **Sync custom role permissions**
+ workflow, triggered by a change to that file.
+
+ Only `data/custom_role_permissions.yaml` is updated. The
+ permissions reference page renders it with an inline shortcode. If
+ this change is unexpected or shouldn't ship yet, close this PR —
+ the workflow will re-open it the next time the source changes.
+ commit-message: "Sync custom role permissions data"
+ sign-commits: true
+ add-paths: |
+ data/custom_role_permissions.yaml
+ branch: chore/sync-custom-role-permissions
+ delete-branch: true
diff --git a/Dockerfile b/Dockerfile
index 225a58be95..1d9b745084 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -5,7 +5,7 @@ ARG ALPINE_VERSION=3.23
ARG GO_VERSION=1.27
ARG HTMLTEST_VERSION=0.17.0
ARG VALE_VERSION=3.17.0
-ARG HUGO_VERSION=0.163.0
+ARG HUGO_VERSION=0.169.0
ARG NODE_VERSION=24
ARG PAGEFIND_VERSION=1.5.2
ARG TARGETARCH
diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose.md
index 50ebfba473..d709074e1f 100644
--- a/_vendor/github.com/docker/compose/v5/docs/reference/compose.md
+++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose.md
@@ -215,9 +215,13 @@ Profiles can also be set by `COMPOSE_PROFILES` environment variable.
### Configuring parallelism
-Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
+Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls or builds.
Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file
-one at a time. This can also be used to control build concurrency.
+one at a time.
+
+Limiting build concurrency requires Buildx 0.38.0 or later. When services are linked by
+`additional_contexts` (`service:`), Buildx rejects a limit lower than the number of images to
+build, so Compose ignores it with a warning.
Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_push.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_push.md
index 0efc48c46d..20da97c98c 100644
--- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_push.md
+++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_push.md
@@ -22,12 +22,12 @@ services:
### Options
-| Name | Type | Default | Description |
-|:-------------------------|:-------|:--------|:-------------------------------------------------------|
-| `--dry-run` | `bool` | | Execute command in dry run mode |
-| `--ignore-push-failures` | `bool` | | Push what it can and ignores images with push failures |
-| `--include-deps` | `bool` | | Also push images of services declared as dependencies |
-| `-q`, `--quiet` | `bool` | | Push without printing progress information |
+| Name | Type | Default | Description |
+|:-------------------|:-------|:--------|:---------------------------------------------------------------------------|
+| `--dry-run` | `bool` | | Execute command in dry run mode |
+| `--ignore-missing` | `bool` | | Skip images that are not available locally instead of failing to push them |
+| `--include-deps` | `bool` | | Also push images of services declared as dependencies |
+| `-q`, `--quiet` | `bool` | | Push without printing progress information |
diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md
index 14fb854792..f7681f6c9c 100644
--- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md
+++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md
@@ -57,33 +57,34 @@ specified in the service configuration.
### Options
-| Name | Type | Default | Description |
-|:------------------------|:--------------|:---------|:---------------------------------------------------------------------------------|
-| `--build` | `bool` | | Build image before starting container |
-| `--cap-add` | `list` | | Add Linux capabilities |
-| `--cap-drop` | `list` | | Drop Linux capabilities |
-| `-d`, `--detach` | `bool` | | Run container in background and print container ID |
-| `--dry-run` | `bool` | | Execute command in dry run mode |
-| `--entrypoint` | `string` | | Override the entrypoint of the image |
-| `-e`, `--env` | `stringArray` | | Set environment variables |
-| `--env-from-file` | `stringArray` | | Set environment variables from file |
-| `-i`, `--interactive` | `bool` | `true` | Keep STDIN open even if not attached |
-| `-l`, `--label` | `stringArray` | | Add or override a label |
-| `--name` | `string` | | Assign a name to the container |
-| `--no-deps` | `bool` | | Don't start linked services |
-| `-T`, `--no-tty` | `bool` | `true` | Disable pseudo-TTY allocation (default: auto-detected) |
-| `-p`, `--publish` | `stringArray` | | Publish a container's port(s) to the host |
-| `--pull` | `string` | `policy` | Pull image before running ("always"\|"missing"\|"never") |
-| `-q`, `--quiet` | `bool` | | Don't print anything to STDOUT |
-| `--quiet-build` | `bool` | | Suppress progress output from the build process |
-| `--quiet-pull` | `bool` | | Pull without printing progress information |
-| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file |
-| `--rm` | `bool` | | Automatically remove the container when it exits |
-| `-P`, `--service-ports` | `bool` | | Run command with all service's ports enabled and mapped to the host |
-| `--use-aliases` | `bool` | | Use the service's network useAliases in the network(s) the container connects to |
-| `-u`, `--user` | `string` | | Run as specified username or uid |
-| `-v`, `--volume` | `stringArray` | | Bind mount a volume |
-| `-w`, `--workdir` | `string` | | Working directory inside the container |
+| Name | Type | Default | Description |
+|:------------------------|:--------------|:---------|:-------------------------------------------------------------------------------------------------|
+| `--build` | `bool` | | Build image before starting container |
+| `--cap-add` | `list` | | Add Linux capabilities |
+| `--cap-drop` | `list` | | Drop Linux capabilities |
+| `-d`, `--detach` | `bool` | | Run container in background and print container ID |
+| `--dry-run` | `bool` | | Execute command in dry run mode |
+| `--entrypoint` | `string` | | Override the entrypoint of the image |
+| `-e`, `--env` | `stringArray` | | Set environment variables |
+| `--env-from-file` | `stringArray` | | Set environment variables from file |
+| `-i`, `--interactive` | `bool` | `true` | Keep STDIN open even if not attached |
+| `-l`, `--label` | `stringArray` | | Add or override a label |
+| `--name` | `string` | | Assign a name to the container |
+| `--no-deps` | `bool` | | Don't start linked services |
+| `--no-recreate` | `bool` | | If dependent containers already exist, don't recreate them, even if their configuration diverged |
+| `-T`, `--no-tty` | `bool` | `true` | Disable pseudo-TTY allocation (default: auto-detected) |
+| `-p`, `--publish` | `stringArray` | | Publish a container's port(s) to the host |
+| `--pull` | `string` | `policy` | Pull image before running ("always"\|"missing"\|"never") |
+| `-q`, `--quiet` | `bool` | | Don't print anything to STDOUT |
+| `--quiet-build` | `bool` | | Suppress progress output from the build process |
+| `--quiet-pull` | `bool` | | Pull without printing progress information |
+| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file |
+| `--rm` | `bool` | | Automatically remove the container when it exits |
+| `-P`, `--service-ports` | `bool` | | Run command with all service's ports enabled and mapped to the host |
+| `--use-aliases` | `bool` | | Use the service's network useAliases in the network(s) the container connects to |
+| `-u`, `--user` | `string` | | Run as specified username or uid |
+| `-v`, `--volume` | `stringArray` | | Bind mount a volume |
+| `-w`, `--workdir` | `string` | | Working directory inside the container |
diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/compose_stats.md b/_vendor/github.com/docker/compose/v5/docs/reference/compose_stats.md
index 78d44b8935..843dac86bb 100644
--- a/_vendor/github.com/docker/compose/v5/docs/reference/compose_stats.md
+++ b/_vendor/github.com/docker/compose/v5/docs/reference/compose_stats.md
@@ -5,13 +5,15 @@ Display a live stream of container(s) resource usage statistics
### Options
-| Name | Type | Default | Description |
-|:--------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `-a`, `--all` | `bool` | | Show all containers (default shows just running) |
-| `--dry-run` | `bool` | | Execute command in dry run mode |
-| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/engine/cli/formatting/ for more information about formatting output with templates |
-| `--no-stream` | `bool` | | Disable streaming stats and only pull the first result |
-| `--no-trunc` | `bool` | | Do not truncate output |
+| Name | Type | Default | Description |
+|:-----------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--aggregate` | `bool` | | Show one line per project, summing the resource usage of its containers (only 'table' and 'json' formats) |
+| `-a`, `--all` | `bool` | | Show all containers (default shows just running) |
+| `--all-projects` | `bool` | | Show the containers of all projects instead of the current one, with their project (only 'table' and 'json' formats) |
+| `--dry-run` | `bool` | | Execute command in dry run mode |
+| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/engine/cli/formatting/ for more information about formatting output with templates |
+| `--no-stream` | `bool` | | Disable streaming stats and only pull the first result |
+| `--no-trunc` | `bool` | | Do not truncate output |
diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose.yaml
index c5fdb93751..e1fe5f1a57 100644
--- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose.yaml
+++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose.yaml
@@ -389,9 +389,13 @@ examples: |-
### Configuring parallelism
- Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
+ Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls or builds.
Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file
- one at a time. This can also be used to control build concurrency.
+ one at a time.
+
+ Limiting build concurrency requires Buildx 0.38.0 or later. When services are linked by
+ `additional_contexts` (`service:`), Buildx rejects a limit lower than the number of images to
+ build, so Compose ignores it with a warning.
Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_push.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_push.yaml
index be7c116065..fe96a00053 100644
--- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_push.yaml
+++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_push.yaml
@@ -23,12 +23,23 @@ usage: docker compose push [OPTIONS] [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
+ - option: ignore-missing
+ value_type: bool
+ default_value: "false"
+ description: |
+ Skip images that are not available locally instead of failing to push them
+ deprecated: false
+ hidden: false
+ experimental: false
+ experimentalcli: false
+ kubernetes: false
+ swarm: false
- option: ignore-push-failures
value_type: bool
default_value: "false"
description: Push what it can and ignores images with push failures
- deprecated: false
- hidden: false
+ deprecated: true
+ hidden: true
experimental: false
experimentalcli: false
kubernetes: false
diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml
index bc9f81e9ed..dca423ab9a 100644
--- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml
+++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml
@@ -168,6 +168,17 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
+ - option: no-recreate
+ value_type: bool
+ default_value: "false"
+ description: |
+ If dependent containers already exist, don't recreate them, even if their configuration diverged
+ deprecated: false
+ hidden: false
+ experimental: false
+ experimentalcli: false
+ kubernetes: false
+ swarm: false
- option: no-tty
shorthand: T
value_type: bool
diff --git a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_stats.yaml b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_stats.yaml
index e6854b05a2..e79888f5c5 100644
--- a/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_stats.yaml
+++ b/_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_stats.yaml
@@ -5,6 +5,17 @@ usage: docker compose stats [OPTIONS] [SERVICE]
pname: docker compose
plink: docker_compose.yaml
options:
+ - option: aggregate
+ value_type: bool
+ default_value: "false"
+ description: |
+ Show one line per project, summing the resource usage of its containers (only 'table' and 'json' formats)
+ deprecated: false
+ hidden: false
+ experimental: false
+ experimentalcli: false
+ kubernetes: false
+ swarm: false
- option: all
shorthand: a
value_type: bool
@@ -16,6 +27,17 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
+ - option: all-projects
+ value_type: bool
+ default_value: "false"
+ description: |
+ Show the containers of all projects instead of the current one, with their project (only 'table' and 'json' formats)
+ deprecated: false
+ hidden: false
+ experimental: false
+ experimentalcli: false
+ kubernetes: false
+ swarm: false
- option: format
value_type: string
description: |-
diff --git a/_vendor/modules.txt b/_vendor/modules.txt
index 844a013929..abf6fd6d9c 100644
--- a/_vendor/modules.txt
+++ b/_vendor/modules.txt
@@ -1,7 +1,7 @@
# github.com/moby/moby/api v1.56.1
-# github.com/moby/buildkit v0.34.0
-# github.com/docker/buildx v0.38.1
-# github.com/docker/cli v29.9.1+incompatible
-# github.com/docker/compose/v5 v5.6.1
+# github.com/moby/buildkit v0.34.2
+# github.com/docker/buildx v0.38.2
+# github.com/docker/cli v29.9.2+incompatible
+# github.com/docker/compose/v5 v5.7.0
# github.com/docker/model-runner v1.1.36
# github.com/docker/docker-agent v1.152.0
diff --git a/content/get-started/tutorials/admin-set-up.md b/content/get-started/tutorials/admin-set-up.md
index f36f451375..b0c1fc808d 100644
--- a/content/get-started/tutorials/admin-set-up.md
+++ b/content/get-started/tutorials/admin-set-up.md
@@ -76,7 +76,7 @@ pilot's feedback to refine the policy and its deployment communication.
Continue with these guides when you're ready to expand the deployment:
-- [Set up your company for success with Docker](/guides/admin-set-up/) for the
+- [Plan and roll out Docker](/manuals/accounts/organization/setup/rollout.md) for the
full deployment handbook
- [Manage organization members](/manuals/accounts/organization/manage/members.md)
for roles, teams, and bulk invitations
@@ -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
diff --git a/content/get-started/tutorials/run-an-agent.md b/content/get-started/tutorials/run-an-agent.md
index 820b19f28f..69b7f054d2 100644
--- a/content/get-started/tutorials/run-an-agent.md
+++ b/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
diff --git a/content/guides/admin-set-up.md b/content/guides/admin-set-up.md
deleted file mode 100644
index cf3b322c42..0000000000
--- a/content/guides/admin-set-up.md
+++ /dev/null
@@ -1,330 +0,0 @@
----
-title: Set up your company for success with Docker
-linkTitle: Admin set up
-summary: Get the most out of Docker by streamlining workflows, standardizing development environments, and ensuring smooth deployments across your company.
-description: Learn how to onboard your company and take advantage of all of the Docker products and features.
-keywords: admin, onboarding, deployment, organization setup, docker business, rollout
-aliases:
- - /guides/admin-set-up/comms-and-info-gathering/
- - /guides/admin-set-up/deploy/
- - /guides/admin-set-up/finalize-plans-and-setup/
- - /guides/admin-set-up/testing/
-params:
- tags: [admin]
- time: 20 minutes
- image:
----
-
-
-Docker's tools provide a scalable, secure platform that empowers your
-developers to create, ship, and run applications faster. As an administrator,
-you can streamline workflows, standardize development environments, and ensure
-smooth deployments across your organization.
-
-By configuring Docker products to suit your company's needs, you can optimize
-performance, simplify user management, and maintain control over resources.
-This guide helps you set up and configure Docker products to maximize
-productivity and success for your team while meeting compliance and security
-policies.
-
-## Who’s this for?
-
-- Administrators responsible for managing Docker environments within their
- organization
-- IT leaders looking to streamline development and deployment workflows
-- Teams aiming to standardize application environments across multiple users
-- Organizations seeking to optimize their use of Docker products for greater
- scalability and efficiency
-- Organizations with a
- [Docker Business subscription](https://www.docker.com/pricing?ref=DocsGuides&refAction=DocsGuidesCTAClicked)
-
-## What you’ll learn
-
-- Why signing into your company's Docker organization provides access to usage
- data and enhanced functionality
-- How to standardize Docker Desktop versions and settings to create a consistent
- baseline for all users, while allowing flexibility for advanced developers
-- Strategies for implementing Docker's security configurations to meet company
- IT and software development security requirements without hindering developer productivity
-
-## Features covered
-
-This guide covers the following Docker features:
-
-- [Organizations](/manuals/accounts/organization/_index.md): The core structure
- for managing your Docker environment, grouping users, teams, and image
- repositories. Your organization was created with your subscription and is
- managed by one or more owners. Users signed into the organization are
- assigned seats based on the purchased subscription.
-- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md):
- By default, Docker Desktop doesn't require sign-in. You can configure
- settings to enforce this and ensure your developers sign in to your
- Docker organization.
-- [SSO](/manuals/security/authentication/single-sign-on/_index.md): Without SSO,
- user management in a Docker organization is manual. Setting
- up an SSO connection between your identity provider and Docker ensures
- compliance with your security policy and automates user provisioning. Adding
- SCIM further automates user provisioning and de-provisioning.
-- General and security settings: Configuring key settings ensures smooth
- onboarding and usage of Docker products within your environment. You can also
- enable security features based on your company's specific security needs.
-
-## Who needs to be involved
-
-- Docker organization owner: Must be involved in the process and is required
- for several key steps
-- DNS team: Needed during the SSO setup to verify the company domain
-- MDM team: Responsible for distributing Docker-specific configuration files to
- developer machines
-- Identity Provider team: Required for configuring the identity provider and
- establishing the SSO connection during setup
-- Development lead: A development lead with knowledge of Docker configurations
- to help establish a baseline for developer settings
-- IT team: An IT representative familiar with company desktop policies to
- assist with aligning Docker configuration to those policies
-- Infosec: A security team member with knowledge of company development
- security policies to help configure security features
-- Docker testers: A small group of developers to test the new settings and
- configurations before full deployment
-
-## Tools integration
-
-This guide covers integration with:
-
-- Okta
-- Entra ID SAML 2.0
-- Azure Connect (OIDC)
-- MDM solutions like Intune
-
-## Communication and information gathering
-
-### Communicate with your developers and IT teams
-
-Before rolling out Docker Desktop across your organization, coordinate with key stakeholders to ensure a smooth transition.
-
-#### Notify Docker Desktop users
-
-You may already have Docker Desktop users within your company. Some steps in
-this onboarding process may affect how they interact with the platform.
-
-Communicate early with users to inform them that:
-
-- They'll be upgraded to a supported version of Docker Desktop as part of the subscription onboarding
-- Settings will be reviewed and optimized for productivity
-- They'll need to sign in to the company's Docker organization using their
- business email to access subscription benefits
-
-#### Engage with your MDM team
-
-Device management solutions, such as Intune and Jamf, are commonly used for
-software distribution across enterprises. These tools are typically managed by a dedicated MDM team.
-
-Engage with this team early in the process to:
-
-- Understand their requirements and lead time for deploying changes
-- Coordinate the distribution of configuration files
-
-Several setup steps in this guide require JSON files, registry keys, or .plist
-files to be distributed to developer machines. Use MDM tools to deploy these configuration files and ensure their integrity.
-
-### Identify Docker organizations
-
-Some companies may have more than one
-[Docker organization](/manuals/accounts/organization/_index.md) created. These
-organizations may have been created for specific purposes, or may not be
-needed anymore.
-
-If you suspect your company has multiple Docker organizations:
-
-- Survey your teams to see if they have their own organizations
-- Contact your Docker Support to get a list of organizations with users whose
- emails match your domain name
-
-### Gather requirements
-
-[Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) lets you preset numerous configuration parameters for Docker Desktop.
-
-Work with the following stakeholders to establish your company's baseline
-configuration:
-
-- Docker organization owner
-- Development lead
-- Information security representative
-
-Review these areas together:
-
-- Security features and
- [enforcing sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md)
- for Docker Desktop users
-- Additional Docker products included in your subscriptions
-
-To view the parameters that can be preset, see [Configure Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md#step-two-configure-the-settings-you-want-to-lock-in).
-
-### Optional: Meet with the Docker Implementation team
-
-The Docker Implementation team can help you set up your organization,
-configure SSO, enforce sign-in, and configure Docker Desktop.
-
-To schedule a meeting, email successteam@docker.com.
-
-## Finalize plans and begin setup
-
-### Send finalized settings files to the MDM team
-
-After reaching an agreement with the relevant teams about your baseline and
-security configurations as outlined in the previous section, configure Settings Management either via [Docker Home](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md) or with an
-[`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md).
-
-Once the file is ready, collaborate with your MDM team to deploy your chosen
-settings, along with your chosen method for [enforcing sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md).
-
-> [!IMPORTANT]
->
-> Test this first with a small number of Docker Desktop developers to verify the functionality works as expected before deploying more widely.
-
-### Manage your organizations
-
-If you have more than one organization, consider either [consolidating them
-into one organization](/manuals/accounts/organization/setup/orgs.md) or creating a
-[Docker company](/manuals/accounts/company/_index.md) to manage multiple
-organizations.
-
-### Begin setup
-
-#### Set up single sign-on and domain verification
-
-Single sign-on (SSO) lets developers authenticate using their identity
-providers (IdPs) to access Docker. SSO is available for a whole company and all associated organizations, or an individual organization that has a Docker
-Business subscription. For more information, see the
-[documentation](/manuals/security/authentication/single-sign-on/_index.md).
-
-You can also enable [SCIM](/manuals/security/provisioning/scim/_index.md)
-for further automation of provisioning and deprovisioning of users.
-
-#### Set up Docker product entitlements included in the subscription
-
-[Docker Build Cloud](/manuals/build-cloud/_index.md) significantly reduces
-build times, both locally and in CI, by providing a dedicated remote builder
-and shared cache. Powered by the cloud, developer time and local resources are
-freed up so your team can focus on more important things, like innovation.
-To get started, [set up a cloud builder](https://app.docker.com/build/).
-
-[Docker Scout](manuals/scout/_index.md) is a solution for proactively enhancing
-your software supply chain security. By analyzing your images, Docker Scout
-compiles an inventory of components, also known as a Software Bill of Materials
-(SBOM). The SBOM is matched against a continuously updated vulnerability
-database to pinpoint security weaknesses. To get started, see
-[Quickstart](/manuals/scout/quickstart.md).
-
-[Testcontainers Cloud](https://testcontainers.com/cloud/docs/) allows
-developers to run containers in the cloud, removing the need to run heavy
-containers on your local machine.
-
-[Docker Hardened Images](/manuals/dhi/_index.md) are minimal, secure, and production-ready container base and application images maintained by Docker.
-Designed to reduce vulnerabilities and simplify compliance, DHIs integrate
-easily into your existing Docker-based workflows with little to no retooling
-required.
-
-#### Ensure you're running a supported version of Docker Desktop
-
-> [!WARNING]
->
-> This step could affect the experience for users on older versions of Docker
-> Desktop.
-
-Existing users may be running outdated or unsupported versions of
-Docker Desktop. All users should update to a supported version. Docker Desktop
-versions released within the past 6 months from the latest release are supported.
-
-Use an MDM solution to manage the version of Docker Desktop for users. Users
-may also get Docker Desktop directly from Docker or through a company software
-portal.
-
-## Testing
-
-### SSO and SCIM testing
-
-Test SSO and SCIM by signing in to Docker Desktop or Docker Hub with the email
-address linked to a Docker account that is part of the verified domain.
-Developers who sign in using their Docker usernames remain unaffected by the
-SSO and SCIM setup.
-
-> [!IMPORTANT]
->
-> Some users may need CLI based logins to Docker Hub, and for this they will
-> need a [personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md).
-
-### Test Registry Access Management and Image Access Management
-
-> [!WARNING]
->
-> Communicate with your users before proceeding, as this step will impact all
-> existing users signing into your Docker organization.
-
-If you plan to use [Registry Access Management (RAM)](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) and/or [Image Access Management (IAM)](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md):
-
-1. Ensure your test developer signs in to Docker Desktop using their
- organization credentials
-2. Have them attempt to pull an unauthorized image or one from a disallowed
- registry via the Docker CLI
-3. Verify they receive an error message indicating that the registry is
- restricted by the organization
-
-### Deploy settings and enforce sign in to test group
-
-Deploy the Docker settings and enforce sign-in for a small group of test users
-via MDM. Have this group test their development workflows with containers on
-Docker Desktop and Docker Hub to ensure all settings and the sign-in enforcement
-function as expected.
-
-### Test Docker Build Cloud capabilities
-
-Have one of your Docker Desktop testers [connect to the cloud builder you created and use it to build](/manuals/build-cloud/usage.md).
-
-### Test Testcontainers Cloud
-
-Have a test developer [connect to Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) and run a container in
-the cloud to verify the setup is working correctly.
-
-### Verify Docker Scout monitoring of repositories
-
-Check the [Docker Scout dashboard](https://scout.docker.com/) to confirm that
-data is being properly received for the repositories where Docker Scout has
-been enabled.
-
-### Verify access to Docker Hardened Images
-
-Have a test developer attempt to [pull a Docker Hardened Image](/manuals/dhi/get-started.md) to confirm that
-the team has proper access and can integrate these images into their workflows.
-
-## Deploy your Docker setup
-
-> [!WARNING]
->
-> Communicate with your users before proceeding, and confirm that your IT and
-> MDM teams are prepared to handle any unexpected issues, as these steps will
-> affect all existing users signing into your Docker organization.
-
-### Enforce SSO
-
-Enforcing SSO means that anyone who has a Docker profile with an email address
-that matches your verified domain must sign in using your SSO connection. Make
-sure the Identity provider groups associated with your SSO connection cover all
-the developer groups that you want to have access to the Docker subscription.
-
-For instructions on how to enforce SSO, see [Enforce SSO](/manuals/security/authentication/single-sign-on/connect.md).
-
-### Deploy configuration settings and enforce sign-in to users
-
-Have the MDM team deploy the configuration files for Docker to all users.
-
-### Next steps
-
-Congratulations, you've successfully completed the admin implementation process
-for Docker.
-
-To continue optimizing your Docker environment:
-
-- Review your [organization's usage data](/manuals/accounts/organization/insights.md) to track adoption
-- Monitor [Docker Scout findings](/manuals/scout/explore/analysis.md) for security insights
-- Explore [additional security features](/manuals/desktop/enterprise/hardened-desktop/_index.md) to enhance your configuration
diff --git a/content/guides/admin-user-management.md b/content/guides/admin-user-management.md
deleted file mode 100644
index 492cdb8e23..0000000000
--- a/content/guides/admin-user-management.md
+++ /dev/null
@@ -1,198 +0,0 @@
----
-title: Mastering user and access management
-summary: Simplify user access while ensuring security and efficiency in Docker.
-description: A guide for managing roles, provisioning users, and optimizing Docker access with tools like SSO and activity logs.
-keywords: admin, user management, roles, permissions, sso, provisioning, access control
-aliases:
- - /guides/admin-user-management/audit-and-monitor/
- - /guides/admin-user-management/onboard/
- - /guides/admin-user-management/setup/
-params:
- tags: [admin]
- featured: false
- time: 20 minutes
- image:
----
-
-
-Managing roles and permissions is key to securing your Docker environment while enabling easy collaboration and operational efficiency. This guide walks IT administrators through the essentials of user and access management, offering strategies for assigning roles, provisioning users, and using tools like activity logs and Insights to monitor and optimize Docker usage.
-
-## Who's this for?
-
-- IT teams tasked with configuring and maintaining secure user access
-- Security professionals focused on enforcing secure access practices
-- Project managers overseeing team collaboration and resource management
-
-## What you'll learn
-
-- How to assess and manage Docker user access and align accounts with organizational needs
-- When to use team configurations for scalable access control
-- How to automate and streamline user provisioning with SSO, SCIM, and JIT
-- How to get the most out of Docker's monitoring tools
-
-## Tools integration
-
-This guide covers integration with:
-
-- Okta
-- Entra ID SAML 2.0
-- Azure Connect (OIDC)
-
-## Setting up roles and permissions in Docker
-
-With the right configurations, you can ensure your developers have easy access to necessary resources while preventing unauthorized access. This page guides you through identifying Docker users so you can allocate subscription seats efficiently within your Docker organization, and assigning roles to align with your organization's structure.
-
-### Identify your Docker users and accounts
-
-Before setting up roles and permissions, it's important to have a clear understanding of who in your organization requires Docker access. Focus on gathering a comprehensive view of active users, their roles within projects, and how they interact with Docker resources. This process can be supported by tools like device management software or manual assessments. Encourage all users to update their Docker accounts to use organizational email addresses, ensuring seamless integration with your subscription.
-
-For steps on how you can do this, see [step 1 of onboarding your organization](/manuals/accounts/organization/setup/onboard.md).
-
-### Assign roles strategically
-
-When you invite members to join your Docker organization, you assign them a role.
-
-Docker's predefined roles offer flexibility for various organizational needs. Assigning roles effectively ensures a balance of accessibility and security.
-
-- Member: Non-administrative role. Members can view other members that are in the same organization.
-- Editor: Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions.
-- Owner: Full organization administrative access. Owners can manage organization repositories, teams, members, settings, and billing.
-
-For more information, see [Roles and permissions](/manuals/security/roles-and-permissions.md).
-
-#### Enhance with teams
-
-Teams in Docker provide a structured way to manage member access and they provide an additional level of permissions. They simplify permission management and enable consistent application of policies.
-
-- Organize users into teams aligned with projects, departments, or functional roles. This approach helps streamline resource allocation and ensures clarity in access control.
-- Assign permissions at the team level rather than individually. For instance, a development team might have "Read & Write" access to certain repositories, while a QA team has "Read-only" access.
-- As teams grow or responsibilities shift, you can easily update permissions or add new members, maintaining consistency without reconfiguring individual settings.
-
-For more information, see [Create and manage a team](/manuals/accounts/organization/manage/manage-a-team.md).
-
-#### Example scenarios
-
-- Development teams: Assign the member role to developers, granting access to the repositories needed for coding and testing.
-- Team leads: Assign the editor role to team leads for resource management and repository control within their teams.
-- Organizational oversight: Restrict the organization owner or company owner roles to a select few trusted individuals responsible for billing and security settings.
-
-#### Best practices
-
-- Apply the principle of least privilege. Assign users only the minimum permissions necessary for their roles.
-- Conduct regular reviews of role assignments to ensure they align with evolving team structures and organizational responsibilities.
-
-## Onboarding and managing roles and permissions in Docker
-
-This page guides you through onboarding owners and members, and using tools like SSO and SCIM to future-proof onboarding going forward.
-
-### Invite owners
-
-When you create a Docker organization, you automatically become its sole owner. While optional, adding additional owners can significantly ease the process of onboarding and managing your organization by distributing administrative responsibilities. It also ensures continuity and prevents blockers if the primary owner is unavailable.
-
-For detailed information on owners, see [Roles and permissions](/manuals/security/roles-and-permissions.md).
-
-### Invite members and assign roles
-
-Members are granted controlled access to resources and enjoy enhanced organizational benefits. When you invite members to join your Docker organization, you immediately assign them a role.
-
-#### Benefits of inviting members
-
-- Enhanced visibility: Gain insights into user activity, making it easier to monitor access and enforce security policies.
-- Streamlined collaboration: Help members collaborate effectively by granting access to shared resources and repositories.
-- Improved resource management: Organize and track users within your organization, ensuring optimal allocation of resources.
-- Access to enhanced features: Members benefit from organization-wide perks, such as increased pull limits and access to premium Docker features.
-- Security control: Apply and enforce security settings at an organizational level, reducing risks associated with unmanaged accounts.
-
-For detailed information, see [Manage organization members](/manuals/accounts/organization/manage/members.md).
-
-### Future-proof user management
-
-A robust, future-proof approach to user management combines automated provisioning, centralized authentication, and dynamic access control. Implementing these practices ensures a scalable, secure, and efficient environment.
-
-#### Secure user authentication with single sign-on (SSO)
-
-Integrating Docker with your identity provider streamlines user access and enhances security.
-
-SSO:
-
-- Simplifies sign in, as users sign in with their organizational credentials.
-- Reduces password-related vulnerabilities.
-- Simplifies onboarding as it works seamlessly with SCIM and group mapping for automated provisioning.
-
-For more information, see the [SSO documentation](/manuals/security/authentication/single-sign-on/_index.md).
-
-#### Automate onboarding with SCIM and JIT provisioning
-
-Streamline user provisioning and role management with [SCIM](/manuals/security/provisioning/scim/_index.md) and [Just-in-Time (JIT) provisioning](/manuals/security/provisioning/just-in-time.md).
-
-With SCIM you can:
-
-- Sync users and roles automatically with your identity provider.
-- Automate adding, updating, or removing users based on directory changes.
-
-With JIT provisioning you can:
-
-- Automatically add users upon first sign in based on [group mapping](#simplify-access-with-group-mapping).
-- Reduce overhead by eliminating pre-invite steps.
-
-#### Simplify access with group mapping
-
-Group mapping automates permissions management by linking identity provider groups to Docker roles and teams.
-
-It also:
-
-- Reduces manual errors in role assignments.
-- Ensures consistent access control policies.
-- Help you scale permissions as teams grow or change.
-
-For more information on how it works, see [Group mapping](/manuals/security/provisioning/scim/group-mapping.md).
-
-## Monitoring and insights
-
-Activity logs and Insights are useful tools for user and access management in Docker. They provide visibility into user actions, team workflows, and organizational trends, helping enhance security, ensure compliance, and boost productivity.
-
-### Activity logs
-
-Activity logs track events at the organization and repository levels, offering a clear view of activities like repository changes, team updates, and billing adjustments.
-
-Activity logs are available for Docker Team or Docker Business plans, with data retained for three months.
-
-#### Key features
-
-- Change tracking: View what changed, who made the change, and when.
-- Comprehensive reporting: Monitor critical events such as repository creation, deletion, privacy changes, and role assignments.
-
-#### Example scenarios
-
-- Audit trail for security: A repository’s privacy settings were updated unexpectedly. The activity logs reveal which user made the change and when, helping administrators address potential security risks.
-- Team collaboration review: Logs show which team members pushed updates to a critical repository, ensuring accountability during a development sprint.
-- Billing adjustments: Track who added or removed subscription seats to maintain budgetary control and compliance.
-
-For more information, see [Activity logs](/manuals/accounts/organization/activity-logs.md).
-
-### Insights
-
-Insights provide data-driven views of Docker usage to improve team productivity and resource allocation.
-
-#### Key benefits
-
-- Standardized environments: Ensure consistent configurations and enforce best practices across teams.
-- Improved visibility: Monitor metrics like Docker Desktop usage, builds, and container activity to understand team workflows and engagement.
-- Optimized resources: Track license usage and feature adoption to maximize the value of your Docker subscription.
-
-#### Example scenarios
-
-- Usage trends: Identify underutilized licenses or resources, allowing reallocation to more active teams.
-- Build efficiency: Track average build times and success rates to pinpoint bottlenecks in development processes.
-- Container utilization: Analyze container activity across departments to ensure proper resource distribution and cost efficiency.
-
-For more information, see [Insights](/manuals/accounts/organization/insights.md).
-
-### Next steps
-
-Now that you've mastered user and access management in Docker, you can:
-
-- Review your [activity logs](/manuals/accounts/organization/activity-logs.md) regularly to maintain security awareness
-- Check your [Insights dashboard](/manuals/accounts/organization/insights.md) to identify opportunities for optimization
-- Explore [advanced security features](/manuals/desktop/enterprise/hardened-desktop/_index.md) to further enhance your Docker environment
-- Share best practices with your team to ensure consistent adoption of security policies
diff --git a/content/guides/azure-pipelines.md b/content/guides/azure-pipelines.md
index 27f218770f..308742fa49 100644
--- a/content/guides/azure-pipelines.md
+++ b/content/guides/azure-pipelines.md
@@ -1,5 +1,6 @@
---
title: Introduction to Azure Pipelines with Docker
+description: Automate Docker image builds and publishing with Azure Pipelines.
linkTitle: Azure Pipelines and Docker
summary: |
Learn how to automate Docker image build and push using Azure Pipelines.
@@ -308,5 +309,5 @@ With this Azure Pipelines CI setup, you get:
- [Azure Pipelines Documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/?view=azure-devops): Comprehensive guide to configuring and managing CI/CD pipelines in Azure DevOps.
- [Docker Task for Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/build/docker): Detailed reference for using the Docker task in Azure Pipelines to build and push images.
-- [Docker Buildx Bake](/manuals/build/bake/_index.md): Explore Docker's advanced build tool for complex, multi-stage, and multi-platform build setups. See also the [Mastering Buildx Bake Guide](/guides/bake/) for practical examples and best practices.
+- [Bake targets](/manuals/build/bake/targets.md): Group builds, run checks, and export artifacts.
- [Docker Build Cloud](/manuals/build-cloud/_index.md): Learn about Docker's managed build service for faster, scalable, and multi-platform image builds in the cloud.
diff --git a/content/guides/bake.md b/content/guides/bake.md
deleted file mode 100644
index 9f70755bfa..0000000000
--- a/content/guides/bake.md
+++ /dev/null
@@ -1,515 +0,0 @@
----
-title: Mastering multi-platform builds, testing, and more with Docker Buildx Bake
-linkTitle: Mastering Docker Buildx Bake
-description: >
- Learn how to manage simple and complex build configurations with Buildx Bake.
-summary: >
- Learn to automate Docker builds and testing with declarative configurations using Buildx Bake.
-keywords: bake, buildx, multi-platform, build configuration, hcl, automation
-params:
- tags: [cicd]
- time: 30 minutes
- image: /images/guides/bake.webp
----
-
-This guide demonstrates how to simplify and automate the process of building
-images, testing, and generating build artifacts using Docker Buildx Bake. By
-defining build configurations in a declarative `docker-bake.hcl` file, you can
-eliminate manual scripts and enable efficient workflows for complex builds,
-testing, and artifact generation.
-
-## Assumptions
-
-This guide assumes that you're familiar with:
-
-- Docker
-- [Buildx](/manuals/build/concepts/overview.md#buildx)
-- [BuildKit](/manuals/build/concepts/overview.md#buildkit)
-- [Multi-stage builds](/manuals/build/building/multi-stage.md)
-- [Multi-platform builds](/manuals/build/building/multi-platform.md)
-
-## Prerequisites
-
-- You have a recent version of Docker installed on your machine.
-- You have Git installed for cloning repositories.
-- You're using the [containerd](/manuals/desktop/features/containerd.md) image store.
-
-## Introduction
-
-This guide uses an example project to demonstrate how Docker Buildx Bake can
-streamline your build and test workflows. The repository includes both a
-Dockerfile and a `docker-bake.hcl` file, giving you a ready-to-use setup to try
-out Bake commands.
-
-Start by cloning the example repository:
-
-```bash
-git clone https://github.com/dvdksn/bakeme.git
-cd bakeme
-```
-
-The Bake file, `docker-bake.hcl`, defines the build targets in a declarative
-syntax, using targets and groups, allowing you to manage complex builds
-efficiently.
-
-Here's what the Bake file looks like out-of-the-box:
-
-```hcl
-target "default" {
- target = "image"
- tags = [
- "bakeme:latest",
- ]
- attest = [
- "type=provenance,mode=max",
- "type=sbom",
- ]
- platforms = [
- "linux/amd64",
- "linux/arm64",
- "linux/riscv64",
- ]
-}
-```
-
-The `target` keyword defines a build target for Bake. The `default` target
-defines the target to build when no specific target is specified on the command
-line. Here's a quick summary of the options for the `default` target:
-
-- `target`: The target build stage in the Dockerfile.
-- `tags`: Tags to assign to the image.
-- `attest`: [Attestations](/manuals/build/metadata/attestations/_index.md) to attach to the image.
-
- > [!TIP]
- > The attestations provide metadata such as build provenance, which tracks
- > the source of the image's build, and an SBOM (Software Bill of Materials),
- > useful for security audits and compliance.
-
-- `platforms`: Platform variants to build.
-
-To execute this build, run the following command in the root of the
-repository:
-
-```console
-$ docker buildx bake
-```
-
-With Bake, you avoid long, hard-to-remember command-line incantations,
-simplifying build configuration management by replacing manual, error-prone
-scripts with a structured configuration file.
-
-For contrast, here's what this build command would look like without Bake:
-
-```console
-$ docker buildx build \
- --target=image \
- --tag=bakeme:latest \
- --provenance=true \
- --sbom=true \
- --platform=linux/amd64,linux/arm64,linux/riscv64 \
- .
-```
-
-## Testing and linting
-
-Bake isn't just for defining build configurations and running builds. You can
-also use Bake to run your tests, effectively using BuildKit as a task runner.
-Running your tests in containers is great for ensuring reproducible results.
-This section shows how to add two types of tests:
-
-- Unit testing with `go test`.
-- Linting for style violations with `golangci-lint`.
-
-In Test-Driven Development (TDD) fashion, start by adding a new `test` target
-to the Bake file:
-
-```hcl
-target "test" {
- target = "test"
- output = ["type=cacheonly"]
-}
-```
-
-> [!TIP]
-> Using `type=cacheonly` ensures that the build output is effectively
-> discarded; the layers are saved to BuildKit's cache, but Buildx will not
-> attempt to load the result to the Docker Engine's image store.
->
-> For test runs, you don't need to export the build output — only the test
-> execution matters.
-
-To execute this Bake target, run `docker buildx bake test`. At this time,
-you'll receive an error indicating that the `test` stage does not exist in the
-Dockerfile.
-
-```console
-$ docker buildx bake test
-[+] Building 1.2s (6/6) FINISHED
- => [internal] load local bake definitions
-...
-ERROR: failed to solve: target stage "test" could not be found
-```
-
-To satisfy this target, add the corresponding Dockerfile target. The `test`
-stage here is based on the same base stage as the build stage.
-
-```dockerfile
-FROM base AS test
-RUN --mount=target=. \
- --mount=type=cache,target=/go/pkg/mod \
- go test .
-```
-
-> [!TIP]
-> The [`--mount=type=cache` directive](/manuals/build/cache/optimize.md#use-cache-mounts)
-> caches Go modules between builds, improving build performance by avoiding the
-> need to re-download dependencies. This shared cache ensures that the same
-> dependency set is available across build, test, and other stages.
-
-Now, running the `test` target with Bake will evaluate the unit tests for this
-project. If you want to verify that it works, you can make an arbitrary change
-to `main_test.go` to cause the test to fail.
-
-Next, to enable linting, add another target to the Bake file, named `lint`:
-
-```hcl
-target "lint" {
- target = "lint"
- output = ["type=cacheonly"]
-}
-```
-
-And in the Dockerfile, add the build stage. This stage will use the official
-`golangci-lint` image on Docker Hub.
-
-> [!TIP]
-> Because this stage relies on executing an external dependency, it's generally
-> a good idea to define the version you want to use as a build argument. This
-> lets you manage version upgrades in the future by collocating
-> dependency versions to the beginning of the Dockerfile.
-
-```dockerfile {hl_lines=[2,"6-8"]}
-ARG GO_VERSION="1.23"
-ARG GOLANGCI_LINT_VERSION="1.61"
-
-#...
-
-FROM golangci/golangci-lint:v${GOLANGCI_LINT_VERSION}-alpine AS lint
-RUN --mount=target=.,rw \
- golangci-lint run
-```
-
-Lastly, to enable running both tests simultaneously, you can use the `groups`
-construct in the Bake file. A group can specify multiple targets to run with a
-single invocation.
-
-```hcl
-group "validate" {
- targets = ["test", "lint"]
-}
-```
-
-Now, running both tests is as simple as:
-
-```console
-$ docker buildx bake validate
-```
-
-## Building variants
-
-Sometimes you need to build more than one version of a program. The following
-example uses Bake to build separate "release" and "debug" variants of the
-program, using [matrices](/manuals/build/bake/matrices.md). Using matrices lets
-you run parallel builds with different configurations, saving time and ensuring
-consistency.
-
-A matrix expands a single build into multiple builds, each representing a
-unique combination of matrix parameters. This means you can orchestrate Bake
-into building both the production and development build of your program in
-parallel, with minimal configuration changes.
-
-The example project for this guide is set up to use a build-time option to
-conditionally enable debug logging and tracing capabilities.
-
-- If you compile the program with `go build -tags="debug"`, the additional
- logging and tracing capabilities are enabled (development mode).
-- If you build without the `debug` tag, the program is compiled with a default
- logger (production mode).
-
-Update the Bake file by adding a matrix attribute which defines the variable
-combinations to build:
-
-```diff {title="docker-bake.hcl"}
- target "default" {
-+ matrix = {
-+ mode = ["release", "debug"]
-+ }
-+ name = "image-${mode}"
- target = "image"
-```
-
-The `matrix` attribute defines the variants to build ("release" and "debug").
-The `name` attribute defines how the matrix gets expanded into multiple
-distinct build targets. In this case, the matrix attribute expands the build
-into two workflows: `image-release` and `image-debug`, each using different
-configuration parameters.
-
-Next, define a build argument named `BUILD_TAGS` which takes the value of the
-matrix variable.
-
-```diff {title="docker-bake.hcl"}
- target = "image"
-+ args = {
-+ BUILD_TAGS = mode
-+ }
- tags = [
-```
-
-You'll also want to change how the image tags are assigned to these builds.
-As written, both matrix paths would generate the same image tag names, and
-overwrite each other. Update the `tags` attribute use a conditional operator to
-set the tag depending on the matrix variable value.
-
-```diff {title="docker-bake.hcl"}
- tags = [
-- "bakeme:latest",
-+ mode == "release" ? "bakeme:latest" : "bakeme:dev"
- ]
-```
-
-- If `mode` is `release`, the tag name is `bakeme:latest`
-- If `mode` is `debug`, the tag name is `bakeme:dev`
-
-Finally, update the Dockerfile to consume the `BUILD_TAGS` argument during the
-compilation stage. When the `-tags="${BUILD_TAGS}"` option evaluates to
-`-tags="debug"`, the compiler uses the `configureLogging` function in the
-[`debug.go`](https://github.com/dvdksn/bakeme/blob/75c8a41e613829293c4bd3fc3b4f0c573f458f42/debug.go#L1)
-file.
-
-```diff {title=Dockerfile}
- # build compiles the program
- FROM base AS build
--ARG TARGETOS TARGETARCH
-+ARG TARGETOS TARGETARCH BUILD_TAGS
- ENV GOOS=$TARGETOS
- ENV GOARCH=$TARGETARCH
- RUN --mount=target=. \
- --mount=type=cache,target=/go/pkg/mod \
-- go build -o "/usr/bin/bakeme" .
-+ go build -tags="${BUILD_TAGS}" -o "/usr/bin/bakeme" .
-```
-
-That's all. With these changes, your `docker buildx bake` command now builds
-two multi-platform image variants. You can introspect the canonical build
-configuration that Bake generates using the `docker buildx bake --print`
-command. Running this command shows that Bake will run a `default` group with
-two targets with different build arguments and image tags.
-
-```json {collapse=true}
-{
- "group": {
- "default": {
- "targets": ["image-release", "image-debug"]
- }
- },
- "target": {
- "image-debug": {
- "attest": ["type=provenance,mode=max", "type=sbom"],
- "context": ".",
- "dockerfile": "Dockerfile",
- "args": {
- "BUILD_TAGS": "debug"
- },
- "tags": ["bakeme:dev"],
- "target": "image",
- "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"]
- },
- "image-release": {
- "attest": ["type=provenance,mode=max", "type=sbom"],
- "context": ".",
- "dockerfile": "Dockerfile",
- "args": {
- "BUILD_TAGS": "release"
- },
- "tags": ["bakeme:latest"],
- "target": "image",
- "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"]
- }
- }
-}
-```
-
-Factoring in all of the platform variants as well, this means that the build
-configuration generates 6 different images.
-
-```console
-$ docker buildx bake
-$ docker image ls --tree
-
-IMAGE ID DISK USAGE CONTENT SIZE USED
-bakeme:dev f7cb5c08beac 49.3MB 28.9MB
-├─ linux/riscv64 0eae8ba0367a 9.18MB 9.18MB
-├─ linux/arm64 56561051c49a 30MB 9.89MB
-└─ linux/amd64 e8ca65079c1f 9.8MB 9.8MB
-
-bakeme:latest 20065d2c4d22 44.4MB 25.9MB
-├─ linux/riscv64 7cc82872695f 8.21MB 8.21MB
-├─ linux/arm64 e42220c2b7a3 27.1MB 8.93MB
-└─ linux/amd64 af5b2dd64fde 8.78MB 8.78MB
-```
-
-## Exporting build artifacts
-
-Exporting build artifacts like binaries can be useful for deploying to
-environments without Docker or Kubernetes. For example, if your programs are
-meant to be run on a user's local machine.
-
-> [!TIP]
-> The techniques discussed in this section can be applied not only to build
-> output like binaries, but to any type of artifacts, such as test reports.
-
-With programming languages like Go and Rust where the compiled binaries are
-usually portable, creating alternate build targets for exporting only the
-binary is trivial. All you need to do is add an empty stage in the Dockerfile
-containing nothing but the binary that you want to export.
-
-First, let's add a quick way to build a binary for your local platform and
-export it to `./build/local` on the local filesystem.
-
-In the `docker-bake.hcl` file, create a new `bin` target. In this stage, set
-the `output` attribute to a local filesystem path. Buildx automatically detects
-that the output looks like a filepath, and exports the results to the specified
-path using the [local exporter](/manuals/build/exporters/local-tar.md).
-
-```hcl
-target "bin" {
- target = "bin"
- output = ["build/bin"]
- platforms = ["local"]
-}
-```
-
-Notice that this stage specifies a `local` platform. By default, if `platforms`
-is unspecified, builds target the OS and architecture of the BuildKit host. If
-you're using Docker Desktop, this often means builds target `linux/amd64` or
-`linux/arm64`, even if your local machine is macOS or Windows, because Docker
-runs in a Linux VM. Using the `local` platform forces the target platform to
-match your local environment.
-
-Next, add the `bin` stage to the Dockerfile which copies the compiled binary
-from the build stage.
-
-```dockerfile
-FROM scratch AS bin
-COPY --from=build "/usr/bin/bakeme" /
-```
-
-Now you can export your local platform version of the binary with `docker
-buildx bake bin`. For example, on macOS, this build target generates an
-executable in the [Mach-O format](https://en.wikipedia.org/wiki/Mach-O) — the
-standard executable format for macOS.
-
-```console
-$ docker buildx bake bin
-$ file ./build/bin/bakeme
-./build/bin/bakeme: Mach-O 64-bit executable arm64
-```
-
-Next, let's add a target to build all of the platform variants of the program.
-To do this, you can [inherit](/manuals/build/bake/inheritance.md) the `bin`
-target that you just created, and extend it by adding the desired platforms.
-
-```hcl
-target "bin-cross" {
- inherits = ["bin"]
- platforms = [
- "linux/amd64",
- "linux/arm64",
- "linux/riscv64",
- ]
-}
-```
-
-Now, building the `bin-cross` target creates binaries for all platforms.
-Subdirectories are automatically created for each variant.
-
-```console
-$ docker buildx bake bin-cross
-$ tree build/
-build/
-└── bin
- ├── bakeme
- ├── linux_amd64
- │ └── bakeme
- ├── linux_arm64
- │ └── bakeme
- └── linux_riscv64
- └── bakeme
-
-5 directories, 4 files
-```
-
-To also generate "release" and "debug" variants, you can use a matrix just like
-you did with the default target. When using a matrix, you also need to
-differentiate the output directory based on the matrix value, otherwise the
-binary gets written to the same location for each matrix run.
-
-```hcl
-target "bin-all" {
- inherits = ["bin-cross"]
- matrix = {
- mode = ["release", "debug"]
- }
- name = "bin-${mode}"
- args = {
- BUILD_TAGS = mode
- }
- output = ["build/bin/${mode}"]
-}
-```
-
-```console
-$ rm -r ./build/
-$ docker buildx bake bin-all
-$ tree build/
-build/
-└── bin
- ├── debug
- │ ├── linux_amd64
- │ │ └── bakeme
- │ ├── linux_arm64
- │ │ └── bakeme
- │ └── linux_riscv64
- │ └── bakeme
- └── release
- ├── linux_amd64
- │ └── bakeme
- ├── linux_arm64
- │ └── bakeme
- └── linux_riscv64
- └── bakeme
-
-10 directories, 6 files
-```
-
-## Conclusion
-
-Docker Buildx Bake streamlines complex build workflows, enabling efficient
-multi-platform builds, testing, and artifact export. By integrating Buildx Bake
-into your projects, you can simplify your Docker builds, make your build
-configuration portable, and wrangle complex configurations.
-
-Experiment with different configurations and extend your Bake files to suit
-your project's needs. You might consider integrating Bake into your CI/CD
-pipelines to automate builds, testing, and artifact deployment. The flexibility
-and power of Buildx Bake can significantly improve your development and
-deployment processes.
-
-### Further reading
-
-For more information about how to use Bake, check out these resources:
-
-- [Bake documentation](/manuals/build/bake/_index.md)
-- [Matrix targets](/manuals/build/bake/matrices.md)
-- [Bake file reference](/manuals/build/bake/reference.md)
-- [Bake GitHub Action](https://github.com/docker/bake-action)
diff --git a/content/guides/compose-bake.md b/content/guides/compose-bake.md
deleted file mode 100644
index cad2cdfc15..0000000000
--- a/content/guides/compose-bake.md
+++ /dev/null
@@ -1,402 +0,0 @@
----
-title: Building Compose projects with Bake
-description: Learn how to build Docker Compose projects with Docker Buildx Bake
-summary: |
- This guide demonstrates how you can use Bake to build production-grade images for Docker Compose projects.
-keywords: docker compose, bake, buildx, multi-service, production builds, build configuration
-params:
- tags: [cicd]
- time: 20 minutes
----
-
-This guide explores how you can use Bake to build images for Docker Compose
-projects with multiple services.
-
-[Docker Buildx Bake](/manuals/build/bake/_index.md) is a build orchestration
-tool that enables declarative configuration for your builds, much like Docker
-Compose does for defining runtime stacks. For projects where Docker Compose is
-used to spin up services for local development, Bake offers a way of seamlessly
-extending the project with a production-ready build configuration.
-
-## Prerequisites
-
-This guide assumes that you're familiar with
-
-- Docker Compose
-- [Multi-stage builds](/manuals/build/building/multi-stage.md)
-- [Multi-platform builds](/manuals/build/building/multi-platform.md)
-
-## Orientation
-
-This guide will use the
-[dvdksn/example-voting-app](https://github.com/dvdksn/example-voting-app)
-repository as an example of a monorepo using Docker Compose that can be
-extended with Bake.
-
-```console
-$ git clone https://github.com/dvdksn/example-voting-app.git
-$ cd example-voting-app
-```
-
-This repository uses Docker Compose to define the runtime configurations for
-running the application, in the `compose.yaml` file. This app consists of the
-following services:
-
-| Service | Description |
-| -------- | ---------------------------------------------------------------------- |
-| `vote` | A front-end web app in Python which lets you vote between two options. |
-| `result` | A Node.js web app which shows the results of the voting in real time. |
-| `worker` | A .NET worker which consumes votes and stores them in the database. |
-| `db` | A Postgres database backed by a Docker volume. |
-| `redis` | A Redis instance which collects new votes. |
-| `seed` | A utility container that seeds the database with mock data. |
-
-The `vote`, `result`, and `worker` services are built from code in this
-repository, whereas `db` and `redis` use pre-existing Postgres and Redis images
-from Docker Hub. The `seed` service is a utility that invokes requests against
-the front-end service to populate the database, for testing purposes.
-
-## Build with Compose
-
-When you spin up a Docker Compose project, any services that define the `build`
-property are automatically built before the service is started. Here's the
-build configuration for the `vote` service in the example repository:
-
-```yaml {title="compose.yaml"}
-services:
- vote:
- build:
- context: ./vote # Build context
- target: dev # Dockerfile stage
-```
-
-The `vote`, `result`, and `worker` services all have a build configuration
-specified. Running `docker compose up` will trigger a build of these services.
-
-Did you know that you can also use Compose just to build the service images?
-The `docker compose build` command lets you invoke a build using the build
-configuration specified in the Compose file. For example, to build the `vote`
-service with this configuration, run:
-
-```console
-$ docker compose build vote
-```
-
-Omit the service name to build all services at once:
-
-```console
-$ docker compose build
-```
-
-The `docker compose build` command is useful when you only need to build images
-without running services.
-
-The Compose file format supports a number of properties for defining your
-build's configuration. For example, to specify the tag name for the images, set
-the `image` property on the service.
-
-```yaml
-services:
- vote:
- image: username/vote
- build:
- context: ./vote
- target: dev
- #...
-
- result:
- image: username/result
- build:
- context: ./result
- #...
-
- worker:
- image: username/worker
- build:
- context: ./worker
- #...
-```
-
-Running `docker compose build` creates three service images with fully
-qualified image names that you can push to Docker Hub.
-
-The `build` property supports a [wide range](/reference/compose-file/build.md)
-of options for configuring builds. However, building production-grade images
-are often different from images used in local development. To avoid cluttering
-your Compose file with build configurations that might not be desirable for
-local builds, consider separating the production builds from the local builds
-by using Bake to build images for release. This approach separates concerns:
-using Compose for local development and Bake for production-ready builds, while
-still reusing service definitions and fundamental build configurations.
-
-## Build with Bake
-
-Like Compose, Bake parses the build definition for a project from a
-configuration file. Bake supports HashiCorp Configuration Language (HCL), JSON,
-and the Docker Compose YAML format. When you use Bake with multiple files, it
-will find and merge all of the applicable configuration files into one unified
-build configuration. The build options defined in your Compose file are
-extended, or in some cases overridden, by options specified in the Bake file.
-
-The following section explores how you can use Bake to extend the build options
-defined in your Compose file for production.
-
-### View the build configuration
-
-Bake automatically creates a build configuration from the `build` properties of
-your services. Use the `--print` flag for Bake to view the build configuration
-for a given Compose file. This flag evaluates the build configuration and
-outputs the build definition in JSON format.
-
-```console
-$ docker buildx bake --print
-```
-
-The JSON-formatted output shows the group that would be executed, and all the
-targets of that group. A group is a collection of builds, and a target
-represents a single build.
-
-```json
-{
- "group": {
- "default": {
- "targets": [
- "vote",
- "result",
- "worker",
- "seed"
- ]
- }
- },
- "target": {
- "result": {
- "context": "result",
- "dockerfile": "Dockerfile",
- },
- "seed": {
- "context": "seed-data",
- "dockerfile": "Dockerfile",
- },
- "vote": {
- "context": "vote",
- "dockerfile": "Dockerfile",
- "target": "dev",
- },
- "worker": {
- "context": "worker",
- "dockerfile": "Dockerfile",
- }
- }
-}
-```
-
-As you can see, Bake has created a `default` group that includes four targets:
-
-- `seed`
-- `vote`
-- `result`
-- `worker`
-
-This group is created automatically from your Compose file; it includes all of
-your services containing a build configuration. To build this group of services
-with Bake, run:
-
-```console
-$ docker buildx bake
-```
-
-### Customize the build group
-
-Start by redefining the default build group that Bake executes. The current
-default group includes a `seed` target — a Compose service used solely to
-populate the database with mock data. Since this target doesn't produce a
-production image, it doesn't need to be included in the build group.
-
-To customize the build configuration that Bake uses, create a new file at the
-root of the repository, alongside your `compose.yaml` file, named
-`docker-bake.hcl`.
-
-```console
-$ touch docker-bake.hcl
-```
-
-Open the Bake file and add the following configuration:
-
-```hcl {title=docker-bake.hcl}
-group "default" {
- targets = ["vote", "result", "worker"]
-}
-```
-
-Save the file and print your Bake definition again.
-
-```console
-$ docker buildx bake --print
-```
-
-The JSON output shows that the `default` group only includes the targets you
-care about.
-
-```json
-{
- "group": {
- "default": {
- "targets": ["vote", "result", "worker"]
- }
- },
- "target": {
- "result": {
- "context": "result",
- "dockerfile": "Dockerfile",
- "tags": ["username/result"]
- },
- "vote": {
- "context": "vote",
- "dockerfile": "Dockerfile",
- "tags": ["username/vote"],
- "target": "dev"
- },
- "worker": {
- "context": "worker",
- "dockerfile": "Dockerfile",
- "tags": ["username/worker"]
- }
- }
-}
-```
-
-Here, the build configuration for each target (context, tags, etc.) is picked
-up from the `compose.yaml` file. The group is defined by the `docker-bake.hcl`
-file.
-
-### Customize targets
-
-The Compose file currently defines the `dev` stage as the build target for the
-`vote` service. That's appropriate for the image that you would run in local
-development, because the `dev` stage includes additional development
-dependencies and configurations. For the production image, however, you'll want
-to target the `final` image instead.
-
-To modify the target stage used by the `vote` service, add the following
-configuration to the Bake file:
-
-```hcl
-target "vote" {
- target = "final"
-}
-```
-
-This overrides the `target` property specified in the Compose file with a
-different value when you run the build with Bake. The other build options in
-the Compose file (tag, context) remain unmodified. You can verify by inspecting
-the build configuration for the `vote` target with `docker buildx bake --print
-vote`:
-
-```json
-{
- "group": {
- "default": {
- "targets": ["vote"]
- }
- },
- "target": {
- "vote": {
- "context": "vote",
- "dockerfile": "Dockerfile",
- "tags": ["username/vote"],
- "target": "final"
- }
- }
-}
-```
-
-### Additional build features
-
-Production-grade builds often have different characteristics from development
-builds. Here are a few examples of things you might want to add for production
-images.
-
-Multi-platform
-: For local development, you only need to build images for your local platform,
-since those images are just going to run on your machine. But for images that
-are pushed to a registry, it's often a good idea to build for multiple
-platforms, arm64 and amd64 in particular.
-
-Attestations
-: [Attestations](/manuals/build/metadata/attestations/_index.md) are manifests
-attached to the image that describe how the image was created and what
-components it contains. Attaching attestations to your images helps ensure that
-your images follow software supply chain best practices.
-
-Annotations
-: [Annotations](/manuals/build/metadata/annotations.md) provide descriptive
-metadata for images. Use annotations to record arbitrary information and attach
-it to your image, which helps consumers and tools understand the origin,
-contents, and how to use the image.
-
-> [!TIP]
-> Why not just define these additional build options in the Compose file
-> directly?
->
-> The `build` property in the Compose file format does not support all build
-> features. Additionally, some features, like multi-platform builds, can
-> drastically increase the time it takes to build a service. For local
-> development, you're better off keeping your build step simple and fast,
-> saving the bells and whistles for release builds.
-
-To add these properties to the images you build with Bake, update the Bake file
-as follows:
-
-```hcl
-group "default" {
- targets = ["vote", "result", "worker"]
-}
-
-target "_common" {
- annotations = ["org.opencontainers.image.authors=username"]
- platforms = ["linux/amd64", "linux/arm64"]
- attest = [
- "type=provenance,mode=max",
- "type=sbom"
- ]
-}
-
-target "vote" {
- inherits = ["_common"]
- target = "final"
-}
-
-target "result" {
- inherits = ["_common"]
-}
-
-target "worker" {
- inherits = ["_common"]
-}
-```
-
-This defines a new `_common` target that defines reusable build configuration
-for adding multi-platform support, annotations, and attestations to your
-images. The reusable target is inherited by the build targets.
-
-With these changes, building the project with Bake produces three sets of
-multi-platform images for the `linux/amd64` and `linux/arm64` architectures.
-Each image is decorated with an author annotation, and both SBOM and provenance
-attestation records.
-
-## Conclusions
-
-The pattern demonstrated in this guide provides a useful approach for managing
-production-ready Docker images in projects using Docker Compose. Using Bake
-gives you access to all the powerful features of Buildx and BuildKit, and also
-helps separate your development and build configuration in a reasonable way.
-
-### Further reading
-
-For more information about how to use Bake, check out these resources:
-
-- [Bake documentation](/manuals/build/bake/_index.md)
-- [Building with Bake from a Compose file](/manuals/build/bake/compose-file.md)
-- [Bake file reference](/manuals/build/bake/reference.md)
-- [Mastering multi-platform builds, testing, and more with Docker Buildx Bake](/guides/bake/)
-- [Bake GitHub Action](https://github.com/docker/bake-action)
diff --git a/content/guides/firecrawl-sandbox-kit.md b/content/guides/firecrawl-sandbox-kit.md
index aa19302239..56bc31f72b 100644
--- a/content/guides/firecrawl-sandbox-kit.md
+++ b/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
diff --git a/content/guides/gha.md b/content/guides/gha.md
deleted file mode 100644
index b284a2a352..0000000000
--- a/content/guides/gha.md
+++ /dev/null
@@ -1,257 +0,0 @@
----
-title: Introduction to GitHub Actions with Docker
-linkTitle: GitHub Actions and Docker
-summary: |
- Learn how to automate image build and push with GitHub Actions.
-keywords: github actions, ci/cd, docker hub, build and push, automation, workflows
-params:
- tags: [cicd]
- time: 10 minutes
----
-
-This guide provides an introduction to building CI pipelines using Docker and
-GitHub Actions. You will learn how to use Docker's official GitHub Actions to
-build your application as a Docker image and push it to Docker Hub. By the end
-of the guide, you'll have a simple, functional GitHub Actions configuration for
-Docker builds. Use it as-is, or extend it further to fit your needs.
-
-## Prerequisites
-
-If you want to follow along with the guide, ensure you have the following:
-
-- A verified Docker account.
-- Familiarity with Dockerfiles.
-
-This guide assumes basic knowledge of Docker concepts but provides explanations
-for using Docker in GitHub Actions workflows.
-
-## Get the sample app
-
-This guide is project-agnostic and assumes you have an application with a
-Dockerfile.
-
-If you need a sample project to follow along, you can use [this sample
-application](https://github.com/dvdksn/rpg-name-generator.git), which includes
-a Dockerfile for building a containerized version of the app. Alternatively,
-use your own GitHub project or create a new repository from the template.
-
-{{% dockerfile.inline %}}
-
-{{ $data := resources.GetRemote "https://raw.githubusercontent.com/dvdksn/rpg-name-generator/refs/heads/main/Dockerfile" }}
-
-```dockerfile {collapse=true}
-{{ $data.Content }}
-```
-
-{{% /dockerfile.inline %}}
-
-## Configure your GitHub repository
-
-The workflow in this guide pushes the image you build to Docker Hub. To do
-that, you must authenticate with your Docker credentials (username and access
-token) as part of the GitHub Actions workflow.
-
-For instructions on how to create a Docker access token, see
-[Create and manage access tokens](/manuals/security/access-tokens/personal-access-tokens.md).
-
-Once you have your Docker credentials ready, add the credentials to your GitHub
-repository so you can use them in GitHub Actions:
-
-1. Open your repository's **Settings**.
-2. Under **Security**, go to **Secrets and variables > Actions**.
-3. Under **Secrets**, create a new repository secret named `DOCKER_PASSWORD`,
- containing your Docker access token.
-4. Next, under **Variables**, create a `DOCKER_USERNAME` repository variable
- containing your Docker Hub username.
-
-## Set up your GitHub Actions workflow
-
-GitHub Actions workflows define a series of steps to automate tasks, such as
-building and pushing Docker images, in response to triggers like commits or
-pull requests. In this guide, the workflow focuses on automating Docker builds
-and testing, ensuring your containerized application works correctly before
-publishing it.
-
-Create a file named `docker-ci.yml` in the `.github/workflows/` directory of
-your repository. Start with the basic workflow configuration:
-
-```yaml
-name: Build and Push Docker Image
-
-on:
- push:
- branches:
- - main
- pull_request:
-```
-
-This configuration runs the workflow on pushes to the main branch and on pull
-requests. By including both triggers, you can ensure that the image builds
-correctly for a pull request before it's merged.
-
-## Extract metadata for tags and annotations
-
-For the first step in your workflow, use the `docker/metadata-action` to
-generate metadata for your image. This action extracts information about your
-Git repository, such as branch names and commit SHAs, and generates image
-metadata such as tags and annotations.
-
-Add the following YAML to your workflow file:
-
-```yaml
-jobs:
- build:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@{{% param "checkout_action_version" %}}
- - name: Extract Docker image metadata
- id: meta
- uses: docker/metadata-action@{{% param "metadata_action_version" %}}
- with:
- images: ${{ vars.DOCKER_USERNAME }}/my-image
-```
-
-These steps prepare metadata to tag and annotate your images during the build
-and push process.
-
-- The **Checkout** step clones the Git repository.
-- The **Extract Docker image metadata** step extracts Git metadata and
- generates image tags and annotations for the Docker build.
-
-## Authenticate to your registry
-
-Before you build the image, authenticate to your registry to ensure that you
-can push your built image to the registry.
-
-To authenticate with Docker Hub, add the following step to your workflow:
-
-```yaml
- - name: Log in to Docker Hub
- uses: docker/login-action@{{% param "login_action_version" %}}
- with:
- username: ${{ vars.DOCKER_USERNAME }}
- password: ${{ secrets.DOCKER_PASSWORD }}
-```
-
-This step uses the Docker credentials [configured in the repository settings](#configure-your-github-repository).
-
-## Build and push the image
-
-Finally, build the final production image and push it to your registry. The
-following configuration builds the image and pushes it directly to a registry.
-
-```yaml
- - name: Build and push Docker image
- uses: docker/build-push-action@{{% param "build_push_action_version" %}}
- with:
- push: ${{ github.event_name != 'pull_request' }}
- tags: ${{ steps.meta.outputs.tags }}
- annotations: ${{ steps.meta.outputs.annotations }}
-```
-
-In this configuration:
-
-- `push: ${{ github.event_name != 'pull_request' }}` ensures that images are
- only pushed when the event is not a pull request. This way, the workflow
- builds and tests images for pull requests but only pushes images for commits
- to the main branch.
-- `tags` and `annotations` use the outputs from the metadata action to apply
- consistent tags and [annotations](/manuals/build/metadata/annotations.md) to
- the image automatically.
-
-## Attestations
-
-SBOM (Software Bill of Materials) and provenance attestations improve security
-and traceability, ensuring your images meet modern software supply chain
-requirements.
-
-With a small amount of additional configuration, you can configure
-`docker/build-push-action` to generate Software Bill of Materials (SBOM) and
-provenance attestations for the image, at build-time.
-
-To generate this additional metadata, you need to make two changes to your
-workflow:
-
-- Before the build step, add a step that uses `docker/setup-buildx-action`.
- This action configures your Docker build client with additional capabilities
- that the default client doesn't support.
-- Then, update the **Build and push Docker image** step to also enable SBOM and
- provenance attestations.
-
-Here's the updated snippet:
-
-```yaml
- - name: Set up Docker Buildx
- uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
-
- - name: Build and push Docker image
- uses: docker/build-push-action@{{% param "build_push_action_version" %}}
- with:
- push: ${{ github.event_name != 'pull_request' }}
- tags: ${{ steps.meta.outputs.tags }}
- annotations: ${{ steps.meta.outputs.annotations }}
- provenance: true
- sbom: true
-```
-
-For more details about attestations, refer to
-[the documentation](/manuals/build/metadata/attestations/_index.md).
-
-## Conclusion
-
-With all the steps outlined in the previous section, here's the full workflow
-configuration:
-
-```yaml
-name: Build and Push Docker Image
-
-on:
- push:
- branches:
- - main
- pull_request:
-
-jobs:
- build:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@{{% param "checkout_action_version" %}}
-
- - name: Extract Docker image metadata
- id: meta
- uses: docker/metadata-action@{{% param "metadata_action_version" %}}
- with:
- images: ${{ vars.DOCKER_USERNAME }}/my-image
-
- - name: Log in to Docker Hub
- uses: docker/login-action@{{% param "login_action_version" %}}
- with:
- username: ${{ vars.DOCKER_USERNAME }}
- password: ${{ secrets.DOCKER_PASSWORD }}
-
- - name: Set up Docker Buildx
- uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
-
- - name: Build and push Docker image
- uses: docker/build-push-action@{{% param "build_push_action_version" %}}
- with:
- push: ${{ github.event_name != 'pull_request' }}
- tags: ${{ steps.meta.outputs.tags }}
- annotations: ${{ steps.meta.outputs.annotations }}
- provenance: true
- sbom: true
-```
-
-This workflow implements best practices for building and pushing Docker images
-using GitHub Actions. This configuration can be used as-is or extended with
-additional features based on your project's needs, such as
-[multi-platform](/manuals/build/building/multi-platform.md).
-
-### Further reading
-
-- Learn more about advanced configurations and examples in the [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) section.
-- For more complex build setups, you may want to consider [Bake](/manuals/build/bake/_index.md). (See also the [Mastering Buildx Bake guide](/guides/bake/).)
-
-- Learn about Docker's managed build service, designed for faster, multi-platform builds, see [Docker Build Cloud](/manuals/build-cloud/_index.md).
diff --git a/content/manuals/_index.md b/content/manuals/_index.md
index d45c635765..f14f606347 100644
--- a/content/manuals/_index.md
+++ b/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
diff --git a/content/manuals/accounts/organization/_index.md b/content/manuals/accounts/organization/_index.md
index 5b1fdaa759..adcd19ea6f 100644
--- a/content/manuals/accounts/organization/_index.md
+++ b/content/manuals/accounts/organization/_index.md
@@ -84,6 +84,11 @@ access to many people at once. Use a team when several members need the
same repositories. Members can belong to the organization without joining
a team.
+For a deployment across your organization, start with
+[Plan and roll out Docker](/manuals/accounts/organization/setup/rollout.md).
+For ongoing membership and permissions decisions, use
+[Plan and maintain user access](/manuals/accounts/organization/manage/user-access.md).
+
## Next steps
Learn how to manage organizations in the following sections.
diff --git a/content/manuals/accounts/organization/activity-logs.md b/content/manuals/accounts/organization/activity-logs.md
index db269a80ca..870b635e3a 100644
--- a/content/manuals/accounts/organization/activity-logs.md
+++ b/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
diff --git a/content/manuals/accounts/organization/manage/_index.md b/content/manuals/accounts/organization/manage/_index.md
index 725b428c2e..14fc31f0ce 100644
--- a/content/manuals/accounts/organization/manage/_index.md
+++ b/content/manuals/accounts/organization/manage/_index.md
@@ -5,6 +5,10 @@ weight: 20
description: Learn how to manage your Docker organization, including members, teams, licenses, seats, product access, and settings.
keywords: manage organization, members, teams, licenses, seats, product access, organization management, docker home, organization settings, deactivate organization
grid:
+ - title: User access workflow
+ description: Plan roles, provisioning, and ongoing access reviews.
+ icon: user-group
+ link: /accounts/organization/manage/user-access/
- title: Information
description: Update your organization's general information and settings.
icon: pencil-square
diff --git a/content/manuals/accounts/organization/manage/manage-licenses.md b/content/manuals/accounts/organization/manage/manage-licenses.md
index 212a957196..4476aeab3f 100644
--- a/content/manuals/accounts/organization/manage/manage-licenses.md
+++ b/content/manuals/accounts/organization/manage/manage-licenses.md
@@ -117,11 +117,11 @@ card.
When the toggle is on:
-- Docker Team or Business: members receive a license when they sign in to
+- Docker Team or Business: members receive a license when they use
Docker Desktop.
-- AI Governance: members receive a license when they sign in to
- [Docker Sandboxes](/manuals/ai/sandboxes/_index.md). The `sbx login`
- command provisions licenses on a first-come, first-served basis.
+- AI Governance: members receive a license when they use
+ [Docker Sandboxes](/manuals/ai/sandboxes/_index.md).
+- Licenses are provisioned on a first-come, first-served basis.
- Licenses are assigned until exhausted.
- Once the available licenses are exhausted, automatic license assignment
stops until more licenses are available.
diff --git a/content/manuals/accounts/organization/manage/manage-products.md b/content/manuals/accounts/organization/manage/manage-products.md
index fa8ae9a7fa..bc3e7e0084 100644
--- a/content/manuals/accounts/organization/manage/manage-products.md
+++ b/content/manuals/accounts/organization/manage/manage-products.md
@@ -2,8 +2,14 @@
title: Manage usage and access for Docker products
linkTitle: Products
weight: 60
-description: Learn how to manage access and usage for Docker products for your organization
-keywords: organization, product access, product usage, access control, docker desktop, docker hub, docker scout, docker build cloud, docker offload, testcontainers cloud
+description: >-
+ Control which Docker products organization members can use, and find
+ where to check usage
+keywords: organization, product access, product usage, access control, seats,
+ licenses, docker desktop, docker hub, docker scout, docker build cloud,
+ docker offload, docker offload v1, testcontainers cloud, docker sandboxes,
+ ai governance
+toc_max: 2
aliases:
- /admin/organization/manage/manage-products/
- /admin/organization/manage-products/
@@ -12,17 +18,38 @@ aliases:
{{< summary-bar feature_name="Admin orgs" >}}
Use this page to learn how to control and monitor product access and usage
-for your organization's members. If you're looking for setup and
-configuration instructions, see each product's manual under
-[Next steps](#next-steps).
+for your organization's members.
-## Control access for your organization
+## How product access and usage works
-Organization members can access Docker products that your organization is
-subscribed to by default. When signed in as an organization owner, you can
-use the following procedures to control access for all members.
+Members receive access to products through seats, licenses, and the controls
+you configure:
-### Docker Desktop access
+- A member uses one seat on a Docker Team or Business
+ [subscription](/manuals/subscription-billing/plans/_index.md). The seat
+ includes the products in the plan, such as Docker Desktop and Docker Hub.
+- Some products need a separate
+ [license](/manuals/accounts/organization/manage/manage-licenses.md) that
+ you assign to teams or members.
+- After a member has a seat or license, the controls on this page set what
+ they can do in each product, such as which Hub images they can pull,
+ which repositories Scout analyzes, or whether Docker Offload v1 is
+ available in Docker Desktop.
+
+Where a product has a usage allowance, the **Usage** section shows where to
+check how much of it the organization has used. Products measure that
+allowance in different units, such as build minutes, Hub pulls, or runtime
+minutes.
+
+This page covers product access, but does not cover access tokens.
+For organization access tokens,
+see [Access tokens](/manuals/security/access-tokens/_index.md).
+
+## Docker Desktop
+
+For setup and configuration, see the [Docker Desktop manual](../../../desktop/_index.md).
+
+### Access
To manage Docker Desktop access:
@@ -30,12 +57,12 @@ To manage Docker Desktop access:
1. Manage members [manually](./members.md) or use
[provisioning](../../../security/provisioning/_index.md).
-With sign-in enforced, only users who are a member of your organization can
-use Docker Desktop after signing in.
+With sign-in enforced, only members of your organization can use Docker
+Desktop after they sign in.
-### Docker Hub access
-
-To manage Docker Hub access:
+Image Access and Registry Access are Docker Desktop controls. Image Access
+limits which images members can pull from Docker Hub. Registry Access
+limits which registries Docker Desktop can reach.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization, then select **Docker Desktop**.
@@ -44,113 +71,206 @@ To manage Docker Hub access:
1. Select **Image Access** to control
[Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md).
-### Docker Build Cloud access
+### Usage
-To initially set up and configure Docker Build Cloud, sign in to
-[Docker Build Cloud](https://app.docker.com/build) and follow the
-on-screen instructions.
+Desktop insights shows how members use Docker Desktop, including active
+users, builds, containers, images, and extensions.
+
+1. Sign in to [Docker Home](https://app.docker.com/) and select your
+ organization.
+1. Select **Docker Desktop**, then
+ [**Desktop insights**](/manuals/accounts/organization/insights.md).
+
+## Docker Hub
+
+For setup and configuration, see the [Docker Hub manual](../../../docker-hub/_index.md).
+
+### Usage
+
+Hub usage counts how many times members pull images and how much space
+your organization's repositories take up.
+
+1. Sign in to [Docker Home](https://app.docker.com/) and select your
+ organization.
+1. Select **Go to Hub**.
+1. Select **Usage**, then **Pulls** or **Storage**. For example,
+ `https://hub.docker.com/orgs/{namespace}/usage`.
+
+## Docker Build Cloud
+
+For setup and configuration, see the [Docker Build Cloud manual](../../../build-cloud/_index.md).
+
+### Access
+
+To set up Docker Build Cloud, sign in to
+[Docker Build Cloud](https://app.docker.com/build) and follow the on-screen
+instructions.
To manage Docker Build Cloud access:
-1. Sign in to [Docker Home](https://app.docker.com/), then select
- [Docker Build Cloud](http://app.docker.com/build).
-1. Select **Account settings**.
+1. Sign in to [Docker Home](https://app.docker.com/) and select your
+ organization.
+1. Select **Build Cloud**, then **Account settings**.
1. Select **Lock access to Docker Build Account**.
-### Docker Scout access
+> [!WARNING]
+>
+> **Lock access to Docker Build Account** removes the ability to use cloud
+> builders or build minutes, and it purges build data.
-To initially set up and configure Docker Scout, sign in to
-[Docker Scout](https://scout.docker.com/) and follow the on-screen
-instructions.
+### Usage
+
+Build minutes are the time your organization spends on cloud builds.
+
+1. Sign in to [Docker Home](https://app.docker.com/) and select your
+ organization.
+1. Select **Build Cloud**, then **Build minutes**.
+
+## Docker Scout
+
+For setup and configuration, see the [Docker Scout manual](../../../scout/_index.md).
+
+### Access
+
+To set up Docker Scout, sign in to [Docker Scout](https://scout.docker.com/)
+and follow the on-screen instructions.
To manage Docker Scout access:
1. Sign in to [Docker Home](https://app.docker.com/), then select
[Docker Scout](https://scout.docker.com/).
1. Select your organization, then **Settings**.
-1. To manage what repositories are enabled for Docker Scout analysis, select
- **Repository settings**. For more information, see
- [repository settings](../../../scout/explore/dashboard.md#repository-settings).
-1. To manage access to Docker Scout for use on local images with Docker
- Desktop, use
+1. To manage which repositories Docker Scout analyzes, select
+ **Repository settings**. See
+ [Repository settings](../../../scout/explore/dashboard.md#repository-settings).
+1. To manage Docker Scout for local images in Docker Desktop, use
[Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md)
- and set `sbomIndexing` to `false` to disable, or to `true` to enable.
+ and set **SBOM indexing** (`sbomIndexing`) to **Enabled**, **Disabled**,
+ or **User defined**. **Enabled** indexes images when they are inspected
+ in Docker Desktop or with Docker Scout CLI commands.
-### Testcontainers Cloud access
+### Usage
-To initially set up and configure Testcontainers Cloud, sign in to
+[Repository settings](../../../scout/explore/dashboard.md#repository-settings)
+lists the repositories Docker Scout analyzes. Follow the access steps above
+and select **Repository settings**.
+
+## Testcontainers Cloud
+
+For setup and configuration, see
+[Get started with Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started).
+
+### Access
+
+To set up Testcontainers Cloud, sign in to
[Testcontainers Cloud](https://app.testcontainers.cloud/) and follow the
on-screen instructions.
To manage access to Testcontainers Cloud:
-1. Sign in to the [Testcontainers Cloud](https://app.testcontainers.cloud/),
+1. Sign in to [Testcontainers Cloud](https://app.testcontainers.cloud/),
then select the menu icon.
1. Select **Account**, then **Settings**.
-1. Choose **Lock access to Testcontainers Cloud**.
+1. Select **Lock access to Testcontainers Cloud**.
-### Docker Offload access
+### Usage
-> [!NOTE]
->
-> Docker Offload isn't included in the core Docker subscription plans. To
-> make Docker Offload available, you must
-> [contact sales](https://www.docker.com/products/docker-offload/) and
-> subscribe.
+Billing shows the Testcontainers Cloud runtime minutes included with your
+subscription.
-To manage Docker Offload access for your organization, use [Settings
+1. Sign in to [Docker Home](https://app.docker.com/) and select your
+ organization.
+1. Select **Go to Testcontainers Cloud**.
+1. Select the menu icon, then
+ [**Billing**](https://app.testcontainers.cloud/dashboard/billing).
+
+## Docker Offload v1
+
+For setup and configuration, see the [Docker Offload v1 manual](../../../offload/v1/_index.md).
+
+Docker Offload v1 uses its own [license](./manage-licenses.md). Assign it to
+teams or members, or turn on automatic assignment so members receive a
+license the first time they use Docker Offload v1.
+
+### Access
+
+**Offload access** turns Docker Offload v1 on or off for the organization.
+**Disabled** removes the ability for anybody in the organization, including
+CI/CD, to use Offload resources or consume Offload minutes.
+
+1. Sign in to [Docker Home](https://app.docker.com/) and select your
+ organization.
+1. Select **Docker Offload**, then **Offload access**.
+1. Set **Enable Docker Offload** to **Enabled** or **Disabled**.
+1. When Offload is enabled, select **Allow GPU access** to let members run
+ GPU workloads in cloud mode.
+
+To set the Docker Offload v1 default inside Docker Desktop, use [Settings
Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md):
-1. Sign in to [Docker Home](https://app.docker.com/), then select **Docker
- Desktop**.
-1. Select **Settings Management**.
-1. Configure the **Enable Docker Offload** setting to control whether
- Docker Offload features are available in Docker Desktop. You can
- configure this setting in five states:
- - **Always enabled**: Docker Offload is always enabled and users cannot
- disable it. The Offload toggle is always visible in the Docker Desktop
- header. Recommended for VDI environments where local Docker execution
- is not possible.
- - **Enabled**: Docker Offload is enabled by default but users can
- disable it in Docker Desktop settings. Suitable for hybrid
- environments.
- - **Disabled**: Docker Offload is disabled by default but users can
- enable it in Docker Desktop settings.
- - **Always disabled**: Docker Offload is disabled and users cannot
- enable it. The option is visible but locked. Use when Docker Offload
- is not approved for organizational use.
- - **User defined**: No enforced default. Users choose whether to enable
- or disable Docker Offload in their Docker Desktop settings.
+1. Select **Docker Desktop**, then **Settings Management**.
+1. Set **Enable Docker Offload** to one of these configurations:
+ - **Always enabled**: Offload stays on, and members cannot turn it off.
+ - **Enabled**: Offload is on by default, and members can turn it off.
+ - **Disabled**: Offload is off by default, and members can turn it on.
+ - **Always disabled**: Offload stays off, and members cannot turn it on.
+ - **User defined**: Docker Desktop does not enforce a default. Members
+ choose whether to turn Offload on.
1. Select **Save**.
For more details on Settings Management, see the [Settings
reference](/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md#enable-docker-offload).
-## Monitor product usage for your organization
+### Usage
-You can monitor usage for Docker products across your organization. Use the
-following table to learn where you can monitor organization usage:
+[Offload activity](../../../offload/v1/usage.md) shows Docker Offload v1
+sessions, including how long they ran and which images they used.
-| Product | Monitor usage |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Docker Desktop | From [Docker Home](https://app.docker.com/), view the [**Insights**](/manuals/accounts/organization/insights.md) page. |
-| Docker Hub | From Docker Hub, view the [**Usage** page](https://hub.docker.com/usage). |
-| Docker Build Cloud | From [Docker Build Cloud](http://app.docker.com/build), view the **Build minutes** page. |
-| Docker Scout | From [Docker Home](https://app.docker.com/), select **Go to Scout** to view the [**Repository settings** page](https://scout.docker.com/settings/repos). |
-| Testcontainers Cloud | From [Docker Home](https://app.docker.com/), select **Go to Testcontainers Cloud**, then select the menu icon. Go to the [**Billing** page](https://app.testcontainers.cloud/dashboard/billing). |
-| Docker Offload | From [Docker Home](https://app.docker.com/), select **Offload**, then **Offload activity**. See [Docker Offload usage and billing](../../../offload/usage.md) for more details. |
+1. Sign in to [Docker Home](https://app.docker.com/) and select your
+ organization.
+1. Select **Docker Offload**, then **Offload activity**.
-If your usage or seat count exceeds your subscription amount, you can
-[add seats](./manage-seats.md) or [view available Docker plans](../../../subscription-billing/plans/_index.md) to meet your needs.
+## AI Governance
+
+For setup and configuration, see
+[Docker Sandboxes](../../../ai/sandboxes/_index.md) and
+[AI Governance](../../../ai/governance/_index.md).
+
+AI Governance is the separate paid subscription that adds the
+organization-level controls to
+[Docker Sandboxes](../../../ai/sandboxes/_index.md): policies for what
+members' local sandboxes can reach on the network, mount from the filesystem,
+or call through MCP, plus sign-in enforcement and audit logs.
+
+### Access
+
+Organization policies govern only members who hold an AI Governance license.
+
+- [Manage licenses](./manage-licenses.md): assign AI Governance licenses to
+ teams or members, or turn on **Automatic license assignment** so members
+ receive a license when they run `sbx login`.
+- [Organization policies](../../../ai/governance/organization/policies/create-manage.md):
+ create network, filesystem, and MCP policies under **AI Platform** in Docker
+ Home, and scope them to the whole organization or to specific teams.
+- [Sign-in enforcement](../../../ai/governance/organization/sign-in-enforcement.md):
+ deploy a configuration through your endpoint management tooling so
+ `sbx login` succeeds only for members of your organization.
+
+### Usage
+
+- [View licenses](./manage-licenses.md#view-licenses): the **Licenses** page
+ shows how many AI Governance licenses you have, how many are assigned, and
+ whether the assignments go to teams or to individual members.
+- [View and export audit events](../../../ai/governance/organization/audit/view-export.md):
+ **AI Platform** > **Audit logs** shows the policy decisions Docker recorded
+ for members' sandboxes, including who made the request, which resource it
+ targeted, and whether Docker allowed or denied it.
## Next steps
-For more detailed information about each product, including how to set up
-and configure them, see the following manuals:
-
-- [Docker Desktop](../../../desktop/_index.md)
-- [Docker Hub](../../../docker-hub/_index.md)
-- [Docker Build Cloud](../../../build-cloud/_index.md)
-- [Docker Scout](../../../scout/_index.md)
-- [Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started)
-- [Docker Offload](../../../offload/_index.md)
+- [Manage subscription seats](./manage-seats.md) to add seats, and
+ [Manage licenses](./manage-licenses.md) to assign product licenses.
+- [Invite and manage organization members](./members.md) to invite people
+ and assign roles.
+- [Plan and maintain user access](./user-access.md) to choose roles,
+ provisioning, and how you review access.
diff --git a/content/manuals/accounts/organization/manage/user-access.md b/content/manuals/accounts/organization/manage/user-access.md
new file mode 100644
index 0000000000..2295934b1e
--- /dev/null
+++ b/content/manuals/accounts/organization/manage/user-access.md
@@ -0,0 +1,130 @@
+---
+title: Plan and maintain user access
+linkTitle: User access workflow
+weight: 15
+description: Identify Docker users, choose roles and provisioning methods, and review access and adoption across your organization.
+keywords: admin, user management, roles, permissions, SSO, provisioning, access control
+aliases:
+ - /guides/admin-user-management/
+ - /guides/admin-user-management/audit-and-monitor/
+ - /guides/admin-user-management/onboard/
+ - /guides/admin-user-management/setup/
+---
+
+Use this workflow to decide who needs access to your Docker organization,
+assign appropriate permissions, and keep membership aligned with changing
+responsibilities. It links to the procedures for onboarding, provisioning,
+and monitoring so you can apply those decisions.
+
+## Setting up roles and permissions in Docker
+
+### Identify your Docker users and accounts
+
+Inventory the people who need Docker access, the projects they work on, and
+the resources they need. Use device management records or ask development
+teams to identify existing Docker Desktop users. Ask users to use their
+business email for their Docker accounts.
+
+Follow [organization onboarding](/manuals/accounts/organization/setup/onboard.md)
+for the identification procedure and seat planning. Keep this inventory as
+the starting point for access reviews.
+
+### Assign roles strategically
+
+Choose the minimum permissions each person needs. Compare the built-in
+Member, Editor, and Owner roles with
+[Roles and permissions](/manuals/security/roles-and-permissions/_index.md).
+If you need a combination of permissions that the built-in roles don't
+provide, consider custom roles, which require Docker Business.
+
+#### Enhance with teams
+
+Group members by project, department, or shared repository needs. A member's
+role determines organization-wide access, while team permissions apply to
+specific repositories. Avoid granting an administrative role solely because
+a developer needs access to a project's repositories.
+
+Use [Create and manage a team](/manuals/accounts/organization/manage/manage-a-team.md)
+to apply repository permissions to groups of members. Review team membership
+when projects or responsibilities change.
+
+## Onboarding and managing roles and permissions in Docker
+
+### Invite owners
+
+Decide who needs to administer membership, settings, and billing. Additional
+owners can share these responsibilities and provide continuity when another
+owner is unavailable. Review the permissions before assigning the role.
+
+### Invite members and assign roles
+
+Use your access inventory to assign roles and teams. Follow
+[Onboard a Docker organization](/manuals/accounts/organization/setup/onboard.md)
+for initial setup and
+[Manage organization members](/manuals/accounts/organization/manage/members.md)
+for invitations and membership changes.
+
+### Choose a provisioning method {#future-proof-user-management}
+
+Decide who will maintain membership as people join, move between teams, or
+leave. Manual invitations can suit a small organization. For Docker Business
+organizations using an identity provider, compare the
+[provisioning methods](/manuals/security/provisioning/_index.md) before
+choosing how to automate membership.
+
+#### Secure user authentication with single sign-on (SSO)
+
+[SSO](/manuals/security/authentication/single-sign-on/_index.md) authenticates
+users through your identity provider. Plan it together with provisioning,
+which controls account creation, updates, and removal.
+
+#### Automate onboarding with SCIM and JIT provisioning
+
+Choose a method based on the user lifecycle you need to manage:
+
+- [Just-in-Time (JIT) provisioning](/manuals/security/provisioning/just-in-time.md)
+ creates and updates accounts during SSO sign-in. It doesn't deprovision users,
+ so plan how to remove access when users leave.
+- [SCIM](/manuals/security/provisioning/scim/_index.md) synchronizes users
+ with your identity provider and supports deprovisioning. If you enable SCIM,
+ choose how it will work with JIT so the intended source manages user attributes.
+
+Test adding a user, changing their team, and removing access before relying
+on automated provisioning for the whole organization.
+
+#### Simplify access with group mapping
+
+Use [group mapping](/manuals/security/provisioning/scim/group-mapping.md)
+to assign identity provider groups to Docker organizations and teams.
+Group mapping works with SAML SSO or SCIM. For Microsoft Entra ID OIDC
+connections, use SCIM to synchronize groups. Review the mappings when your
+identity provider groups change.
+
+## Monitoring and insights
+
+Schedule access reviews with organization owners and team leads. Compare
+membership with your access inventory, remove users who no longer need
+access, and adjust roles and teams when responsibilities change.
+
+### Activity logs
+
+Use [activity logs](/manuals/accounts/organization/activity-logs.md) to review
+organization and repository changes, including repository privacy changes
+and subscription seat changes. Check who made an unexpected change and when
+it happened. Docker Home retains logs for 90 days; plan exports if your audit
+process needs a longer history.
+
+### Insights
+
+If your organization meets the subscription and configuration requirements,
+use [Insights](/manuals/accounts/organization/insights.md) to review Docker
+Desktop adoption, versions, builds, and container usage. Active user counts
+include only users who send analytics. Compare usage with your membership
+inventory before deciding whether to change access or subscription seats.
+
+### Next steps
+
+- Review [members](/manuals/accounts/organization/manage/members.md) and
+ [teams](/manuals/accounts/organization/manage/manage-a-team.md) on a regular schedule.
+- Use [rollout planning](/manuals/accounts/organization/setup/rollout.md)
+ before deploying changes to Docker Desktop settings or sign-in requirements.
diff --git a/content/manuals/accounts/organization/setup/_index.md b/content/manuals/accounts/organization/setup/_index.md
index 4d94e13294..54662b835d 100644
--- a/content/manuals/accounts/organization/setup/_index.md
+++ b/content/manuals/accounts/organization/setup/_index.md
@@ -13,6 +13,10 @@ keywords:
- organization namespace
- Docker Home
grid:
+ - title: Plan your rollout
+ description: Coordinate settings, pilot testing, and deployment.
+ icon: magnifying-glass-plus
+ link: /accounts/organization/setup/rollout/
- title: Create your organization
description: Choose a new namespace and subscription.
icon: building-storefront
diff --git a/content/manuals/accounts/organization/setup/onboard.md b/content/manuals/accounts/organization/setup/onboard.md
index 950c246a72..bf0798ee32 100644
--- a/content/manuals/accounts/organization/setup/onboard.md
+++ b/content/manuals/accounts/organization/setup/onboard.md
@@ -170,6 +170,9 @@ Use these features to manage your organization's security posture:
## Next steps
+- [Plan your rollout](/manuals/accounts/organization/setup/rollout.md) to
+ coordinate pilot testing and deployment with your IT teams.
+
- [Manage Docker products](../manage/manage-products.md) to configure
access and view usage.
- Configure
diff --git a/content/manuals/accounts/organization/setup/rollout.md b/content/manuals/accounts/organization/setup/rollout.md
new file mode 100644
index 0000000000..f7d381f645
--- /dev/null
+++ b/content/manuals/accounts/organization/setup/rollout.md
@@ -0,0 +1,158 @@
+---
+title: Plan and roll out Docker
+linkTitle: Plan your rollout
+weight: 40
+description: Coordinate stakeholders, define Docker Desktop settings, test with a pilot group, and roll out Docker across your organization.
+keywords: admin, onboarding, deployment, organization setup, Docker Desktop, rollout
+aliases:
+ - /guides/admin-set-up/
+ - /guides/admin-set-up/comms-and-info-gathering/
+ - /guides/admin-set-up/deploy/
+ - /guides/admin-set-up/finalize-plans-and-setup/
+ - /guides/admin-set-up/testing/
+---
+
+Use this workflow to plan a Docker rollout across your organization, test its
+settings with a pilot group, and coordinate deployment with your IT teams.
+For invitations and sign-in configuration, follow
+[Onboard a Docker organization](/manuals/accounts/organization/setup/onboard.md).
+
+## Who needs to be involved
+
+Identify the people responsible for each part of the rollout:
+
+- Organization owners to manage membership and organization settings
+- DNS and identity provider teams to verify domains and configure single sign-on (SSO)
+- IT and mobile device management (MDM) teams to distribute Docker Desktop and configuration files
+- Development leads and security representatives to agree on settings and security requirements
+- A small group of developers to test the configuration before wider deployment
+
+## Communication and information gathering
+
+### Communicate with your developers and IT teams
+
+Notify existing Docker Desktop users before changing versions, settings, or
+sign-in requirements. Explain which changes they should expect, when the pilot
+and wider rollout will happen, and where to report problems. Ask users to use
+their business email for their Docker accounts.
+
+Engage your MDM team early to understand deployment requirements and lead
+times. Agree on how to distribute configuration files, registry keys, or
+`.plist` files for your chosen deployment method.
+
+### Identify Docker organizations
+
+Survey teams to find existing Docker organizations and decide which ones
+should be part of the rollout. If you need to administer multiple
+organizations together, consider a
+[Docker company](/manuals/accounts/company/_index.md). A company groups Docker
+organizations; it is separate from the business deploying Docker Desktop.
+
+### Gather requirements
+
+Work with organization owners, development leads, and security representatives
+to define a baseline that supports development workflows and company policies.
+Agree on:
+
+- Docker Desktop versions and update policies
+- Settings developers can change and settings administrators must control
+- Sign-in requirements, identity provider integration, and user provisioning
+- Approved image sources and registries
+- Additional Docker products your teams need and the subscriptions they require
+
+Review [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md)
+and [Hardened Docker Desktop](/manuals/desktop/enterprise/hardened-desktop/_index.md)
+to choose controls available with your subscription.
+
+## Finalize plans and begin setup
+
+### Send finalized settings files to the MDM team
+
+Record the agreed baseline and configure it through
+[Docker Home](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md)
+or an [`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md),
+as appropriate for your subscription and deployment method. Coordinate with
+your MDM team to prepare the configuration and your chosen method for
+[enforcing sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md).
+Deploy to the pilot group before applying the settings more widely.
+
+### Begin setup
+
+Follow [organization onboarding](/manuals/accounts/organization/setup/onboard.md)
+to identify users, invite owners and members, and configure sign-in and
+provisioning. SSO and SCIM require Docker Business. Plan authentication and
+provisioning together: SSO authenticates users, while provisioning controls
+how users are added, updated, and removed.
+
+Choose a supported Docker Desktop version and agree with IT on how users will
+receive it through MDM, a software portal, or direct installation. See
+[Docker Desktop deployment](/manuals/desktop/enterprise/enterprise-deployment.md).
+
+If your rollout includes other Docker products, confirm access and complete
+their setup before the pilot. For example, follow the setup documentation for
+[Docker Build Cloud](/manuals/build-cloud/setup/_index.md),
+[Docker Scout](/manuals/scout/quickstart.md), or
+[Docker Hardened Images](/manuals/dhi/get-started.md).
+
+## Testing
+
+### SSO and SCIM testing
+
+If you configure SSO or SCIM, test sign-in, provisioning, role assignments,
+and team membership with pilot accounts. Include a user joining the
+organization and a user leaving it. Follow the
+[provisioning documentation](/manuals/security/provisioning/_index.md)
+for the behavior of your chosen method. Check CLI authentication as well as
+Docker Desktop and browser sign-in.
+
+### Test Registry Access Management and Image Access Management
+
+If your subscription and rollout include
+[Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md)
+or [Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md),
+verify that pilot users can pull approved images and that configured
+restrictions block disallowed sources. Tell pilot users about these
+restrictions before testing them.
+
+### Deploy settings and enforce sign in to test group
+
+Apply the baseline settings and sign-in requirements to the pilot group.
+Have developers run their normal projects on Docker Desktop and Docker Hub.
+Confirm that required settings apply and that developers can still build,
+pull, and run the containers they need. Use the
+[pilot rollout tutorial](/get-started/tutorials/admin-set-up.md) for a focused
+settings policy test.
+
+For each additional product in your rollout, have a pilot developer complete
+a representative task: build with a cloud builder, review Scout results, or
+pull a Hardened Image. Record problems and adjust the baseline before wider
+deployment.
+
+## Deploy your Docker setup
+
+Communicate the rollout schedule and expected changes to users. Confirm that
+IT and MDM teams are ready to distribute the tested configuration and support
+users who encounter problems.
+
+### Enforce SSO
+
+If your plan includes SSO enforcement, verify that your identity provider
+configuration covers all intended users before enforcing it. Follow
+[Configure SSO](/manuals/security/authentication/single-sign-on/connect.md)
+for setup and enforcement. Enforcing SSO and enforcing Docker Desktop sign-in
+are separate controls.
+
+### Deploy configuration settings and enforce sign-in to users
+
+Have the MDM team distribute the tested Docker configuration to the remaining
+users. Provide instructions for sign-in and a support contact. Review feedback
+after each deployment group before expanding the rollout.
+
+### Next steps
+
+- Review [organization Insights](/manuals/accounts/organization/insights.md),
+ if available for your subscription, to track Docker Desktop adoption and versions.
+- Use the [user access workflow](/manuals/accounts/organization/manage/user-access.md)
+ to review membership and permissions after rollout.
+- Monitor [Docker Scout findings](/manuals/scout/explore/analysis.md) for
+ repositories where you've configured Scout.
diff --git a/content/manuals/agentic-platform/policies.md b/content/manuals/agentic-platform/policies.md
index 87b39384a4..436b40282e 100644
--- a/content/manuals/agentic-platform/policies.md
+++ b/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
diff --git a/content/manuals/ai-overview.md b/content/manuals/ai-overview.md
index e064b00ccb..a6ace5563a 100644
--- a/content/manuals/ai-overview.md
+++ b/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` |
diff --git a/content/manuals/ai/governance/_index.md b/content/manuals/ai/governance/_index.md
new file mode 100644
index 0000000000..3b83656709
--- /dev/null
+++ b/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.
diff --git a/content/manuals/ai/governance/local/_index.md b/content/manuals/ai/governance/local/_index.md
new file mode 100644
index 0000000000..a5d1d3ed69
--- /dev/null
+++ b/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.
diff --git a/content/manuals/ai/governance/local/approvals.md b/content/manuals/ai/governance/local/approvals.md
new file mode 100644
index 0000000000..b339db4a53
--- /dev/null
+++ b/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
+```
+
+For more details, see [Remove a rule](network-rules.md#remove-a-rule).
diff --git a/content/manuals/ai/governance/local/inspect.md b/content/manuals/ai/governance/local/inspect.md
new file mode 100644
index 0000000000..a5ad7de526
--- /dev/null
+++ b/content/manuals/ai/governance/local/inspect.md
@@ -0,0 +1,212 @@
+---
+title: Inspect policy status and rules
+linkTitle: Inspect policies
+weight: 40
+description: List the policies and rules that apply to your sandboxes, see where they come from, and check organization governance status with sbx policy ls.
+keywords: docker sandboxes, sbx policy ls, sbx policy inspect, policy rules, inactive rules, organization governance, policy debugging
+aliases:
+ - /ai/sandboxes/governance/monitoring/
+ - /ai/sandboxes/governance/monitor-and-enforce/monitoring/
+---
+
+Use `sbx policy ls` to see which policies and rules apply to your sandboxes and
+where they come from, and `sbx policy inspect` to see one policy or rule in
+full. A listing includes rules from your local policy, from kits, and from your
+organization, so you can confirm the rules you added and work out why a request
+is allowed or blocked. To watch network activity instead, see
+[Test and monitor network policy](test-monitor.md).
+
+## List the policies that apply
+
+Run `sbx policy ls` to see every active policy:
+
+```console
+$ sbx policy ls
+POLICY SOURCE APPLIES TO SUMMARY
+default-deny-all local all network: deny when no rule decides
+local-policy local all network: 42 allow, 1 deny; filesystem read: 1 allow; filesystem write: 1 allow
+1b2633ea-e604-48bb-a5e6-3ac86ba383fe kit sandbox:my-sandbox network: 3 allow
+```
+
+The columns are:
+
+- `POLICY`: the policy name.
+- `SOURCE`: where the policy came from. `local` means your local policy, which
+ holds your preset and the rules you added with `sbx policy`. `kit` means a
+ [kit](../../sandboxes/customize/use-kits.md). `org` means your organization.
+- `APPLIES TO`: which sandboxes the policy applies to. `all` means the policy
+ is global, and `sandbox:` scopes it to one sandbox.
+- `SUMMARY`: a count of rule entries by type and decision, for example
+ `network: 5 allow, 1 deny`. A rule that names several destinations
+ contributes one entry per destination.
+
+The `default-deny-all` row represents the built-in fallback: access is blocked
+when no applicable policy decides a request. It never overrides an allow rule.
+Its summary describes this condition instead of counting it as an explicit
+deny. For how unmatched requests are handled under each preset, see
+[How rules combine](_index.md#how-rules-combine).
+
+## List the policies for one sandbox
+
+Pass a sandbox name to see only the global policies and the policies scoped to
+that sandbox:
+
+```console
+$ sbx policy ls my-sandbox
+```
+
+The output groups rules by type. For example, the network section for a sandbox
+with 42 allowed hosts and one explicitly denied host in its local policy shows:
+
+```text
+NETWORK
+ • allow 42 hosts from local-policy
+ • deny 1 host from local-policy
+ • fallback: deny when no rule decides from default-deny-all
+```
+
+The fallback appears on its own line, so `deny 1 host` counts only the explicit
+deny. Other policies, such as those provided by kits, also contribute to the
+sandbox's summary. To see each rule, add `--wide`.
+
+## Show rule details
+
+Pass `--wide` to list each rule on its own row, with its rule ID, type,
+decision, protocols, and resources:
+
+```console
+$ sbx policy ls --wide
+```
+
+Use the rule ID from this listing to remove a rule with
+`sbx policy rm network --id`. For more details, see
+[Remove a rule](network-rules.md#remove-a-rule).
+
+To see one policy or rule in full, pass its name or rule ID to
+`sbx policy inspect`:
+
+```console
+$ sbx policy inspect local-policy
+```
+
+## Filter the listing
+
+Filters work with both the summary and the `--wide` listing:
+
+- `--type`: show only `network`, `http`, or `filesystem` policies.
+- `--source`: show only policies from `local`, `kit`, or `org`.
+- `--decision`: show only `allow` or `deny` rules.
+- `--protocol`: show only network rules for `tcp` or `udp`.
+- `--created-via`: show only rules created a certain way. Pass `default` for
+ preset rules, `added` for rules you added yourself, `provisioned` for rules a
+ kit or application added, or `approval` for rules recorded when you approved
+ a destination.
+
+For example, to list the destinations you've approved:
+
+```console
+$ sbx policy ls --wide --created-via approval
+```
+
+For more details, see [Respond to approval requests](approvals.md).
+
+To list the rules a kit added to a sandbox:
+
+```console
+$ sbx policy ls my-sandbox --source kit --wide
+```
+
+## List HTTP rules
+
+Rules that match an HTTP method and path have the type `http`. To list only
+those rules, pass `--type http`:
+
+```console
+$ sbx policy ls --type http
+```
+
+In a `--wide` listing, HTTP rules fill the `METHOD` and `PATH` columns. Rules
+that match a whole destination show `-` in both columns.
+
+In the `SUMMARY` column, HTTP rules count as network rules, and each part is
+labeled by the network layer it matches on. `L4` counts entries that match a
+whole destination, and `L7` counts entries that also match an HTTP method and
+path:
+
+```console
+$ sbx policy ls
+POLICY SOURCE APPLIES TO SUMMARY
+local-policy local all network: 2 allow (L4), 1 deny (L7)
+```
+
+When the same decision has entries at both layers, each layer gets its own
+count, L4 first. Two host allows and one HTTP allow read
+`network: 2 allow (L4), 1 allow (L7)`.
+
+The labels appear only when the listing includes at least one HTTP rule.
+Because filters and hidden inactive rules change what the listing contains, a
+filtered listing with no HTTP rules shows an unlabeled count, such as
+`network: 42 allow`.
+
+For more details, see
+[HTTP method and path](../reference/network-rules.md#http-method-and-path).
+
+## List filesystem mount rules
+
+Filesystem mount rules control which host paths a sandbox can mount as a workspace.
+To list only those rules, pass `--type filesystem`:
+
+```console
+$ sbx policy ls --type filesystem
+POLICY SOURCE APPLIES TO SUMMARY
+local-policy local all filesystem read: 1 allow; filesystem write: 1 allow
+```
+
+Your local policy allows read and write access to all paths by default, shown
+as the two allow entries above. For how read and write rules combine, see
+[Filesystem mount rule syntax](../reference/filesystem-rules.md).
+
+## Check organization governance status
+
+When an organization policy is enforced for you, `sbx policy ls` starts with a
+status line:
+
+```console
+$ sbx policy ls
+Governance: Managed by my-org · Sync: OK, last synced 08:21:01 · Hidden: 9 inactive rules. Show with: sbx policy ls --include-inactive
+
+POLICY SOURCE APPLIES TO SUMMARY
+default filesystem org all filesystem read: 2 allow; filesystem write: 7 allow, 2 deny
+default network org all network: 38 allow, 4 deny
+```
+
+A `--wide` listing shows the same fields as a `POLICY RULES` block above the
+table.
+
+- `Governance` shows which organization manages the policy.
+- `Sync` shows when the daemon last pulled the organization policy. If it shows
+ an error or an old timestamp, run `sbx policy refresh` to fetch and apply the
+ latest organization policy right away. For more details, see
+ [Organization policy changes aren't taking effect](../troubleshooting.md#organization-policy-changes-arent-taking-effect).
+- `Hidden` shows how many inactive rules the listing leaves out. For more
+ details, see [Show inactive rules](#show-inactive-rules).
+
+If the status shows `Governance: Unresolved`, see
+[`sbx policy ls` shows Governance: Unresolved](../troubleshooting.md#sbx-policy-ls-shows-governance-unresolved).
+
+## Show inactive rules
+
+When an organization policy is enforced for you, local and kit allow rules
+aren't evaluated, so `sbx policy ls` hides them. To list them, for example to
+confirm which of your allow rules the organization policy overrides, pass
+`--include-inactive` with `--wide`:
+
+```console
+$ sbx policy ls --wide --include-inactive
+```
+
+The `STATUS` column shows `active` or `inactive` for each rule. Inactive rules
+have no effect while the organization policy is enforced. Local and kit deny
+rules stay active and aren't hidden, because a deny still applies on top of the
+organization policy. 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).
diff --git a/content/manuals/ai/governance/local/network-rules.md b/content/manuals/ai/governance/local/network-rules.md
new file mode 100644
index 0000000000..632f135ce3
--- /dev/null
+++ b/content/manuals/ai/governance/local/network-rules.md
@@ -0,0 +1,240 @@
+---
+title: Manage local network rules
+linkTitle: Manage network rules
+weight: 20
+description: Allow, deny, and remove local network rules for sandboxes on your machine with sbx policy.
+keywords: docker sandboxes, local policy, network rules, sbx policy allow, sbx policy deny, HTTP rules, UDP
+---
+
+Local network rules allow or block destinations on top of your
+[preset](_index.md#start-from-a-preset). You can add rules for all sandboxes or
+for one sandbox, narrow a rule to HTTP methods and paths, and remove rules you
+no longer need. For the host patterns a rule accepts, see
+[Network and HTTP rule syntax](../reference/network-rules.md#destinations).
+
+## Allow or block a destination
+
+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. Rules apply to
+all sandboxes by default:
+
+```console
+$ sbx policy allow network api.anthropic.com
+$ sbx policy deny network ads.example.com
+```
+
+Specify multiple hosts in one command with a comma-separated list:
+
+```console
+$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org"
+```
+
+## Allow or block a destination for one sandbox
+
+Pass `--sandbox ` to scope a rule to one sandbox:
+
+```console
+$ sbx policy allow network --sandbox my-sandbox api.example.com
+$ sbx policy deny network --sandbox my-sandbox ads.example.com
+```
+
+You can also add deny rules for a sandbox when you create it, with
+`--deny-network` on `sbx create` or `sbx run`:
+
+```console
+$ sbx create --deny-network ads.example.com claude .
+$ sbx run --deny-network ads.example.com claude
+```
+
+Pass the flag multiple times to deny more than one host. Rules added this way
+appear in `sbx policy ls `, like any other rule scoped to the sandbox.
+
+To block a destination that a kit allows, add a deny rule for the sandbox that
+uses the kit. A deny rule takes precedence over the kit's allow rule:
+
+```console
+$ sbx policy deny network --sandbox my-sandbox openrouter.ai
+```
+
+Removing a sandbox also removes the rules scoped to it.
+
+## Allow or block HTTP methods and paths
+
+The rules in the previous sections match a whole host. An HTTP rule matches
+specific HTTP methods and paths on a host instead, so you can allow or block
+specific API requests. For example, you can let an agent read from an API
+without letting it write to it.
+
+Add `--method` to an allow or deny rule to match specific HTTP methods, and
+`--path` to narrow it to part of the host's URL space. Quote the path so your
+shell doesn't expand the wildcard:
+
+```console
+$ sbx policy allow network api.github.com --method GET --path '/repos/org/project/**'
+```
+
+Write the host without a scheme, such as `api.github.com` rather than
+`https://api.github.com`. It follows the same patterns as network rules and can
+include a port, but it must be a hostname. To match an IP address or a CIDR
+range, use a network rule without `--method` or `--path`.
+
+### Choose methods
+
+Pass several methods as a comma-separated list, or `ANY` to match every
+method. Method names are case-insensitive, and `ANY` can't be combined with
+specific methods:
+
+```console
+$ sbx policy allow network api.github.com --method GET,HEAD
+```
+
+The accepted methods are `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`,
+`OPTIONS`, `CONNECT`, and `TRACE`.
+
+### Choose paths
+
+A rule without `--path` matches every path on the host. A rule takes one path,
+and a path needs a method. Repeating `--path` keeps only the last value, and a
+comma is read as part of the path, so add a separate rule for each path:
+
+```console
+$ sbx policy allow network api.github.com --method GET --path '/repos/**'
+$ sbx policy allow network api.github.com --method GET --path '/users/**'
+```
+
+A path must start with `/` and be canonical. For the full path rules, see
+[HTTP method and path](../reference/network-rules.md#http-method-and-path).
+
+### Match query parameters
+
+Add `--query` to require URL query parameters, separately from the path. Repeat
+the flag to require more than one. Like a path, a query restriction needs a
+method, so keep `--method` or use `--method ANY`:
+
+```console
+$ sbx policy allow network api.example.com --method GET --path '/search' \
+ --query 'team=platform' --query 'label=release*'
+```
+
+For value patterns and matching behavior, see
+[Query parameters](../reference/network-rules.md#query-parameters).
+
+### Block part of an allowed host
+
+To restrict part of a host, add a deny rule with the same flags on top of a
+broader allow:
+
+```console
+$ sbx policy allow network api.example.com
+$ sbx policy deny network api.example.com --method POST --path '/admin/**'
+```
+
+## Remove a rule
+
+Remove a rule by resource or by rule ID:
+
+```console
+$ sbx policy rm network --resource ads.example.com
+$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
+```
+
+To remove a rule scoped to a sandbox, pass `--sandbox `:
+
+```console
+$ sbx policy rm network --sandbox my-sandbox --resource api.example.com
+```
+
+To remove an HTTP rule, name the same method, path, and any `--query` flags you
+added it with, or use its rule ID:
+
+```console
+$ sbx policy rm network --resource api.example.com --method GET --path '/search' \
+ --query 'team=platform' --query 'label=release*'
+```
+
+To find a rule's ID, run `sbx policy ls --wide`. For more details, see
+[Inspect policy status and rules](inspect.md).
+
+## Allow outbound UDP
+
+Outbound UDP is experimental and disabled by default. Turn on experimental
+features and UDP egress before you add UDP allow rules. The CLI warns you if
+you save a UDP rule while UDP egress is off:
+
+```console
+$ sbx settings set platform.allowExperimentalFeatures true
+$ sbx settings set feature.udp-egress true
+$ sbx policy allow network --protocol udp api.example.com:443
+```
+
+Local allow rules apply to TCP by default. Use `--protocol udp` for UDP or
+`--protocol tcp,udp` for both. Deny rules apply to both protocols by default,
+and `--protocol` restricts a deny rule to one. UDP rules follow the same
+organization and local precedence as TCP rules.
+
+Some UDP traffic is blocked whatever your rules allow:
+
+- Traffic to a destination that needs an HTTP, SOCKS5, system, or PAC-selected
+ proxy, because those proxies can't carry UDP.
+- Traffic to local-network destinations, including multicast, link-local, and
+ unspecified addresses, `255.255.255.255`, and the broadcast addresses of the
+ host's networks. This block applies before any policy is evaluated, so even a
+ rule that allows all hosts doesn't permit it, and discovery protocols such as
+ mDNS and SSDP don't work from a sandbox. UDP to `host.docker.internal` isn't
+ affected. The network log records these connections under the rule
+ ``.
+
+To list UDP rules or check a destination:
+
+```console
+$ sbx policy ls --protocol udp
+$ sbx policy check network --protocol udp api.example.com:443
+```
+
+## Set or reset the preset
+
+If no preset is set, the CLI prompts you to choose one when you run a sandbox
+in an interactive terminal. For more details, see
+[Start from a preset](_index.md#start-from-a-preset). To set the preset without
+the prompt, or to start over with a new one, use `sbx policy init` or `sbx
+policy reset`.
+
+### Set the preset without the prompt
+
+In non-interactive environments such as CI pipelines or headless servers, the
+CLI can't prompt you, so commands such as `sbx run` return an error until a
+preset is set. Use `sbx policy init` to set the preset before you run a
+sandbox:
+
+```console
+$ sbx policy init balanced
+```
+
+Available values are `allow-all` (Open), `balanced` (Balanced), and `deny-all`
+(Locked Down). `sbx policy init` only works before a preset is set. To change
+the preset after that, reset local policy.
+
+### Reset local policy
+
+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, restarts the daemon, and prompts you 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
+```
+
+> [!WARNING]
+> `sbx policy reset` deletes all locally configured policy rules, including any
+> destinations you approved. Those destinations are requested again the next
+> time a sandbox reaches them. To pick up organization policy changes without
+> deleting local rules, use `sbx policy refresh` instead. For more details, see
+> [Organization policy changes aren't taking effect](../troubleshooting.md#organization-policy-changes-arent-taking-effect).
diff --git a/content/manuals/ai/governance/local/test-monitor.md b/content/manuals/ai/governance/local/test-monitor.md
new file mode 100644
index 0000000000..afed9addb6
--- /dev/null
+++ b/content/manuals/ai/governance/local/test-monitor.md
@@ -0,0 +1,109 @@
+---
+title: Test and monitor network policy
+linkTitle: Test and monitor
+weight: 50
+description: Check whether policy allows a destination, and view the network requests your sandboxes make, with sbx policy check and sbx policy log.
+keywords: docker sandboxes, test network policy, sbx policy check, sbx policy log, network traffic, local policy
+---
+
+Use `sbx policy check` to find out whether policy allows a destination before a
+sandbox tries to reach it, and `sbx policy log` to see the requests your
+sandboxes made and which rules matched. Both work the same way whether the
+rules come from your local policy, a kit, or your organization.
+
+## Check whether a destination is allowed
+
+Run `sbx policy check network` with the destination you want to test:
+
+```console
+$ sbx policy check network api.anthropic.com
+$ sbx policy check network blocked.example.com
+```
+
+The output reports `Allowed` or `Denied`, along with governance and context
+details. A denied check returns exit status 1, so you can use the command in
+scripts.
+
+The destination can be a hostname, a `host:port` pair, an IP address, or a URL.
+Hostnames and IP addresses without a port are checked on port 443. A URL
+supplies only its host and port, so the check ignores its path.
+
+To check a destination for one sandbox, including the rules scoped to it, pass
+`--sandbox`:
+
+```console
+$ sbx policy check network --sandbox my-sandbox api.example.com
+```
+
+A check never creates an approval request. A destination that a sandbox would
+ask you to approve shows as `Denied`, with a `Reason` line of
+`no matching allow rule (default deny)`, or `approval required by policy` when
+an organization policy is enforced for you.
+
+A check reports the decision for the host, not for an HTTP method or path. To
+test an HTTP rule, send a request from inside the sandbox. For more details,
+see
+[Allow or block HTTP methods and paths](network-rules.md#allow-or-block-http-methods-and-paths).
+
+## View network activity
+
+Run `sbx policy log` to see which hosts your sandboxes contacted and which
+rules matched:
+
+```console
+$ sbx policy log
+BLOCKED REQUESTS
+SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT
+my-sandbox network blocked.example.com transparent domain-blocked default-deny 10:15:25 29-Jan 1
+
+ALLOWED REQUESTS
+SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT
+my-sandbox network api.anthropic.com forward domain-allowed 10:15:23 29-Jan 42
+my-sandbox network registry.npmjs.org forward-bypass domain-allowed 10:15:20 29-Jan 18
+my-sandbox network app.example.com browser-open 10:15:10 29-Jan 1
+```
+
+The `RULE` column identifies the policy rule that matched the request. The
+`REASON` column includes extra context when the daemon records one. The `PROXY`
+column shows how the request left the sandbox:
+
+| Value | Description |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `forward` | Routed through the forward proxy. Supports credential injection. |
+| `forward-bypass` | Routed through the forward proxy without credential injection. |
+| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. |
+| `network` | Non-HTTP traffic. TCP and experimental UDP egress follow network policy. ICMP is blocked. |
+| `browser-open` | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL. |
+
+For how the forward and transparent proxies handle sandbox traffic, see
+[Networking](../../sandboxes/architecture.md#networking).
+
+The log records network requests by host, without their HTTP methods and
+paths. Filesystem mount decisions aren't in the log.
+
+## Filter the log
+
+To see only one sandbox's requests, pass its name:
+
+```console
+$ sbx policy log my-sandbox
+```
+
+To show only the most recent entries, pass `--limit`:
+
+```console
+$ sbx policy log --limit 20
+```
+
+## Get the log as JSON or YAML
+
+Pass `--json` or `--format yaml` for output that scripts can read:
+
+```console
+$ sbx policy log --json
+```
+
+The document has the form `{updated_at, allowed: [...], blocked: [...]}`. Each
+entry includes `sandbox_id`, `host`, `proxy_type`, `rule`, `reason`, `count`,
+`first_seen`, and `last_seen`. The `--limit` flag applies to structured output
+too.
diff --git a/content/manuals/ai/governance/local/try-it-out.md b/content/manuals/ai/governance/local/try-it-out.md
new file mode 100644
index 0000000000..4f5b99c26f
--- /dev/null
+++ b/content/manuals/ai/governance/local/try-it-out.md
@@ -0,0 +1,137 @@
+---
+title: Try out local policy
+linkTitle: Try it out
+weight: 10
+description: Follow an example that allows and blocks network destinations and HTTP methods for one sandbox with local policy.
+keywords: docker sandboxes, local policy, try it out, tutorial, sbx policy check, sbx policy ls, sbx policy allow, sbx policy deny, sbx policy log, http rules
+---
+
+In this example, you create a sandbox, allow and block destinations for it,
+block an HTTP method, and review what happened. It uses the `shell` agent, so
+you don't need to sign in to an agent.
+
+## Before you begin
+
+[Install Docker Sandboxes](/manuals/ai/sandboxes/install.md).
+
+If your organization enforces a policy for you, some steps behave differently.
+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).
+
+## Step 1: Create a sandbox
+
+Create a sandbox named `policy-demo` that uses the current directory as its
+workspace:
+
+```console
+$ sbx create --name policy-demo shell .
+```
+
+If you haven't chosen a network [preset](_index.md#start-from-a-preset) yet,
+`sbx` asks you to choose one. This example works with any preset.
+
+## Step 2: Allow a destination for this sandbox
+
+Add an allow rule for `example.com` that applies only to `policy-demo`:
+
+```console
+$ sbx policy allow network --sandbox policy-demo example.com
+```
+
+The rule doesn't affect your other sandboxes. List the rules you've added that
+apply to the sandbox:
+
+```console
+$ sbx policy ls policy-demo --wide --created-via added
+```
+
+The listing includes the `example.com` rule, with `sandbox:policy-demo` in the
+`APPLIES TO` column. Rules from your preset aren't listed, because
+`--created-via added` shows only rules you added. For more details, see
+[Inspect policy status and rules](inspect.md).
+
+Reach the destination from inside the sandbox:
+
+```console
+$ sbx exec policy-demo -- curl -sI https://example.com
+```
+
+For more details, see [Manage local network rules](network-rules.md).
+
+## Step 3: Block a destination for this sandbox
+
+Add a deny rule for `registry.npmjs.org` that applies only to `policy-demo`:
+
+```console
+$ sbx policy deny network --sandbox policy-demo registry.npmjs.org
+```
+
+Check the destination:
+
+```console
+$ sbx policy check network --sandbox policy-demo registry.npmjs.org
+```
+
+The check reports `Denied`. A deny rule takes precedence over allow rules,
+including the ones your preset and kits add.
+
+## Step 4: Block an HTTP method for this sandbox
+
+An HTTP rule matches a method and path on a host, rather than the whole host.
+Use HTTP rules to allow or block specific API requests, such as letting an
+agent read from an API without letting it write to it. Block `POST` requests to
+`example.com` for `policy-demo`:
+
+```console
+$ sbx policy deny network --sandbox policy-demo example.com --method POST
+```
+
+Send a `POST` request from inside the sandbox:
+
+```console
+$ sbx exec policy-demo -- curl -s -X POST https://example.com
+```
+
+The response starts with `Blocked by local rule`. Other methods are still
+allowed. Send a `GET` request to the same destination:
+
+```console
+$ sbx exec policy-demo -- curl -s https://example.com
+```
+
+The response is the HTML of the `example.com` page.
+
+`sbx policy check network` reports the decision for the host, not for a method
+or path, so use a request like this one to test an HTTP rule. For more details,
+see
+[Allow or block HTTP methods and paths](network-rules.md#allow-or-block-http-methods-and-paths).
+
+## Step 5: Review network activity
+
+See the sandbox's network activity:
+
+```console
+$ sbx policy log policy-demo
+```
+
+For more details, see [Test and monitor network policy](test-monitor.md).
+
+## Step 6: Clean up
+
+Remove the sandbox:
+
+```console
+$ sbx rm policy-demo
+```
+
+Removing a sandbox also removes the rules scoped to it, so you don't need to
+remove the rules you added in this example.
+
+## Next steps
+
+- Learn how presets, rules for one sandbox, and kit rules combine in
+ [Local policy](_index.md).
+- Approve destinations that no rule allows, under the Balanced and Locked Down
+ presets, in [Respond to approval requests](approvals.md).
+- Reference the [Network and HTTP rule
+ syntax](../reference/network-rules.md#http-method-and-path).
diff --git a/content/manuals/ai/governance/organization/_index.md b/content/manuals/ai/governance/organization/_index.md
new file mode 100644
index 0000000000..feaa4c8696
--- /dev/null
+++ b/content/manuals/ai/governance/organization/_index.md
@@ -0,0 +1,70 @@
+---
+title: Organization governance
+weight: 20
+description: Centrally manage sandbox network, filesystem, and MCP policies and review audit logs for your organization.
+keywords: docker sandboxes, governance, organization policy, AI governance, Docker Home, network access, filesystem access, mcp policy, sign-in enforcement, audit logs
+aliases:
+ - /ai/sandboxes/security/governance/
+ - /ai/sandboxes/governance/org/
+ - /ai/sandboxes/governance/access-controls/organization/
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Organization governance lets you, the administrator, control what sandboxes can
+do across your organization. You set the rules once in Docker Home, and they
+apply to the sandboxes on every governed developer's machine, instead of each
+developer deciding with local policy. Organization policy is default deny, so
+those sandboxes can reach, mount, and use only what your policies allow.
+
+## How organization governance works
+
+Organization governance has three parts. Licenses and sign-in enforcement
+decide who is governed, organization policies control what their sandboxes can
+do, and audit logs record the decisions those policies make.
+
+### Licenses and sign-in enforcement
+
+Organization governance applies to the members of your organization who hold
+an AI Governance license. You assign licenses in Docker Home, either to the
+members you choose or automatically when members sign in to Docker Sandboxes.
+For more details, see
+[Manage licenses](/manuals/accounts/organization/manage/manage-licenses.md).
+You can apply each policy to the whole organization or only to selected teams.
+
+A developer could avoid your rules by signing in to Docker Sandboxes with a
+personal account. [Sign-in enforcement](sign-in-enforcement.md) closes that
+gap by allowing only members of your organization to use sandboxes on your
+managed machines.
+
+### Organization policies
+
+Organization policies control which destinations sandboxes can reach, which
+host paths developers can mount, and which MCP servers developers can register
+and use. You create them in Docker Home, or programmatically through the
+[AI Governance API](/reference/api/ai-governance/). For more details, see
+[Organization policies](policies/_index.md).
+
+### Audit logs
+
+[Audit logs](audit/_index.md) record governance activity for your
+organization, such as the policy decision made for each sandbox request. You
+can view and export them in Docker Home, or forward them to your SIEM.
+
+## Developer experience
+
+Developers keep using the same `sbx` commands. When an organization policy is
+enforced for them, `sbx policy ls` shows `Governance: Managed by ` in its
+status line, and only your allow rules grant access, so local and kit allow
+rules on their machines stop applying. For more details, see
+[How organization policy relates to local and kit rules](policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules).
+A request that your policy blocks returns `Blocked by org policy`, followed by
+your [support message](policies/create-manage.md#configure-a-support-message)
+if you configured one.
+
+## Get started
+
+To set up organization governance step by step, see
+[Get started with organization governance](get-started.md). To get an AI
+Governance plan,
+[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales).
diff --git a/content/manuals/ai/governance/organization/audit/_index.md b/content/manuals/ai/governance/organization/audit/_index.md
new file mode 100644
index 0000000000..e90f2ff399
--- /dev/null
+++ b/content/manuals/ai/governance/organization/audit/_index.md
@@ -0,0 +1,101 @@
+---
+title: Audit logs
+linkTitle: Audit logs
+weight: 40
+description: Capture, view, export, and collect structured audit records for Docker AI Governance policy decisions.
+keywords: docker sandboxes, audit log, audit logging, AI Governance, policy decision, SIEM, compliance, jsonl
+aliases:
+ - /ai/sandboxes/governance/audit/
+ - /ai/sandboxes/governance/audit/local/
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Your organization's policies decide what sandboxes can do. Audit logs show you
+what happened: each time a policy decides a request from a governed
+developer's sandbox, a record captures who made the request, what it was, and
+what the policy decided. You can review the records in Docker Home,
+export them, forward them to your SIEM, or collect them from each machine.
+
+This page explains what audit logs record, where records go, and what you can
+do with them.
+
+> [!NOTE]
+> Audit logs cover local sandboxes, the sandboxes that run on developers'
+> machines. Cloud delivery stores their audit records in the cloud. It
+> doesn't add cloud sandbox coverage. For cloud network decisions, see
+> [Cloud policy logs](../../../sandboxes/cloud/network-policy.md#inspect-network-policy).
+
+## What audit logs record
+
+Audit logs cover two kinds of events from Docker Sandboxes: the policy decision
+made for each request, and sandbox session lifecycle events.
+
+Records contain metadata only, such as who made a request, what it targeted,
+and what the policy decided. They never contain prompt content, agent output,
+or parameter values. For every field a record can contain, see the
+[Audit record reference](../../reference/audit-records.md).
+
+Records come only from developers your organization governs: signed-in users
+who have an AI Governance license and for whom an organization policy is
+enforced. Other users don't generate audit records, so they don't appear in
+audit events or SIEM forwarding output.
+
+## Delivery modes
+
+Docker supports two delivery modes for audit records:
+
+- **Local disk**: the sandbox daemon writes JSON Lines (`.jsonl`)
+ files on each host. Use this mode for host-local retention, air-gapped
+ collection, or collection through your own log shipper.
+- **Docker Cloud**: Docker stores audit records in Docker Cloud. Cloud
+ delivery powers the hosted audit log view, CSV export, SIEM streaming, and
+ the Audit Logs API.
+
+To choose which delivery modes your organization uses, see
+[Configure audit delivery](configure.md).
+
+### Where records are stored
+
+With local delivery, the sandbox daemon on each machine writes audit records to
+its audit directory. Local files stay on the host that produced them, whether
+cloud delivery is on or off.
+
+The directory follows each operating system's convention for application logs:
+
+| OS | Default path |
+| ------- | ----------------------------------------------------------------- |
+| macOS | `~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/` |
+| Linux | `${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/` |
+| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\logs\auditkit\` |
+
+Each file is named `audit---.jsonl`. The
+daemon writes records to a temporary `.tmp` file first, then renames it to
+`.jsonl` when it reaches a rotation threshold or shuts down cleanly. By
+default, the threshold is 5 minutes, 1000 events, or 50 MiB, whichever comes
+first. Collect only `.jsonl` files, because `.tmp` files are still being
+written.
+
+Docker Sandboxes never deletes `.jsonl` files, so retention and cleanup are up
+to your log shipper or your own housekeeping.
+
+## What you can do with records
+
+How you use audit records depends on where they go:
+
+- With cloud delivery, [view and export events](view-export.md) in
+ Docker Home, [forward them to your SIEM](siem.md), and
+ [retrieve them with the Audit Logs API](api.md). The hosted view, CSV export,
+ SIEM forwarding, and the API all require cloud delivery. Local
+ delivery alone doesn't power them.
+- With local delivery, collect the `.jsonl` files from each machine with your
+ own log shipper. For more details, see
+ [Collect local audit files with a log shipper](siem.md#collect-local-audit-files-with-a-log-shipper).
+
+## Data handling
+
+When cloud delivery is on, Docker stores audit records in Docker
+Cloud for 90 days. For legal and privacy terms that govern Docker services, see
+Docker's
+[Terms of Service](https://www.docker.com/legal/docker-terms-service/) and
+[Privacy Policy](https://www.docker.com/legal/privacy/).
diff --git a/content/manuals/ai/sandboxes/governance/audit/api.md b/content/manuals/ai/governance/organization/audit/api.md
similarity index 95%
rename from content/manuals/ai/sandboxes/governance/audit/api.md
rename to content/manuals/ai/governance/organization/audit/api.md
index 8e83677969..f4d404b1a2 100644
--- a/content/manuals/ai/sandboxes/governance/audit/api.md
+++ b/content/manuals/ai/governance/organization/audit/api.md
@@ -1,12 +1,14 @@
---
title: Retrieve audit events with the API
-linkTitle: Audit Logs API
+linkTitle: Retrieve with the API
weight: 45
description: Retrieve and filter Docker AI Governance audit events with the Audit Logs API.
keywords: docker sandboxes, AI Governance, audit logs API, audit events, organization access token, OAT
+aliases:
+ - /ai/sandboxes/governance/audit/api/
---
-{{< summary-bar feature_name="AI Governance Audit Logs" >}}
+{{< summary-bar feature_name="AI Governance" >}}
The Audit Logs API retrieves cloud-delivered Docker AI Governance events for
automation, investigation, and reporting. The API returns the same event data
@@ -17,8 +19,8 @@ shown in the hosted audit log view.
Before you use the API, you need:
- A Docker [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md)
-- Docker Cloud delivery turned on in [audit delivery settings](configure.md)
-- An Organization Access Token (OAT) with the **View audit logs** permission
+- Cloud delivery turned on in [audit delivery settings](configure.md)
+- An organization access token (OAT) with the **View audit logs** permission
Personal Access Tokens and Docker account session tokens aren't supported.
@@ -85,7 +87,7 @@ array of events and an opaque cursor for the next page:
}
```
-See the [audit record reference](record-reference.md) for category, decision,
+See the [audit record reference](../../reference/audit-records.md) for category, decision,
action, and payload fields.
## Filter events
diff --git a/content/manuals/ai/governance/organization/audit/configure.md b/content/manuals/ai/governance/organization/audit/configure.md
new file mode 100644
index 0000000000..fcafe0a10d
--- /dev/null
+++ b/content/manuals/ai/governance/organization/audit/configure.md
@@ -0,0 +1,61 @@
+---
+title: Configure audit delivery
+linkTitle: Configure delivery
+weight: 10
+description: Configure local and cloud delivery for Docker AI Governance audit logs, and review who changed the delivery settings.
+keywords: docker sandboxes, audit delivery, AI Governance, audit logs, retention, cloud delivery, AI Platform
+aliases:
+ - /ai/sandboxes/governance/audit/configure/
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Configure where Docker delivers your organization's audit records, and review
+who changed those settings. You can deliver records to local disk on each host,
+to Docker Cloud, or to both. For how the two delivery modes differ, see
+[Delivery modes](_index.md#delivery-modes).
+
+## Before you begin
+
+Your organization needs:
+
+- A Docker [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md)
+- Organization owner access, or a
+ [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md)
+ with AI Governance audit permissions
+
+## Configure delivery
+
+To configure audit delivery:
+
+1. Sign in to [Docker Home](https://app.docker.com) and select your
+ organization.
+1. Go to **AI Platform** > **Audit logs**.
+1. Open **Audit delivery**.
+1. Choose one or both delivery modes:
+ - **Local disk** writes audit records to JSON Lines files on each host.
+ - **Docker Cloud** stores audit records in Docker Cloud for hosted search,
+ CSV export, and SIEM forwarding.
+1. Save your changes.
+
+Cloud delivery is on by default, except for organizations that used local
+audit logging before hosted audit logs were available. Those organizations start with cloud delivery off until an owner
+turns it on. To keep records local to your hosts, turn off **Docker Cloud** and
+keep **Local disk** on.
+
+Docker Cloud keeps audit records searchable in the hosted audit log view for 90
+days, and in archive storage for 90 days.
+
+## Review delivery change history
+
+Docker keeps a record of every change made to your organization's audit delivery
+settings. Each entry shows who made the change, when it happened, and the before
+and after values. Use this history to audit configuration changes and verify
+when delivery modes were modified.
+
+To review the history:
+
+1. Sign in to [Docker Home](https://app.docker.com) and select your
+ organization.
+1. Go to **AI Platform** > **Audit logs**.
+1. Open **History**.
diff --git a/content/manuals/ai/governance/organization/audit/siem.md b/content/manuals/ai/governance/organization/audit/siem.md
new file mode 100644
index 0000000000..5f263eb27e
--- /dev/null
+++ b/content/manuals/ai/governance/organization/audit/siem.md
@@ -0,0 +1,85 @@
+---
+title: Forward audit events to a SIEM
+linkTitle: Forward to a SIEM
+weight: 30
+description: Forward Docker AI Governance audit events to Splunk, Dynatrace, Datadog, Sumo Logic, or CrowdStrike Falcon Next-Gen SIEM.
+keywords: docker sandboxes, SIEM, audit logs, Splunk, Dynatrace, Datadog, Sumo Logic, CrowdStrike, Falcon Next-Gen SIEM, AI Governance, forwarding, NDJSON
+aliases:
+ - /ai/sandboxes/governance/audit/siem/
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Send your Docker AI Governance audit events to your security information and
+event management (SIEM) system to centralize Docker governance data alongside
+other security signals. How you do it depends on where your audit records are
+delivered:
+
+- With cloud delivery, Docker forwards events directly to a supported
+ SIEM destination.
+- With local delivery, your own log shipper collects the audit files from
+ each machine.
+
+## Forward events from Docker Cloud
+
+Docker forwards audit events from Docker Cloud to the SIEM destinations you
+add in Docker Home.
+
+### Supported destinations
+
+| Destination | Connects through | What you need |
+| ---------------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
+| [Splunk Cloud](https://docs.splunk.com/) | HTTP Event Collector (HEC) | HEC ingest URL and an HEC token. Optionally, a Splunk index name. |
+| [Dynatrace](https://docs.dynatrace.com/) | Log Ingest API | Log Ingest API URL and an API token with the `logs.ingest` scope. |
+| [Datadog](https://docs.datadoghq.com/) | HTTP log intake API | Logs intake URL for your Datadog site and an API key. |
+| [Sumo Logic](https://www.sumologic.com/help/) | HTTP Source | HTTP Source URL and an auth token from an HTTP Logs & Metrics source. |
+| [CrowdStrike Falcon Next-Gen SIEM](https://library.humio.com/logscale-api/log-shippers-hec-raw.html) | HEC / HTTP Event Connector | API URL and an API key from the connector. Append `/raw` to the API URL when you add it. |
+
+### Before you begin
+
+You need organization owner access, or a
+[custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md)
+with AI Governance audit permissions.
+
+SIEM forwarding requires cloud delivery to be enabled for your
+organization. If you haven't already, enable it under **AI Platform** > **Audit
+logs** > **Audit delivery** before configuring a SIEM destination. For more
+details, see [Configure audit delivery](configure.md).
+
+Gather the endpoint URL and credential your destination needs, listed in
+Supported destinations. Some destinations require you
+to create a connector or source first.
+
+### Add a SIEM destination
+
+1. Sign in to [Docker Home](https://app.docker.com) and select your
+ organization.
+1. Go to **AI Platform** > **Audit logs**.
+1. Open **Export & Connectors**.
+1. Select **Add destination**.
+1. Select your destination and complete the form.
+1. Select **Save**.
+
+Docker verifies the endpoint is reachable with the supplied credential before
+saving. If verification fails, check that the URL and credential are correct
+and that the endpoint is accessible from the internet.
+
+### Edit or delete a destination
+
+From the **SIEM forwarding** list, select the menu next to a destination to
+edit or delete it. The edit form lets you update credentials and toggle
+forwarding on or off for that destination. Deleting a destination permanently
+removes the endpoint and its stored credential and can't be undone.
+
+## Collect local audit files with a log shipper
+
+With local delivery, each machine writes its audit records to `.jsonl`
+files in its own audit directory. For the directory on each operating system
+and how files are named, see
+[Where records are stored](_index.md#where-records-are-stored).
+
+Point your log shipper at the audit directory and configure it to collect
+`.jsonl` files only. Tools such as the Splunk Universal Forwarder,
+Filebeat, and CrowdStrike Falcon LogScale read the directory and forward each
+line as an event. Because in-progress records live in `.tmp` files until they
+are finalized, collectors never see partial records.
diff --git a/content/manuals/ai/governance/organization/audit/view-export.md b/content/manuals/ai/governance/organization/audit/view-export.md
new file mode 100644
index 0000000000..1e56795e9c
--- /dev/null
+++ b/content/manuals/ai/governance/organization/audit/view-export.md
@@ -0,0 +1,91 @@
+---
+title: View and export audit events
+linkTitle: View and export
+weight: 20
+description: Search, filter, and export Docker AI Governance audit events from the hosted audit log view.
+keywords: docker sandboxes, audit events, audit logs, AI Governance, CSV export
+aliases:
+ - /ai/sandboxes/governance/audit/view-export/
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Cloud delivery stores AI Governance audit records in Docker Cloud and makes
+them available in the hosted audit log view. Use it to investigate
+policy decisions, such as why a developer's request was blocked or what
+sandboxes reached over the past week. Open the view to see recent events,
+narrow it to the ones you care about, then export them to CSV if you need an
+offline copy.
+
+## Before you begin
+
+- [Cloud delivery](configure.md) must be turned on for your
+ organization. The hosted view shows only records delivered to Docker Cloud,
+ not records written to local disk.
+- You need organization owner access, or a
+ [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md)
+ with AI Governance audit permissions.
+
+## View audit events
+
+1. Sign in to [Docker Home](https://app.docker.com) and select your
+ organization.
+1. Go to **AI Platform** > **Audit logs**.
+1. Open **Audit events**.
+
+The **Audit events** view includes summary tiles for **Events**, **Allowed**,
+**Denied**, and **Consent required**. **Consent required** counts the events
+with an Approval required decision. The event table includes:
+
+| Column | Description |
+| --------- | ------------------------------------------------------------------- |
+| Time | When Docker recorded the event. |
+| Event | The event type or policy action. |
+| Principal | The Docker user associated with the event. |
+| Resource | The target resource, such as a domain, file path, or tool. |
+| Decision | The governance decision, such as Allow, Deny, or Approval required. |
+| Agent | The AI agent associated with the event, when Docker knows it. |
+
+For every field in a record and what its values mean, see
+[Audit record reference](../../reference/audit-records.md).
+
+## Filter and search events
+
+The event table can hold a large number of events, so narrow it to the ones
+you're investigating. Use the filters above the table:
+
+- **Date range**: Today, Last 7 days, Last 14 days, Last 30 days, or a custom
+ range. The table shows the last 7 days by default.
+- **Decision**: Allow, Deny, Approval required, or Approval unavailable.
+- **Event type**: the kind of action, such as a network or filesystem
+ evaluation. For the full list, see
+ [Action types](../../reference/audit-records.md#action-types).
+- **Agent**: the AI agent associated with the event.
+- **Principal**: a Docker username.
+- **Session ID**: an audit session ID. This filter shows the whole session,
+ whatever the date range.
+
+To search across events, principals, resources, and decisions, enter at least
+three characters in the search box, then press Enter.
+
+For example, set **Decision** to Deny and **Principal** to a developer's
+username to see what their sandboxes were blocked from.
+
+The table shows 25 events per page by default. You can show 100 per page
+instead.
+
+## Export events to CSV
+
+When you need an offline copy of the events you found, export them. The export
+uses your current filters and search terms:
+
+1. Open **Audit events**.
+1. Apply the filters and search terms for the events you want to export.
+1. Select **Export**.
+1. Download the generated CSV file from the link Docker provides.
+
+CSV exports include up to 1,000,000 rows. An export stays available to download
+for 24 hours after Docker generates it.
+
+To monitor audit events continuously instead of searching them by hand,
+[forward them to your SIEM](siem.md).
diff --git a/content/manuals/ai/governance/organization/get-started.md b/content/manuals/ai/governance/organization/get-started.md
new file mode 100644
index 0000000000..3e1415cf70
--- /dev/null
+++ b/content/manuals/ai/governance/organization/get-started.md
@@ -0,0 +1,152 @@
+---
+title: Get started with organization governance
+linkTitle: Get started
+weight: 10
+description: Set up organization governance for Docker Sandboxes, from planning policies and configuring audit logs to assigning licenses, enforcing sign-in, deploying Docker Sandboxes, and verification.
+keywords: docker sandboxes, AI Governance, organization governance, get started, organization policy, sign-in enforcement, audit logs, rollout
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+This page walks you through setting up organization governance, from planning
+your first policies to confirming they work on a developer machine. Each step
+explains what to do and what to decide, and links to the page with the full
+instructions.
+
+## Before you begin
+
+You need:
+
+- A Docker
+ [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md)
+ for your organization.
+- Your developers added as
+ [members of your organization](/manuals/accounts/organization/manage/members.md).
+ To scope policies to groups of developers, such as a pilot team, also
+ [create teams](/manuals/accounts/organization/manage/manage-a-team.md) for
+ them.
+- The organization
+ [owner](/manuals/security/roles-and-permissions/core-roles.md) role, or a
+ [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md)
+ with the **Governance** permissions.
+- Access to the endpoint management tooling for your developers' machines, such
+ as an MDM solution or Group Policy, to enforce sign-in.
+
+## Step 1: Plan what to allow
+
+Organization policy is default deny. Once an organization policy is enforced
+for a developer, their sandboxes can reach only the network destinations your
+policies allow, mount only the host paths your policies allow, and use MCP
+servers only as your policies permit. For more details, see
+[Organization policies](policies/_index.md).
+
+Before you govern anyone, work out what their sandboxes need:
+
+- Network destinations, such as AI provider APIs, package registries, and code
+ hosts.
+- Host paths that sandboxes mount as workspaces. By default, `sbx run` mounts
+ the directory it's run from, so allow the directories where developers keep
+ their projects. A sandbox can't start if its workspace isn't allowed.
+- MCP servers that developers add with `sbx mcp add`. A server that an agent
+ connects to directly, without `sbx`, is a network destination, so plan for it
+ with your network rules instead.
+
+Before you assign licenses, you can run `sbx policy log` on a developer's
+machine to see the network requests its sandboxes make. Once developers are
+governed, your audit logs record their network requests, mounts, and MCP
+activity in more detail. If you're not sure what sandboxes need, start the
+pilot team with the rules you're confident about, then review your audit logs
+for requests your policies deny and add allow rules where developers need them.
+Audit records are available after you configure audit delivery and assign
+licenses in steps 3 and 4.
+
+Then decide how to scope your policies. Use org-wide policies for guardrails
+that must apply everywhere, such as deny rules that block a destination even
+when a team-scoped policy allows it, and team-scoped policies for access that
+only some teams need. For an example of how the two combine, see
+[How rules decide a request](policies/_index.md#how-rules-decide-a-request).
+Plan to start with one pilot team before you roll out to everyone.
+
+## Step 2: Create your policies
+
+In [Docker Home](https://app.docker.com), expand **AI Platform** and create
+your policies under **Network access**, **Filesystem access**, and **MCP
+access**. Create at least a network policy and a filesystem policy before you
+assign any licenses, so governed developers can keep working. Scope your first
+policies to the pilot team.
+
+For the steps, see
+[Create and manage organization policies](policies/create-manage.md).
+
+Consider also
+[configuring a support message](policies/create-manage.md#configure-a-support-message).
+Developers see it when your policy blocks a request, so you can tell them how
+to ask for access.
+
+## Step 3: Configure audit delivery
+
+Audit logs record the policy decisions made for your developers' sandboxes.
+Configure delivery before you assign licenses, so records are collected from
+the first governed request. In Docker Home, go to **AI Platform** >
+**Audit logs** to choose where records are delivered. For more details, see
+[Configure audit delivery](audit/configure.md).
+
+## Step 4: Assign licenses
+
+Organization policies apply only to members who hold an AI Governance license.
+Assign licenses to the members of your pilot team first. For more details, see
+[Manage licenses](/manuals/accounts/organization/manage/manage-licenses.md).
+
+## Step 5: Enforce sign-in
+
+Without sign-in enforcement, a developer can sign in to Docker Sandboxes with a
+personal account and avoid your policies. Deploy an enforcement configuration
+to your developers' machines with your endpoint management tooling, listing
+the organizations that developers must belong to. For more details, see
+[Enforce sign-in](sign-in-enforcement.md).
+
+## Step 6: Deploy Docker Sandboxes
+
+If your developers don't have Docker Sandboxes yet, deploy it after you assign
+licenses and enforce sign-in, so developers are governed from their first
+sign-in. For installation options, see
+[Install Docker Sandboxes](/manuals/ai/sandboxes/install.md).
+
+## Step 7: Verify on a developer machine
+
+On the machine of a developer in your pilot team, pick up the latest
+organization policy right away instead of waiting for the next sync:
+
+```console
+$ sbx policy refresh
+```
+
+Confirm that organization policy is enforced. The status line should show your
+organization:
+
+```console
+$ sbx policy ls
+```
+
+Check a destination your policy allows and one it doesn't:
+
+```console
+$ sbx policy check network api.anthropic.com
+$ sbx policy check network blocked.example.com
+```
+
+The first check should report `Allowed` and the second `Denied`. Then run a
+sandbox and use `sbx policy log` to see which requests it made and which
+rules matched. For more details, see
+[Inspect policy status and rules](../local/inspect.md) and
+[Test and monitor network policy](../local/test-monitor.md).
+
+## Step 8: Roll out to more teams
+
+When the pilot team works as expected, assign licenses to more members, deploy
+Docker Sandboxes to their machines, and widen the scope of your policies, or
+add team-scoped policies for teams that need different access. As more
+developers are governed, keep reviewing your audit logs for requests your
+policies block, and add allow rules where developers need them. Each change you make reaches developer machines within 5 minutes.
+For more details, see
+[When policy changes reach developers](policies/_index.md#when-policy-changes-reach-developers).
diff --git a/content/manuals/ai/governance/organization/policies/_index.md b/content/manuals/ai/governance/organization/policies/_index.md
new file mode 100644
index 0000000000..0ede956a4e
--- /dev/null
+++ b/content/manuals/ai/governance/organization/policies/_index.md
@@ -0,0 +1,141 @@
+---
+title: Organization policies
+linkTitle: Policies
+weight: 30
+description: How organization policy scope, rule evaluation, and precedence work for Docker Sandboxes.
+keywords: docker sandboxes, organization policy, policy scope, rule evaluation, precedence, governance
+aliases:
+ - /ai/sandboxes/governance/concepts/
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Organization policies control what sandboxes can access for organization
+members. When a developer's sandbox makes a request, three questions decide
+the outcome: which of your policies apply to that developer, what their rules
+say about the request, and how your policy relates to the local and kit
+rules on the developer's machine. This page answers each in turn, then explains
+when your changes reach developers. To create a policy, see
+[Create and manage organization policies](create-manage.md).
+
+## What a policy contains
+
+An organization policy is a named collection of rules. Each rule has a name,
+the actions it controls, the resources it matches, and a decision of `allow` or
+`deny`. Each policy covers one kind of access:
+
+- [Organization network access policies](network.md) control the destinations
+ sandboxes can reach.
+- [Organization filesystem access policies](filesystem.md) control the host
+ paths developers can mount into sandboxes.
+- [Organization MCP access policies](mcp.md) control the MCP servers developers
+ can register and what agents can do with them. They use Cedar statements in
+ the `MCP` namespace instead of rules.
+
+## Policy scope
+
+Organization policies apply only to members who hold an AI Governance license.
+Each policy applies to those members either across the whole organization or
+only on specific teams:
+
+- Org-wide: with no teams assigned, the policy applies to every licensed member
+ of the organization.
+- Team-scoped: with one or more teams assigned, the policy applies only to
+ licensed members of those teams.
+
+Teams are the same [teams](/manuals/accounts/organization/manage/manage-a-team.md)
+you manage for your organization. Docker matches a policy's teams against each
+member's team membership. Because an organization can mix org-wide and
+team-scoped policies, a single member is often subject to several at once. The
+policies that apply to a given member are their effective policies: every
+org-wide policy, plus every team-scoped policy for a team they belong to.
+
+Use org-wide policies for guardrails that must apply everywhere, and
+team-scoped policies for access that only some teams need. The next section
+explains why org-wide deny rules work well as guardrails.
+
+## How rules decide a request
+
+When an organization policy is enforced for you, the rules from all of your
+effective policies are combined and evaluated together against each request,
+following two principles:
+
+- Deny wins: if any rule matches with `decision: deny`, the request is denied,
+ regardless of any matching allow rules.
+- Default deny: anything an allow rule doesn't match is blocked. Outbound
+ network traffic is blocked unless a network rule allows the destination, a
+ host path can't be mounted unless a filesystem mount rule allows it, and MCP
+ activity is blocked unless an MCP `permit` allows it.
+
+Because every effective policy feeds the same evaluation, allows are additive (a
+request is allowed if any effective policy allows it) and denies are absolute (a
+request is blocked if any effective policy denies it). A deny rule in an
+org-wide policy therefore applies to everyone and can't be overridden by a
+team-scoped policy, which makes org-wide deny rules useful as guardrails.
+
+For example, an org-wide policy allows `git.example.com` and denies
+`paste.example.com`, and a team-scoped policy for the Data team allows
+`packages.example.com` and `paste.example.com`:
+
+| Destination | Data team member | Everyone else |
+| ---------------------- | --------------------------------------- | ------------------------------ |
+| `git.example.com` | Allowed by the org-wide policy | Allowed by the org-wide policy |
+| `packages.example.com` | Allowed by the team-scoped policy | Blocked by default deny |
+| `paste.example.com` | Blocked, because the org-wide deny wins | Blocked by the org-wide deny |
+| Anything else | Blocked by default deny | Blocked by default deny |
+
+An approval requirement adds a step before access is allowed. If the Data
+team's policy required approval, a Data team member's first request to
+`packages.example.com` would be blocked and they'd be asked to approve it, and
+later requests would succeed. `paste.example.com` would still be blocked
+without asking, because a deny never asks for approval. For more details, see
+[Approval-required access](network.md#approval-required-access).
+
+### How organization policy relates to local and kit rules
+
+Your organization's rules aren't the only ones on a developer's machine.
+Developers also have their own local rules, and kits can add rules to the
+sandboxes that use them. What applies depends on whether an organization
+policy is enforced for the developer:
+
+- No organization policy: local rules and any kit rules determine what
+ sandboxes can access.
+- Organization policy enforced: organization policy determines what access can
+ be granted. Only organization allow rules grant access, so local and kit
+ allow rules are inactive and can't expand what the organization permits.
+ Deny rules apply from every source, so a local or kit deny rule can still
+ restrict access further.
+
+The following table summarizes which rules are evaluated when an organization
+policy is enforced:
+
+| Rule | Evaluated |
+| ------------------ | --------- |
+| Organization allow | Yes |
+| Organization deny | Yes |
+| Local allow | No |
+| Local deny | Yes |
+| Kit allow | No |
+| Kit deny | Yes |
+
+Local and kit rules cover network access only, so a local or kit deny can
+narrow your network rules but never your filesystem or MCP rules. A local deny
+also takes precedence over an organization approval requirement, so the request
+is blocked without asking for approval.
+
+Approved destinations are the one exception to local allow rules being
+inactive. When a developer approves a destination, the resulting rule records
+their answer to your policy's approval requirement rather than granting new
+access, so it stays active.
+
+## When policy changes reach developers
+
+Policy changes reach developer machines within 5 minutes. When a synced change
+takes effect also depends on the policy type. For more details, see
+[Organization network access policies](network.md#when-changes-take-effect),
+[Organization filesystem access policies](filesystem.md#when-changes-take-effect), and
+[Organization MCP access policies](mcp.md#when-changes-take-effect).
+
+To apply changes right away on a developer machine, or if a change doesn't seem
+to apply, see
+[Organization policy changes aren't taking effect](../../troubleshooting.md#organization-policy-changes-arent-taking-effect).
diff --git a/content/manuals/ai/governance/organization/policies/create-manage.md b/content/manuals/ai/governance/organization/policies/create-manage.md
new file mode 100644
index 0000000000..1ff34ef02b
--- /dev/null
+++ b/content/manuals/ai/governance/organization/policies/create-manage.md
@@ -0,0 +1,105 @@
+---
+title: Create and manage organization policies
+linkTitle: Create and manage
+weight: 40
+description: Create, scope, edit, and delete organization network, filesystem, and MCP policies in Docker Home.
+keywords: docker sandboxes, organization policy, create policy, Docker Home, team scope, policy limits
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Create and manage organization policies in Docker Home. The steps are the same
+for network, filesystem, and MCP policies, and only the rules you add differ.
+To manage policies programmatically instead, use the
+[AI Governance API](/reference/api/ai-governance/). For how scope, rule
+evaluation, and precedence work, see [Organization policies](_index.md).
+
+## Before you begin
+
+You need the organization
+[owner](/manuals/security/roles-and-permissions/core-roles.md) role, or a
+[custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md)
+with the **Governance** permissions.
+
+## Create a policy
+
+1. Sign in to [Docker Home](https://app.docker.com) and select your
+ organization.
+1. In the left-hand navigation, expand **AI Platform** and select
+ **Network access**, **Filesystem access**, or **MCP access**.
+1. Select **Create policy**.
+1. Enter a **Policy name**.
+1. Set the **Scope** to **Organization** or **Teams**. If you select **Teams**,
+ choose the teams the policy applies to. For more details, see
+ [Scope policies to teams](#scope-policies-to-teams).
+1. Define the policy rules.
+ - Network and filesystem policies: select **Add rule** for each rule. For a
+ network policy, see
+ [What a network rule can match](network.md#what-a-network-rule-can-match).
+ For a filesystem policy, see
+ [Filesystem mount rule syntax](../../reference/filesystem-rules.md).
+ - MCP policies: enter Cedar statements in the policy editor. For more
+ details, see [Organization MCP access policies](mcp.md).
+1. For a network policy, set **Require approval before access** if developers
+ should confirm each destination before a sandbox can reach it. The policy's
+ detail page reports approval as **Required** or **Not required**. For more
+ details, see [Approval-required access](network.md#approval-required-access).
+
+For the number of policies and rules you can create, see
+[Organization policy limits](../../reference/policy-limits.md).
+
+## Scope policies to teams
+
+To scope a policy to teams, the teams must already exist in your organization.
+Create teams and manage their members in one of two ways:
+
+- Manually, by
+ [creating teams](/manuals/accounts/organization/manage/manage-a-team.md) in
+ Docker Home.
+- Automatically, by using
+ [group mapping](/manuals/security/provisioning/scim/group-mapping.md)
+ to synchronize your identity provider's groups with the teams in your
+ organization. Group mapping creates teams that don't already exist and keeps
+ their membership in step with your IdP groups.
+
+A team-scoped policy follows team membership, so when someone joins or leaves a
+team, including through IdP sync, the policies that apply to them update
+automatically. For how org-wide and team-scoped policies combine, see
+[Policy scope](_index.md#policy-scope).
+
+## Edit or delete a policy
+
+1. Sign in to [Docker Home](https://app.docker.com) and select your
+ organization.
+1. In the left-hand navigation, expand **AI Platform** and select
+ **Network access**, **Filesystem access**, or **MCP access**.
+1. Find the policy in the list. Each policy is listed with its name, scope,
+ rule count, and last update.
+1. Select the action menu (⋮) for the policy, then select **Edit**, or delete
+ the policy.
+1. If you're editing, make your changes and select **Save**.
+
+Editing a policy replaces it in full. For example, turning off **Require
+approval before access** on a network policy removes the requirement from every
+rule in that policy. Changes reach developer machines within 5 minutes. For more
+details, see
+[When policy changes reach developers](_index.md#when-policy-changes-reach-developers).
+
+## Configure a support message
+
+Administrators can add an optional support message that appears after the policy denial
+details when an organization policy blocks a sandbox action. Use it to
+point members to an internal support channel, ticket queue, or security contact.
+
+To set the message:
+
+1. Sign in to [Docker Home](https://app.docker.com) and select your
+ organization.
+1. In the left-hand navigation, expand **AI Platform** and select **Manage**.
+1. In **Support message**, enter up to 500 characters.
+1. Select **Save changes**.
+
+Docker shows the message only for denials caused by an organization policy and
+for requests an
+[approval-required policy](network.md#approval-required-access) blocks. If you
+leave it blank, Docker shows the policy denial without additional contact text.
diff --git a/content/manuals/ai/governance/organization/policies/filesystem.md b/content/manuals/ai/governance/organization/policies/filesystem.md
new file mode 100644
index 0000000000..b24ac20377
--- /dev/null
+++ b/content/manuals/ai/governance/organization/policies/filesystem.md
@@ -0,0 +1,48 @@
+---
+title: Organization filesystem access policies
+linkTitle: Filesystem
+weight: 20
+description: Control which host paths Docker Sandboxes can mount as workspaces with organization filesystem policies.
+keywords: docker sandboxes, filesystem access, filesystem mount rules, workspace mount, organization policy, governance
+aliases:
+ - /ai/sandboxes/governance/access-controls/filesystem/
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Filesystem access policies control which host paths a sandbox can mount as a
+workspace. When an organization policy is enforced for a developer, a sandbox
+can mount a path only if one of your filesystem mount rules allows it, so a
+developer can't create a sandbox for a directory you haven't approved. The
+rules work at the level of the mount. Once a path is mounted, they don't
+control which files inside it an agent can read or change.
+
+Without an organization policy, a sandbox can mount any host path the developer
+chooses. Developers can't add filesystem mount rules with local policy, but it
+includes two built-in rules that allow read and write access to every path,
+which developers see as `default-fs-*` rules in `sbx policy ls --wide`. Under
+an enforced organization policy, those built-in rules stop applying, and only
+your filesystem mount rules decide which paths a sandbox can mount. For more
+details, see
+[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules).
+
+This page explains what a filesystem mount rule can match and when your changes
+reach developers. To create a filesystem access policy, see
+[Create and manage organization policies](create-manage.md).
+
+## What a filesystem mount rule can match
+
+Each filesystem mount rule allows or denies `read`, `write`, or both on the
+host paths it lists. A read-only workspace needs only `read`, and a writable
+workspace needs both. Paths can use wildcards, and `~` expands to each user's
+home directory, so a single `~/**` rule matches every developer's home tree.
+For the path formats on each operating system and how wildcards match, see
+[Filesystem mount rule syntax](../../reference/filesystem-rules.md).
+
+## When changes take effect
+
+Filesystem policy is checked when a sandbox is created and each time it starts.
+Once a policy change has
+[synced to the developer's machine](_index.md#when-policy-changes-reach-developers),
+it applies the next time a sandbox starts. A sandbox that's already running
+keeps its mount until it stops.
diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/governance/organization/policies/mcp.md
similarity index 64%
rename from content/manuals/ai/sandboxes/governance/access-controls/mcp.md
rename to content/manuals/ai/governance/organization/policies/mcp.md
index 07475cb898..4705fe16d5 100644
--- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md
+++ b/content/manuals/ai/governance/organization/policies/mcp.md
@@ -1,36 +1,52 @@
---
-title: MCP access policies
-linkTitle: MCP access
-weight: 50
+title: Organization MCP access policies
+linkTitle: MCP
+weight: 30
description: Use Cedar-based policies to control MCP server registration and activity routed through the Docker Sandboxes MCP gateway.
keywords: docker sandboxes, MCP policy, MCP access, Cedar policy, requireApproval, AI Governance
+aliases:
+ - /ai/sandboxes/governance/access-controls/mcp/
---
+{{< summary-bar feature_name="AI Governance" >}}
+
MCP access policies let organization administrators control which Model
Context Protocol (MCP) servers developers can register and what agents can do
through Docker's MCP gateway. Use these policies to approve trusted servers,
withdraw access to a server, require approval for tool calls, and restrict
host-run servers. To register MCP servers and connect them to sandboxes, see
-[MCP gateway](../../mcp-gateway.md).
+[MCP gateway](../../../sandboxes/mcp-gateway.md).
MCP access policies apply only to server registration and requests handled by
Docker's MCP gateway. They don't govern an MCP server that an agent or MCP
client configures and connects to directly from inside the sandbox. A direct
connection to a remote MCP server is outbound sandbox traffic, so
-[network access policy](network.md) determines whether the sandbox can reach
-the server. To prevent access through both paths, block the server in MCP
-access policy and block its network destination in network access policy.
+[organization network access policies](network.md) determine whether the
+sandbox can reach the server. To prevent access through both paths, block the
+server in MCP access policy and block its network destination in network access
+policy.
-Unlike [network access policies](network.md) and
-[filesystem access policies](filesystem.md), MCP policies are organization
-policies written in Cedar. Docker defines the `MCP` namespace, including the
-actions, resource types, attributes, and approval behavior that policies can
-match. This page focuses on representative access patterns. For Docker's exact
-policy surface, see the [MCP policy reference](../reference/mcp-policy.md). For
-Cedar syntax and language semantics, see the
-[Cedar documentation](https://docs.cedarpolicy.com/).
+Developers can't restrict MCP activity with local policy. Without an enforced
+organization policy, the gateway doesn't evaluate Cedar policy and permits all
+MCP activity. For more details, see
+[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules).
-## Govern the server lifecycle
+MCP policies are written in Cedar. Docker defines the `MCP` namespace your
+statements use, including the actions, resource types, attributes, and approval
+annotation you can match. The examples on this page cover common access
+patterns. For every action and attribute, see the
+[MCP policy reference](../../reference/mcp-policy.md), and for Cedar syntax,
+see the [Cedar documentation](https://docs.cedarpolicy.com/). If you manage
+policies through the [AI Governance API](/reference/api/ai-governance/), an MCP
+policy is a `cedar_v1` policy whose statements are part of the policy text
+rather than separate rules.
+
+This page explains where MCP policy applies, how to choose between an allowlist
+and a blocklist, example policies for common tasks, and when your changes reach
+developers. To create an MCP access policy and set its scope, see
+[Create and manage organization policies](create-manage.md).
+
+## Where MCP policy applies
MCP policy applies at two points in a server's lifecycle. A rule for one point
doesn't automatically govern the other.
@@ -40,28 +56,28 @@ doesn't automatically govern the other.
| Whether a server can be registered | When a developer runs `sbx mcp add` | The registered name and resolved server attributes, such as `identityURL` |
| What agents can do through the MCP gateway | When the gateway handles a governed request | The registered server name, tool annotations, resource URI, or prompt name |
-Registration rules affect future registrations. They don't remove a saved
-registration or prevent an existing registration from being loaded with
-`sbx mcp load`. Use-time rules govern tool calls, resource reads, and prompt
-retrieval from servers that are already registered or loaded.
+Registration rules apply when a developer registers a server. They affect only
+future registrations, so they don't remove a saved registration or stop an
+existing one from being loaded with `sbx mcp load`.
-Server names are chosen during registration. Registration rules can match the
-chosen name and resolved server identity together. At use time, tools,
-resources, and prompts are associated with the registered name, so rules for an
-existing server must match every name under which it was registered.
+Use-time rules apply to tool calls, resource reads, and prompt retrieval from
+servers that are already registered or loaded. They don't hide anything:
+registrations stay saved, and tool and resource listings can still show
+entries that policy denies when an agent tries to use them.
+
+Developers choose a server's name when they register it. Registration rules can
+match that name together with the resolved server identity. At use time, tools,
+resources, and prompts are tied to the registered name, so rules for an
+existing server must match every name it was registered under.
Built-in gateway tools, such as `mcp-add`, `code-mode`, and OAuth authorization
-helpers, are also governed at use time. They are `MCP::Primordial` resources
-rather than tools associated with a registered server. For details, see
-[Built-in gateway tools](../../mcp-gateway.md#built-in-gateway-tools).
+helpers, are governed at use time too. They're `MCP::Primordial` resources
+rather than tools of a registered server. For details, see
+[Built-in gateway tools](../../../sandboxes/mcp-gateway.md#built-in-gateway-tools).
-Use-time policy doesn't hide or remove existing registrations. Tool and
-resource listings can also include entries that policy denies when an agent
-tries to use them.
+## Allowlist and blocklist policies
-## Choose an access posture
-
-When MCP policy enforcement is active for a user, registration and governed MCP
+When an organization policy is enforced for a developer, registration and governed MCP
requests are denied unless a matching `permit` allows them. A matching `forbid`
overrides any `permit`, including a permit with `@requireApproval`.
@@ -75,12 +91,17 @@ permit (principal, action, resource);
This statement permits every MCP action that reaches Cedar evaluation. Add
`forbid` statements for the restrictions the policy must enforce.
-Policy scope supplies the principal. Use organization or team scope instead of
-matching users, teams, tenants, or roles in Cedar. If MCP policy enforcement
-isn't active for a user, the gateway doesn't evaluate Cedar policy and permits
-MCP activity. MCP doesn't have a local preset equivalent to network policy.
+You don't need to match users, teams, tenants, or roles in Cedar. The policy's
+organization or team scope decides who it applies to and supplies the
+principal.
-## Approve a server
+## Example policies
+
+The following policies show common ways to approve, confirm, withdraw, and
+restrict MCP servers. Combine them in one policy or split them across policies,
+and adapt the server names and identity URLs to your own servers.
+
+### Approve a server
For an allowlist, approve both the server registration and its use-time
capabilities. The following policy approves a remote server only when it is
@@ -114,9 +135,9 @@ when { resource in MCP::Server::"example" };
Matching both the name and identity URL establishes a canonical registration.
It prevents a developer from registering another endpoint under the approved
name or registering the approved endpoint under another name. Remove the
-resource or prompt permit if users don't need that capability.
+resource or prompt permit if developers don't need that capability.
-## Require confirmation with MCP elicitation
+### Require confirmation with MCP elicitation
Use `@requireApproval` to require per-request confirmation through MCP. When a
request matches the annotated `permit`, the gateway sends an
@@ -174,11 +195,11 @@ permit with `@requireApproval` results in a denial. Tool calls made from an
execution context that can't relay an elicitation, including calls from inside
`code-mode`, are also denied.
-## Withdraw server access
+### Withdraw server access
To withdraw access from a server that broader rules permit, block it at
-registration and at use time. Registration policy controls future `sbx mcp add`
-operations, while use-time policy controls requests from servers that are
+registration and at use time. Registration rules control future `sbx mcp add`
+operations, while use-time rules control requests from servers that are
already registered or loaded.
Prevent future registrations of the server by matching its identity URL:
@@ -215,12 +236,12 @@ forbid (principal, action == MCP::Action::"invokePrimordial", resource)
when { resource in MCP::Primordial::"example-authorize" };
```
-## Restrict host-run servers
+### Restrict host-run servers
Local stdio servers run on the host, outside the sandbox VM. This includes
explicit host commands and OCI-packaged stdio servers started with host Docker.
For details about this boundary, see
-[Docker Engine isolation](../../security/isolation.md#docker-engine-isolation).
+[Docker Engine isolation](../../../sandboxes/security/isolation.md#docker-engine-isolation).
In a blocklist policy that otherwise permits registration, deny the host-run
server type:
@@ -234,12 +255,18 @@ when { resource.type == "local-stdio" };
container, and OCI-packaged stdio servers resolved from registry or manifest
metadata with `--local`.
-## Related information
+## When changes take effect
-- [MCP policy concepts](../concepts.md#mcp-policies): policy model and rule
- evaluation.
-- [MCP policy reference](../reference/mcp-policy.md): exact action, resource,
- attribute, context, and approval behavior.
-- [Organization policies](organization.md): policy creation and scope.
-- [MCP policy audit logs](../audit/): policy decision
- records.
+Registration rules are evaluated when a server is registered with
+`sbx mcp add`. Changing registration rules doesn't remove existing
+registrations or stop an already-loaded server by itself.
+
+Use-time rules are evaluated by the MCP gateway when a sandbox makes a
+governed MCP request, such as a tool call, resource read, prompt retrieval, or
+built-in gateway tool call. Once a policy change has
+[synced to the developer's machine](_index.md#when-policy-changes-reach-developers),
+use-time rules apply to subsequent governed MCP requests through the gateway.
+
+To prevent use of an MCP server that is already registered or loaded, add
+use-time rules for the registered server name. For more details, see
+[Withdraw server access](#withdraw-server-access).
diff --git a/content/manuals/ai/governance/organization/policies/network.md b/content/manuals/ai/governance/organization/policies/network.md
new file mode 100644
index 0000000000..73a548c17f
--- /dev/null
+++ b/content/manuals/ai/governance/organization/policies/network.md
@@ -0,0 +1,119 @@
+---
+title: Organization network access policies
+linkTitle: Network
+weight: 10
+description: Control outbound network access from Docker Sandboxes with organization network access policies.
+keywords: docker sandboxes, network access, network rules, HTTP rules, approval, governance, organization policy
+aliases:
+ - /ai/sandboxes/governance/access-controls/network/
+---
+
+{{< summary-bar feature_name="AI Governance" >}}
+
+Network access policies are organization policies that control outbound
+connections from sandboxes. When an organization policy is enforced for a
+developer, their sandboxes can reach only the destinations your network rules
+allow. Each policy contains one or more rules that allow the hosts, IP
+ranges, and ports a workflow needs, or block destinations that should stay
+unavailable. Rules can also match the HTTP method and path of a request, so a
+policy can allow part of an API without allowing all of it.
+
+Developers can also add network rules on their own machines with
+[local policy](../../local/network-rules.md), but under an enforced
+organization policy, only your allow rules grant access. For more details, see
+[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules).
+
+For destinations you want a person to confirm, a policy can require approval
+instead of granting access outright. This page explains what a rule can match,
+how approval works, and when your changes reach developers. To create a network
+access policy, see [Create and manage organization policies](create-manage.md).
+
+## What a network rule can match
+
+Each rule has an optional **Rule name**, a **Type** that decides what the rule
+matches, and a **Decision** of **Allow** or **Deny**. The type is either
+**All traffic**, which covers whole destinations, or **HTTP**, which covers
+specific requests to one destination.
+
+### All traffic rules
+
+An **All traffic** rule matches every request to the destinations you list, on
+any port, method, and path.
+
+- Under **Protocols**, select **TCP**, **UDP**, or **Both**.
+- Under **Destinations**, add the hosts, IP addresses, or CIDR ranges the rule
+ covers. A destination matches any port unless you add one, such as
+ `example.com:8080`.
+
+### HTTP rules
+
+An **HTTP** rule matches only HTTP requests with the methods and paths you
+specify.
+
+- In **Destination**, enter the host or IP address the rule covers. It matches
+ any port unless you add one. Enter the destination with no scheme and no
+ path, so `api.github.com` rather than `https://api.github.com/repos`.
+- Under **HTTP methods**, select the methods the rule applies to. Use
+ **Select all** to select every method, or **Read-only** to select `GET`,
+ `HEAD`, and `OPTIONS`. Select at least one method. A rule with no methods
+ selected fails validation. The composer doesn't list `CONNECT` or `TRACE`,
+ which differs from the CLI, where `--method ANY` matches every HTTP method.
+- Under **Path patterns**, add one or more paths the rule covers, such as
+ `/repos/*` and `/v1/**`. Leave it empty to match any path.
+
+An HTTP rule's paths all belong to its one destination, so to cover paths on a
+second host, add a second rule. For the pattern syntax and how HTTP rules
+combine with **All traffic** rules, see
+[HTTP rules](../../reference/network-rules.md#http-method-and-path).
+
+## Approval-required access
+
+A network access policy can require approval instead of granting access
+outright. Destinations the policy allows aren't reachable until the developer
+confirms them, which keeps an allowlist broad enough to be usable while still
+putting a person in front of each destination an agent reaches for. To turn
+it on when you create or edit a policy, see
+[Create and manage organization policies](create-manage.md).
+
+In an organization policy, approval is a property of the policy rather than of
+individual rules, so turning it on applies it to every allow rule in that
+policy. A destination stays directly reachable only when no policy that
+allows it requires approval. If a policy that requires approval also matches,
+the request needs approval regardless of what the other policies allow.
+
+A request is handled as follows:
+
+```mermaid
+flowchart TD
+ request["Sandbox sends an outbound request"] --> denied{"Does any deny rule match?"}
+ denied -->|"Yes, from any source"| block["Block request"]
+ denied -->|"No"| orgallow{"Does an organization policy allow it?"}
+ orgallow -->|"No"| block
+ orgallow -->|"Yes"| needs{"Does any allowing policy require approval?"}
+ needs -->|"No"| allow["Allow request"]
+ needs -->|"Yes"| approved{"Did the developer already approve this destination?"}
+ approved -->|"Yes"| allow
+ approved -->|"No"| ask["Block request and ask the developer to approve"]
+ ask -.->|"Later requests after approval"| allow
+```
+
+Only a destination the developer has already approved satisfies the requirement.
+Preset rules, kit rules, and rules the developer added with `sbx policy
+allow network` don't answer it. An approval also can't reach a destination the
+organization doesn't allow at all, and it can't override a deny rule. To
+withdraw a destination, add a deny rule, which takes precedence over any
+approval already recorded.
+
+Developers respond to approval requests from the command line. For what they
+see and how they respond, see
+[Respond to approval requests](../../local/approvals.md).
+
+## When changes take effect
+
+Network policy is evaluated on every outbound request. Once a policy change has
+[synced to the developer's machine](_index.md#when-policy-changes-reach-developers),
+it applies immediately to subsequent requests.
+
+An approval requirement applies from the point the policy change syncs.
+Destinations a developer already approved stay reachable, because the approval
+is recorded on the developer's machine.
diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md b/content/manuals/ai/governance/organization/sign-in-enforcement.md
similarity index 72%
rename from content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md
rename to content/manuals/ai/governance/organization/sign-in-enforcement.md
index 8f60dac44d..872c512d47 100644
--- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md
+++ b/content/manuals/ai/governance/organization/sign-in-enforcement.md
@@ -1,30 +1,27 @@
---
-title: Sign-in enforcement
-linkTitle: Sign-in enforcement
+title: Enforce sign-in for Docker Sandboxes
+linkTitle: Enforce sign-in
weight: 20
description: Require Docker Sandboxes users to sign in as members of your organization, enforced through endpoint management.
keywords: docker sandboxes, sign-in enforcement, organization enforcement, sbx login, MDM, configuration profile, registry key, allowedOrgs
aliases:
- /ai/sandboxes/governance/sign-in-enforcement/
+ - /ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement/
---
-Sign-in enforcement restricts Docker Sandboxes to users who are members of
-specific Docker organizations. An administrator deploys an enforcement
-configuration to managed endpoints, and `sbx login` verifies organization
-membership after the user authenticates. If the check fails, credentials are
-immediately revoked and the user can't run sandboxes.
+{{< summary-bar feature_name="AI Governance" >}}
-Without this enforcement, a developer can sign in with a personal account and
-bypass organization [governance policies](../access-controls/organization.md).
-Sign-in enforcement closes that gap at the endpoint, where users can't override
-it.
+Organization policies apply only when a developer signs in to Docker Sandboxes
+as a member of your organization.
+Without sign-in enforcement, a developer can sign in with a personal account
+and bypass those policies. Sign-in enforcement closes that gap on the machine
+itself, where users can't override it.
-> [!NOTE]
-> Sign-in enforcement is part of Docker's AI Governance offering.
-> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales)
-> to learn more.
+To set it up, you write an enforcement configuration that lists your
+organizations, test it on one machine, then deploy it to your developers'
+machines with your endpoint management tooling.
-## How it works
+## How sign-in enforcement works
1. An administrator deploys an enforcement configuration to managed endpoints
through MDM, Group Policy, or configuration management, specifying one or
@@ -32,20 +29,21 @@ it.
2. When a user runs `sbx login`, they authenticate with Docker. Credentials
are saved temporarily, then Docker Sandboxes calls the Docker API to
verify organization membership.
-3. If the user belongs to at least one allowed organization, login succeeds and
+3. If the user belongs to at least one allowed organization, sign-in succeeds and
the credentials are kept.
4. If not, Docker Sandboxes immediately revokes the saved credentials and the
- user receives an [error message](#error-messages) listing the required
- organizations.
+ user receives a [denial message](#check-what-denied-developers-see) listing
+ the required organizations.
`sbx login` and `sbx logout` always run regardless of organization membership.
Other commands require a valid signed-in session, so they fail after a denied
-login until the user signs in with an allowed account.
+sign-in until the user signs in with an allowed account.
-## Enforcement configuration
+## Write the enforcement configuration
-All platforms express the same logical schema. The canonical JSON
-representation:
+The configuration lists the organizations developers must belong to, and
+optionally who to contact for access. Every platform uses the same fields. The
+canonical JSON representation:
```json
{
@@ -70,7 +68,82 @@ The optional `adminName`, `adminEmail`, and `adminURL` fields give denied users
a path to resolution. Include the contact details your organization uses for
access requests.
-## Deploy the configuration
+## Test the configuration on one machine
+
+Before you deploy to every machine, write the configuration on one machine and
+confirm that `sbx login` behaves as you expect.
+
+{{< tabs >}}
+{{< tab name="macOS" >}}
+
+Write the configuration to the user preferences domain:
+
+```console
+$ defaults write com.docker.sbx allowedOrgs -array "acme-corp"
+$ defaults write com.docker.sbx adminEmail "it@acme.com"
+```
+
+To remove the test configuration:
+
+```console
+$ defaults delete com.docker.sbx
+```
+
+`defaults write` uses the user preferences domain, not the managed-preferences
+domain. On a managed device, the MDM profile is authoritative and user-level
+settings in the same domain are ignored.
+
+{{< /tab >}}
+{{< tab name="Windows" >}}
+
+Run the following in an elevated PowerShell session. Use `New-ItemProperty` to
+create values with an explicit type. `Set-ItemProperty` doesn't create new
+values.
+
+```powershell
+New-Item -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" -Force
+
+New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" `
+ -Name "allowedOrgs" -Value @("acme-corp") -PropertyType MultiString -Force
+New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" `
+ -Name "adminEmail" -Value "it@acme.com" -PropertyType String -Force
+```
+
+To remove the test configuration:
+
+```powershell
+Remove-Item -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" -Recurse -Force
+```
+
+{{< /tab >}}
+{{< tab name="Linux" >}}
+
+Write the configuration file and set its ownership:
+
+```console
+$ sudo mkdir -p /etc/docker-sbx
+$ sudo tee /etc/docker-sbx/config.json <<'EOF'
+{"allowedOrgs": ["acme-corp"], "adminEmail": "it@acme.com"}
+EOF
+$ sudo chown root:root /etc/docker-sbx/config.json
+$ sudo chmod 644 /etc/docker-sbx/config.json
+```
+
+To remove the test configuration:
+
+```console
+$ sudo rm -f /etc/docker-sbx/config.json
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
+Then run `sbx login` with an account that belongs to an allowed organization,
+and again with one that doesn't. The second sign-in is denied with the message
+described in
+[Check what denied developers see](#check-what-denied-developers-see).
+
+## Deploy the configuration to your managed machines
Use your existing endpoint management tooling to deploy the configuration. Each
platform reads it from a native location that ordinary users can't modify.
@@ -139,29 +212,12 @@ contact details:
```
-To test the configuration locally without MDM, write to the user preferences
-domain:
-
-```console
-$ defaults write com.docker.sbx allowedOrgs -array "acme-corp"
-$ defaults write com.docker.sbx adminEmail "it@acme.com"
-```
-
-To remove the test configuration:
-
-```console
-$ defaults delete com.docker.sbx
-```
-
-`defaults write` uses the user preferences domain, not the managed-preferences
-domain. On a managed device, the MDM profile is authoritative and user-level
-settings in the same domain are ignored.
-
{{< /tab >}}
{{< tab name="Windows" >}}
-Deploy it through Group Policy, Intune, or any endpoint management tool that can
-write registry values.
+On Windows, the configuration is a set of registry values under
+`HKLM\SOFTWARE\Policies\Docker\SBX`. Deploy them through Group Policy, Intune,
+or any endpoint management tool that can write registry values.
| Value name | Type | Description |
| ------------- | -------------- | --------------------------------------------------- |
@@ -170,25 +226,6 @@ write registry values.
| `adminEmail` | `REG_SZ` | Contact email (optional) |
| `adminURL` | `REG_SZ` | Help desk URL (optional) |
-To test the configuration locally, run the following in an elevated PowerShell
-session. Use `New-ItemProperty` to create values with an explicit type;
-`Set-ItemProperty` doesn't create new values.
-
-```powershell
-New-Item -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" -Force
-
-New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" `
- -Name "allowedOrgs" -Value @("acme-corp") -PropertyType MultiString -Force
-New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" `
- -Name "adminEmail" -Value "it@acme.com" -PropertyType String -Force
-```
-
-To remove the configuration:
-
-```powershell
-Remove-Item -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" -Recurse -Force
-```
-
{{< /tab >}}
{{< tab name="Linux" >}}
@@ -207,37 +244,22 @@ Salt. The file must be owned by root with `644` permissions.
}
```
-To deploy and set ownership:
-
-```console
-$ sudo mkdir -p /etc/docker-sbx
-$ sudo tee /etc/docker-sbx/config.json <<'EOF'
-{"allowedOrgs": ["acme-corp"], "adminEmail": "it@acme.com"}
-EOF
-$ sudo chown root:root /etc/docker-sbx/config.json
-$ sudo chmod 644 /etc/docker-sbx/config.json
-```
-
-To remove the configuration:
-
-```console
-$ sudo rm -f /etc/docker-sbx/config.json
-```
-
The Linux loader fails closed if the file is a symlink, isn't a regular file,
isn't owned by root, or is writable by group or other. Any deviation is treated
as a configuration error and `sbx login` is denied with a descriptive message.
-Deploying with the commands above passes these checks.
+Deploying with the commands in
+[Test the configuration on one machine](#test-the-configuration-on-one-machine)
+passes these checks.
{{< /tab >}}
{{< /tabs >}}
-## Error messages
+## Check what denied developers see
When a user signs in with an account that isn't a member of an allowed
organization, they're signed out and shown a denial message. Only the contact
-fields you configure appear: if only `adminEmail` is set, the URL line is
-omitted.
+fields you configure appear. For example, if only `adminEmail` is set, the URL
+line is omitted.
When no admin contact details are configured:
@@ -262,12 +284,9 @@ For access, contact ACME IT Security:
URL: https://acme-corp.atlassian.net/servicedesk/it
```
-## Related pages
+## Turn off enforcement
-- [Organization policies](../access-controls/organization.md): centrally manage
- sandbox network, filesystem, and MCP access controls from the Docker Admin
- Console
-- [Governance overview](../_index.md): how local and organization governance fit
- together
-- [Enforce sign-in for Docker Desktop](/manuals/desktop/enterprise/enforce-sign-in/_index.md):
- the equivalent control for Docker Desktop
+To turn off sign-in enforcement on a machine, remove the configuration with
+the same tooling you used to deploy it. You can also leave `allowedOrgs` empty,
+which makes enforcement inactive so any authenticated user can use Docker
+Sandboxes.
diff --git a/content/manuals/ai/governance/reference/_index.md b/content/manuals/ai/governance/reference/_index.md
new file mode 100644
index 0000000000..ad95776290
--- /dev/null
+++ b/content/manuals/ai/governance/reference/_index.md
@@ -0,0 +1,6 @@
+---
+build:
+ render: never
+title: Reference
+weight: 30
+---
diff --git a/content/manuals/ai/sandboxes/governance/reference/api.md b/content/manuals/ai/governance/reference/api.md
similarity index 74%
rename from content/manuals/ai/sandboxes/governance/reference/api.md
rename to content/manuals/ai/governance/reference/api.md
index 36e6297f16..8004ee7de4 100644
--- a/content/manuals/ai/sandboxes/governance/reference/api.md
+++ b/content/manuals/ai/governance/reference/api.md
@@ -1,11 +1,13 @@
---
title: AI Governance API
-linkTitle: API reference
+linkTitle: AI Governance API
+weight: 50
description: Programmatic management of Docker AI Governance policies and rules via HTTP+JSON.
keywords: docker sandboxes, AI Governance API, governance API, policy API, organization policies
-weight: 10
build:
render: never
sidebar:
- goto: /reference/api/ai-governance/
+ goto: /reference/api/ai-governance/latest/
---
+
+
diff --git a/content/manuals/ai/governance/reference/audit-logs-api.md b/content/manuals/ai/governance/reference/audit-logs-api.md
new file mode 100644
index 0000000000..1b88ff509d
--- /dev/null
+++ b/content/manuals/ai/governance/reference/audit-logs-api.md
@@ -0,0 +1,11 @@
+---
+title: AI Governance Audit Logs API
+linkTitle: AI Governance Audit Logs API
+weight: 55
+description: HTTP API for retrieving Docker AI Governance audit events programmatically.
+keywords: docker sandboxes, AI Governance, audit logs API, audit events, REST API
+build:
+ render: never
+sidebar:
+ goto: /reference/api/ai-governance-audit-logs/latest/
+---
diff --git a/content/manuals/ai/sandboxes/governance/audit/record-reference.md b/content/manuals/ai/governance/reference/audit-records.md
similarity index 50%
rename from content/manuals/ai/sandboxes/governance/audit/record-reference.md
rename to content/manuals/ai/governance/reference/audit-records.md
index ce547f4e7e..6b229aa2bc 100644
--- a/content/manuals/ai/sandboxes/governance/audit/record-reference.md
+++ b/content/manuals/ai/governance/reference/audit-records.md
@@ -1,9 +1,11 @@
---
title: Audit record reference
-linkTitle: Record reference
-weight: 50
+linkTitle: Audit records
+weight: 40
description: Reference fields, categories, decisions, and payload types for Docker AI Governance audit records.
keywords: docker sandboxes, audit record, audit schema, AI Governance, policy decision, action_type, jsonl
+aliases:
+ - /ai/sandboxes/governance/audit/record-reference/
---
Docker AI Governance audit records use one schema across delivery modes. Local
@@ -15,36 +17,59 @@ action.
## Common fields
-| Field | Description |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `audit_event_id` | Unique ID for the audit event. |
-| `timestamp` | UTC time when Docker recorded the event. |
-| `schema_version` | Version of the record schema. Pin SIEM field mappings to this value. |
-| `category` | Event category, such as `AUDIT_CATEGORY_MANAGEMENT`, `AUDIT_CATEGORY_EVALUATION`, or `AUDIT_CATEGORY_EXECUTION`. |
-| `decision` | Governance decision for evaluation records. |
-| `username` | The signed-in Docker user's Docker Hub username. |
-| `user_email` | The signed-in Docker user's email address. |
-| `org_id` | ID of the organization whose governance policy is in effect. |
-| `org_name` | Display name of the organization whose governance policy is in effect. |
-| `audit_session_id` | Identifies the daemon session that produced the record. |
-| `resource_id` | Target of the evaluation, such as a host and port, file path, or tool. |
-| `os` | Operating system that produced the record. |
-| `app_version` | Version of the Docker component that produced the record. |
-| `client_name` | Source component, such as `sbx` for Docker Sandboxes. |
-| `hostname` | Hostname of the machine that produced the record. |
-| `deny_reason` | Why a denied request was blocked. Present on deny decisions. |
-| `enforcement_mode` | Governance mode in effect when Docker evaluated the request. See [Enforcement modes](#enforcement-modes). |
-| `approval` | Approval details. Present when the decision involves an approval. See [Approval fields](#approval-fields). |
-| `action_type` | Payload discriminator that identifies the action-specific object in the record. |
-| `agent` | AI agent associated with the event, when Docker knows it. |
+| Field | Description |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `audit_event_id` | Unique ID for the audit event. |
+| `timestamp` | UTC time when Docker recorded the event. |
+| `schema_version` | Version of the record schema. Pin SIEM field mappings to this value. |
+| `category` | Event category, such as `AUDIT_CATEGORY_MANAGEMENT`, `AUDIT_CATEGORY_EVALUATION`, or `AUDIT_CATEGORY_EXECUTION`. |
+| `decision` | Governance decision for evaluation records. |
+| `username` | The signed-in Docker user's Docker Hub username. |
+| `user_email` | The signed-in Docker user's email address. |
+| `org_id` | ID of the organization whose policy is in effect. |
+| `org_name` | Display name of the organization whose policy is in effect. |
+| `audit_session_id` | Identifies the daemon session that produced the record. |
+| `resource_id` | Target of the evaluation, such as a host and port, file path, or tool. |
+| `os` | Operating system that produced the record. |
+| `app_version` | Version of the Docker component that produced the record. |
+| `client_name` | Source component, such as `sbx` for Docker Sandboxes. |
+| `hostname` | Hostname of the machine that produced the record. |
+| `sandbox_id` | Stable ID of the sandbox. It persists across restarts of the same sandbox. |
+| `deny_reason` | Why a denied request was blocked. Present on deny decisions. |
+| `policy_rule` | Name of the policy rule that matched, or `default-deny` when no rule matched. |
+| `policy_id` | ID of the policy that produced the decision. |
+| `policy_type` | Schema type of the policy, such as `AllowList:V0`. |
+| `policy_source` | Origin of the policy: `remote`, `local`, or `system`. |
+| `policy_denial_code` | Why a request was denied. Present only on deny decisions. For more details, see [Denial codes](#denial-codes). |
+| `enforcement_mode` | Governance mode in effect when Docker evaluated the request. For more details, see [Enforcement modes](#enforcement-modes). |
+| `approval` | Approval details. Present when the decision involves an approval. For more details, see [Approval fields](#approval-fields). |
+| `action_type` | Payload discriminator that identifies the action-specific object in the record. |
+| `agent` | AI agent associated with the event, when Docker knows it. |
+
+### Denial codes
+
+`policy_denial_code` classifies why a request was denied:
+
+| Code | Meaning |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POLICY_DENIAL_CODE_POLICY_DENY` | A deny rule matched. `policy_id` and `policy_rule` identify it. |
+| `POLICY_DENIAL_CODE_DEFAULT_DENY` | No rule allowed the request, so default deny applied. |
+| `POLICY_DENIAL_CODE_POLICY_SNAPSHOT_STALE` | The cached policy expired, so evaluation failed closed. |
+| `POLICY_DENIAL_CODE_POLICY_EVALUATION_FAILED` | Loading or evaluating the policy failed, so evaluation failed closed. |
+| `POLICY_DENIAL_CODE_GOVERNANCE_BLOCKED` | Governance couldn't be resolved for the user, for example because of membership in several organizations, so the request was denied without consulting local rules. |
+| `POLICY_DENIAL_CODE_INVALID_REQUEST` | The request was malformed, so evaluation failed closed. |
## Categories
-| Category | Description |
-| --------------------------- | ------------------------------------------------------------- |
-| `AUDIT_CATEGORY_MANAGEMENT` | Session lifecycle, policy sync, and configuration events. |
-| `AUDIT_CATEGORY_EVALUATION` | Governance policy decisions, such as allow, deny, or consent. |
-| `AUDIT_CATEGORY_EXECUTION` | Outcomes after an evaluated action runs. |
+| Category | Description |
+| --------------------------- | -------------------------------------------------------------------------- |
+| `AUDIT_CATEGORY_MANAGEMENT` | Session lifecycle, policy sync, and configuration events. |
+| `AUDIT_CATEGORY_EVALUATION` | Policy decisions for individual requests, such as allow, deny, or consent. |
+| `AUDIT_CATEGORY_EXECUTION` | Outcomes after an evaluated action runs. |
+
+Session lifecycle records mark the start and end of each daemon run. Evaluation
+records share the run's `audit_session_id`, so you can correlate every decision
+back to a daemon session.
## Decisions
@@ -63,7 +88,7 @@ Docker evaluated it.
| Mode | Description |
| --------- | ------------------------------------------------------------------------------- |
-| `enforce` | Your organization's governance policy is enforced. |
+| `enforce` | Your organization policy is enforced. |
| `audit` | Docker records the decision for observability but doesn't enforce policy. |
| `off` | Governance isn't active. Docker still writes the record to the local audit log. |
@@ -81,7 +106,7 @@ full approval. The approval applies to later requests from the sandbox. It
doesn't retry the request that was blocked. If the user dismisses the request,
it isn't resolved, so no second record is written and the destination is
requested again the next time the sandbox reaches it. For how approval works,
-see [Approval-required access](../access-controls/network.md#approval-required-access).
+see [Approval-required access](../organization/policies/network.md#approval-required-access).
For MCP approvals, an approved request is evaluated again and recorded with
`AUDIT_DECISION_APPROVAL_ALLOW`, and a declined request is recorded with
@@ -106,25 +131,25 @@ an `AUDIT_DECISION_DENY` decision and includes the `approval` object.
The `action_type` field identifies the action-specific payload in the record.
-| Action type | Description |
-| ---------------------------- | --------------------------------------------------------------------------- |
-| `session` | Sandbox daemon session lifecycle event. |
-| `network_egress` | Network access evaluation. |
-| `http_request` | HTTP request evaluation. See [HTTP request payload](#http-request-payload). |
-| `filesystem_mount` | Filesystem mount or path access evaluation. |
-| `tool_invocation` | Tool invocation evaluation. |
-| `resource_read` | Resource read evaluation. |
-| `server_registration` | Server registration event. |
-| `prompt` | Prompt-related metadata event. |
-| `network_egress_execution` | Outcome of a network action. |
-| `filesystem_mount_execution` | Outcome of a filesystem action. |
-| `tool_execution` | Outcome of a tool invocation. |
-| `resource_read_execution` | Outcome of a resource read. |
-| `prompt_execution` | Outcome of a prompt request. |
-| `policy_sync` | Policy synchronization event. |
-| `pii_detection` | Metadata event for a data detection result. |
-| `c_score_report` | Metadata event for a C-score report. |
-| `policy_action` | Policy configuration or policy action event. |
+| Action type | Description |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| `session` | Sandbox daemon session lifecycle event. |
+| `network_egress` | Network access evaluation. |
+| `http_request` | HTTP request evaluation. For more details, see [HTTP request payload](#http-request-payload). |
+| `filesystem_mount` | Filesystem mount or path access evaluation. |
+| `tool_invocation` | Tool invocation evaluation. |
+| `resource_read` | Resource read evaluation. |
+| `server_registration` | Server registration event. |
+| `prompt` | Prompt-related metadata event. |
+| `network_egress_execution` | Outcome of a network action. |
+| `filesystem_mount_execution` | Outcome of a filesystem action. |
+| `tool_execution` | Outcome of a tool invocation. |
+| `resource_read_execution` | Outcome of a resource read. |
+| `prompt_execution` | Outcome of a prompt request. |
+| `policy_sync` | Policy synchronization event. |
+| `pii_detection` | Metadata event for a data detection result. |
+| `c_score_report` | Metadata event for a C-score report. |
+| `policy_action` | Policy configuration or policy action event. |
## HTTP request payload
@@ -142,29 +167,38 @@ separate from the `network_egress` record for the connection.
## Sample record
+The following sample shows a request that a deny rule blocked:
+
```json
{
- "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80",
- "timestamp": "2026-05-28T19:15:00.728933Z",
- "schema_version": "1.82.0",
+ "audit_event_id": "032d5bf2-6be0-484c-9fd1-296680bb9af4",
+ "timestamp": "2026-10-22T21:15:32.674118Z",
+ "schema_version": "1.228.0",
"category": "AUDIT_CATEGORY_EVALUATION",
"decision": "AUDIT_DECISION_DENY",
"username": "jordandoe",
"user_email": "jordandoe@example.com",
+ "audit_session_id": "d038717d-e86d-48c5-abbb-19b7f14c37c8",
+ "agent": "shell",
+ "sandbox_id": "my-sandbox",
+ "resource_id": "example.com:443",
+ "policy_rule": "local:fa56f4d3-7f16-4144-af84-caa7917b2387",
+ "policy_id": "f588126a-8323-47d5-b099-b3d184055733",
+ "policy_type": "AllowList:V0",
+ "policy_source": "local",
+ "policy_denial_code": "POLICY_DENIAL_CODE_POLICY_DENY",
"org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
"org_name": "Acme Inc",
- "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578",
- "resource_id": "example.com:443",
- "os": "macos",
- "app_version": "v0.31.0",
+ "os": "windows",
+ "app_version": "v0.48.0",
"client_name": "sbx",
"hostname": "host-machine",
"deny_reason": [
- "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)"
+ "denied: rule \"local:fa56f4d3-7f16-4144-af84-caa7917b2387\" matched op(action=net:connect:tcp, resource=net:domain:example.com:443)"
],
+ "enforcement_mode": "audit",
"action_type": "network_egress",
- "network_egress": { "protocol": "tcp" },
- "agent": "claude"
+ "network_egress": { "destination_port": "443", "protocol": "tcp" }
}
```
diff --git a/content/manuals/ai/governance/reference/filesystem-rules.md b/content/manuals/ai/governance/reference/filesystem-rules.md
new file mode 100644
index 0000000000..e2291f6769
--- /dev/null
+++ b/content/manuals/ai/governance/reference/filesystem-rules.md
@@ -0,0 +1,49 @@
+---
+title: Filesystem mount rule syntax
+linkTitle: Filesystem mount rules
+weight: 20
+description: Syntax for sandbox filesystem mount rules, including path patterns across macOS, Linux, Windows, and WSL.
+keywords: docker sandboxes, filesystem rules, path patterns, workspace mount, rule syntax
+---
+
+Filesystem mount rules are written in
+[organization filesystem access policies](../organization/policies/filesystem.md).
+Developers can't add them with local policy. Filesystem mount rules use the
+actions `read` and `write`. Resources are host paths that sandboxes can mount
+as workspaces. The rules control which paths a sandbox can mount, not access to
+individual files inside an allowed mount.
+
+A workspace mounted with write access must be allowed by both a `read` and a
+`write` rule. A read-only workspace needs only `read`. When default deny blocks
+a mount, the denial reason names whether read or write access was missing.
+
+`~` expands to the user's home directory on every platform, including Windows,
+where it resolves to `%USERPROFILE%`. A single `~/**` rule therefore matches
+each user's home tree on macOS, Linux, and Windows. The policy engine expands
+only `~`: it does not expand environment variables, so a pattern such as
+`%USERPROFILE%\**` or `$HOME/**` matches nothing.
+
+For a path outside the home directory, write it in the format the user's
+operating system uses. A rule matches only the format it's written in, so a
+location that several platforms share needs a rule for each:
+
+| Operating system | Example path |
+| ---------------- | ------------------------------------------ |
+| macOS, Linux | `/data/project/**` |
+| Windows | `C:\data\project\**` |
+| WSL | `\\wsl.localhost\\data\project\**` |
+
+On Windows, `*:` matches any drive letter, so `*:\data\**` matches the path on
+any drive.
+
+Wildcards behave the same way in every path format:
+
+| 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 `**` to match a directory tree recursively. A single `*` matches within one
+path segment and won't cross a path separator. For example, `~/**` matches all
+paths under the home directory, while `~/*` matches only its direct children.
diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/governance/reference/mcp-policy.md
similarity index 70%
rename from content/manuals/ai/sandboxes/governance/reference/mcp-policy.md
rename to content/manuals/ai/governance/reference/mcp-policy.md
index 2080e85a23..7c22325239 100644
--- a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md
+++ b/content/manuals/ai/governance/reference/mcp-policy.md
@@ -1,18 +1,25 @@
---
title: MCP policy reference
linkTitle: MCP policy
-weight: 20
+weight: 30
description: Reference for Docker MCP policy actions, resources, attributes, context fields, and approval behavior.
keywords: docker sandboxes, MCP policy, Cedar policy, MCP actions, MCP resources, requireApproval, AI Governance
+aliases:
+ - /ai/sandboxes/governance/reference/mcp-policy/
---
MCP policies are organization policies written in Cedar using Docker's `MCP`
namespace. This reference defines the Docker-specific policy surface for Model
Context Protocol (MCP) activity made available to sandboxes through Docker's
-[MCP gateway](../../mcp-gateway.md).
+[MCP gateway](../../sandboxes/mcp-gateway.md). MCP policy applies when a developer
+registers a server and when an agent uses the MCP gateway. Registration rules
+control future `sbx mcp add` operations. Use-time rules control tool calls,
+built-in gateway tools, resource reads, and prompt retrieval from servers that are
+already registered or loaded.
-Use this reference with [MCP access policies](../access-controls/mcp.md) for
-common policy patterns. For the Cedar language, see the
+Use this reference with
+[Organization MCP access policies](../organization/policies/mcp.md) for common
+policy patterns. For the Cedar language, see the
[Cedar documentation](https://docs.cedarpolicy.com/).
## Evaluation model
@@ -28,7 +35,7 @@ Governed MCP activity is default deny. A request is blocked unless a matching
permit annotated with `@requireApproval`.
For details about when Docker Sandboxes evaluates MCP policies for a user, see
-[Govern the server lifecycle](../access-controls/mcp.md#govern-the-server-lifecycle).
+[Where MCP policy applies](../organization/policies/mcp.md#where-mcp-policy-applies).
An actionless `permit` matches every MCP action that reaches Cedar evaluation:
@@ -38,28 +45,28 @@ permit (principal, action, resource);
## Actions
-| Action | Governs | Notes |
-| ------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `register` | MCP server registration | Server registration needs an explicit `permit`. Use server attributes to scope registration. |
-| `invokeTool` | MCP tool calls | Most tool access policies target this action. |
-| `invokePrimordial` | Gateway meta-tool calls | Applies to built-in gateway tools such as `mcp-exec`, `mcp-add`, `code-mode`, and OAuth authorization helpers. |
-| `readResource` | MCP resource reads | Rules match `MCP::Resource` and `resource.uri`. |
-| `getPrompt` | MCP prompt retrieval | Rules match `MCP::Prompt` and `resource.name`. |
-| `listTools` | MCP tool listing | Defined in the schema but not Cedar-gated. Tool listings can include tools denied at invocation. |
-| `listResources` | MCP resource listing | Defined in the schema but not Cedar-gated. Resource listings can include resources denied by policy. |
-| `subscribeResource` | MCP resource subscription | Defined in the schema but not Cedar-gated. |
+| Action | Governs | Notes |
+| ------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `register` | MCP server registration | Server registration needs an explicit `permit`. Use server attributes to scope registration. |
+| `invokeTool` | MCP tool calls | Most tool access policies target this action. |
+| `invokePrimordial` | Built-in gateway tool calls | Applies to built-in gateway tools such as `mcp-exec`, `mcp-add`, `code-mode`, and OAuth authorization helpers. |
+| `readResource` | MCP resource reads | Rules match `MCP::Resource` and `resource.uri`. |
+| `getPrompt` | MCP prompt retrieval | Rules match `MCP::Prompt` and `resource.name`. |
+| `listTools` | MCP tool listing | Defined in the schema but not Cedar-gated. Tool listings can include tools denied at invocation. |
+| `listResources` | MCP resource listing | Defined in the schema but not Cedar-gated. Resource listings can include resources denied by policy. |
+| `subscribeResource` | MCP resource subscription | Defined in the schema but not Cedar-gated. |
## Resources
Match resources with the MCP entity type and attributes for the request.
-| Entity | Match with | Notes |
-| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `MCP::Server` | Registered server name | The canonical server identity is the `resource.identityURL` attribute, not the entity ID. |
-| `MCP::Tool` | Bare tool name | Use `resource.name`. Display prefixes aren't included. A bare-name match applies to every server exposing a tool with that name. |
-| `MCP::Resource` | Resource URI | Use `resource.uri`. |
-| `MCP::Prompt` | Prompt name | Use `resource.name`. |
-| `MCP::Primordial` | Gateway meta-tool name | Match a specific primordial with an entity reference. |
+| Entity | Match with | Notes |
+| ----------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `MCP::Server` | Registered server name | The canonical server identity is the `resource.identityURL` attribute, not the entity ID. |
+| `MCP::Tool` | Bare tool name | Use `resource.name`. Display prefixes aren't included. A bare-name match applies to every server exposing a tool with that name. |
+| `MCP::Resource` | Resource URI | Use `resource.uri`. |
+| `MCP::Prompt` | Prompt name | Use `resource.name`. |
+| `MCP::Primordial` | Built-in gateway tool name | Match a specific built-in gateway tool with an entity reference. |
Examples:
@@ -83,8 +90,8 @@ and are advisory.
| `resource.destructive` | Tools | Defaults to `true` when a tool doesn't declare it. |
| `resource.idempotent` | Tools | Defaults to `false` when a tool doesn't declare it. |
| `resource.openWorld` | Tools | Defaults to `true` when a tool doesn't declare it. |
-| `resource.type` | Servers | Use for server registration rules. See [Server type values](#server-type-values). |
-| `resource.identityURL` | Servers | Canonical server identity. The value depends on the registration type. See [Server identity values](#server-identity-values). |
+| `resource.type` | Servers | Use for server registration rules. For more details, see [Server type values](#server-type-values). |
+| `resource.identityURL` | Servers | Canonical server identity. The value depends on the registration type. For more details, see [Server identity values](#server-identity-values). |
| `resource.requiresOAuth` | Servers | Use for server registration rules. |
| `resource.requiresNetwork` | Servers | Use for server registration rules. |
| `resource.command` | Servers | Local stdio server command, such as `npx` or `docker`, when available. Empty for remote servers and registrations that don't include command details. |
@@ -99,12 +106,12 @@ attributes, use `like`.
### Server type values
-Local gateway registrations use these values:
+Registrations through the MCP gateway use these values:
- `local-stdio`: a host-run stdio server. This includes explicit commands and
OCI-packaged stdio servers resolved from metadata with `--local`.
- `container-stdio`: an OCI-packaged server resolved from metadata without
- `--local`. This value can appear in `register` decisions, but the local
+ `--local`. This value can appear in `register` decisions, but the MCP
gateway can't attach or run this server type.
- `remote-dcr`: a remote endpoint that doesn't require OAuth or supports OAuth
Dynamic Client Registration.
@@ -165,7 +172,7 @@ over a normal `permit`. A matching `forbid` denies the request without an
elicitation.
For the request flow and trust model, see
-[Require confirmation with MCP elicitation](../access-controls/mcp.md#require-confirmation-with-mcp-elicitation).
+[Require confirmation with MCP elicitation](../organization/policies/mcp.md#require-confirmation-with-mcp-elicitation).
Approval requires a client session that can present an MCP elicitation request
to the user. If the request can't be presented for approval, the request is
@@ -187,7 +194,7 @@ don't require approval.
- Approval-gated requests are denied when the execution context can't relay an
MCP elicitation to the originating client. This includes tool calls made from
inside `code-mode`.
-- Registration policy is evaluated when a server is registered. It doesn't
+- Registration rules are evaluated when a server is registered. They don't
remove existing registrations or stop an already-loaded server by itself.
Govern existing registrations with use-time rules such as `invokeTool`,
`readResource`, and `getPrompt`.
diff --git a/content/manuals/ai/governance/reference/network-rules.md b/content/manuals/ai/governance/reference/network-rules.md
new file mode 100644
index 0000000000..5d26fbfde8
--- /dev/null
+++ b/content/manuals/ai/governance/reference/network-rules.md
@@ -0,0 +1,119 @@
+---
+title: Network and HTTP rule syntax
+linkTitle: Network rules
+weight: 10
+description: Syntax for sandbox network rules, including hostname patterns, CIDR ranges, ports, and HTTP method and path rules.
+keywords: docker sandboxes, network rules, rule syntax, wildcards, CIDR, HTTP rules, method and path
+---
+
+A network rule matches a destination. There are two kinds:
+
+- A host rule names no method or path, so it matches all traffic to the
+ destination. The Docker Home composer calls it an **All traffic** rule.
+- An HTTP rule also names an HTTP method and URL path, with optional
+ query-parameter restrictions, so a policy can allow selected API requests.
+
+For how to write destinations, see [Destinations](#destinations).
+
+## HTTP method and path
+
+An HTTP rule names one or more methods, a destination, and path patterns. What
+each part accepts depends on where you configure the rule:
+
+| Part | Organization policy | Local policy |
+| ----------- | ------------------------------------------ | --------------------------------- |
+| Method | One or more listed methods | `ANY`, or one or more methods |
+| Destination | A host or IP address | A host |
+| Path | One or more absolute path patterns | One absolute path pattern |
+
+A destination can include a port, and a path pattern looks like `/api/**`.
+
+A local HTTP rule accepts only a host pattern, not an IP address or a CIDR
+range. To match an IP address or a CIDR range, use a network rule without
+`--method` or `--path`. A local HTTP rule also takes one path, so add a separate
+rule for each path.
+
+Every rule applies to at least one method. On the CLI, `--method ANY` covers
+every HTTP method. In the composer, select at least one method. A rule with no
+methods selected fails validation. For the methods you can select individually,
+see
+[What a network rule can match](../organization/policies/network.md#what-a-network-rule-can-match)
+for an organization policy and
+[Allow or block HTTP methods and paths](../local/network-rules.md#allow-or-block-http-methods-and-paths)
+for a local one.
+
+Path patterns follow the same wildcard rules as filesystem paths, where `*`
+matches within one path segment and `**` matches any depth. A pattern without a
+wildcard matches that path exactly, so `/repos` matches `/repos` and nothing
+below it. Every pattern must start with `/` and can't contain a query string, a
+fragment, or a `..` segment. A local rule's path must also be canonical, so it
+can't contain percent-encoding, control characters, surrounding whitespace,
+repeated or trailing slashes, or a `.` segment.
+
+### Query parameters
+
+An HTTP rule can also restrict query parameters independently of the path.
+
+Use exact parameter names and values, or a single `*` at the start or end of a
+value to match a suffix or prefix. A value of `*` matches any value, including
+an empty one. Names cannot contain wildcards. Names and values are
+case-sensitive.
+
+For rules created with `--query`, every specified parameter must match.
+Parameter order doesn't matter, and requests may include additional
+parameters. Repeating a parameter name in the rule requires separate matching
+occurrences in the request. A rule without query restrictions matches
+regardless of query parameters.
+
+Write names and value patterns using URL query encoding: `+` or `%20` for a
+space, `%2B` for a literal plus, and `%2A` for a literal asterisk. Keep query
+parameters out of `--path`. For CLI examples, see
+[Allow or block HTTP methods and paths](../local/network-rules.md#allow-or-block-http-methods-and-paths).
+
+### Combine HTTP and host rules
+
+HTTP requests are evaluated against both kinds of rule. A host rule sets the
+baseline for a host, and HTTP rules narrow access by method, path, and query
+parameters:
+
+| Rules that cover the host | Result for an HTTP request |
+| ------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Host allow only | Allowed at any method and path |
+| HTTP allow only | Allowed only where a rule matches the method, path, and any query restrictions. Anything else is denied |
+| Host allow and HTTP deny | Requests matching the HTTP deny are blocked. The rest stay allowed |
+| Host deny | Blocked. An HTTP allow can't reopen a denied host |
+
+A host deny is therefore a floor that HTTP rules can't raise, while a host
+allow is a ceiling that HTTP rules can carve into.
+
+When a rule requires an HTTP decision, the sandbox HTTP proxy
+evaluates each request separately instead of deciding once per connection.
+
+Those requests have to go through the proxy. A connection it can't inspect,
+such as one it handles transparently, is blocked rather than evaluated.
+Traffic that isn't HTTP, such as SSH, carries no method or path, so HTTP rules
+never match it. Control those destinations with host rules.
+
+## Destinations
+
+Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are
+hostnames, CIDR ranges, or ports. UDP requires
+[experimental outbound UDP](../local/network-rules.md#allow-outbound-udp).
+ICMP is blocked.
+
+### Hostname patterns
+
+| Pattern | Example | Matches |
+| --------------------- | ----------------- | ------------------------------------------------------------- |
+| Exact hostname | `example.com` | `example.com` on any port, not subdomains |
+| Single-level wildcard | `*.example.com` | One subdomain level, any port: `api.example.com` |
+| Multi-level wildcard | `**.example.com` | Any depth, any port: `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`.
diff --git a/content/manuals/ai/governance/reference/policy-limits.md b/content/manuals/ai/governance/reference/policy-limits.md
new file mode 100644
index 0000000000..78de68a935
--- /dev/null
+++ b/content/manuals/ai/governance/reference/policy-limits.md
@@ -0,0 +1,32 @@
+---
+title: Organization policy limits
+linkTitle: Policy limits
+weight: 35
+description: Limits on the number and size of Docker Sandboxes organization policies and their rules.
+keywords: docker sandboxes, organization policy, policy limits, rules per policy, AI Governance
+---
+
+Organization policies have the following limits, which help ensure fair usage
+and resource availability across organizations:
+
+| Limit | Value | Applies to |
+|---------------------------|--------|-------------------------------------------------------------------------------|
+| Policies per organization | 100 | All organization policies combined, whatever their type |
+| Rules per policy | 250 | Each network or filesystem policy. MCP policies don't have a rule limit. |
+| Policy size | 400 KB | Each policy, whatever its type |
+
+The policies per organization limit is one shared total, not a separate
+allowance for each policy type. For example, an organization with 60 network
+policies, 30 filesystem policies, and 10 MCP policies has reached the limit.
+
+The policy size limit applies to each policy as Docker stores it. This
+includes the policy's content, such as its name, description, scope, and
+rules or Cedar statements, plus a small amount of metadata that Docker stores
+with every policy. Typical policies use only a small fraction of this limit.
+Domain and file path values have no separate length limit beyond valid format.
+Because MCP policies have no rule limit, the policy size limit is what caps how
+many Cedar statements an MCP policy can hold.
+
+If these limits don't fit your organization's needs,
+[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales)
+to discuss options.
diff --git a/content/manuals/ai/governance/troubleshooting.md b/content/manuals/ai/governance/troubleshooting.md
new file mode 100644
index 0000000000..8cc6ec16a1
--- /dev/null
+++ b/content/manuals/ai/governance/troubleshooting.md
@@ -0,0 +1,156 @@
+---
+title: Troubleshoot governance
+linkTitle: Troubleshooting
+weight: 40
+description: Resolve blocked requests, inactive rules, approval prompts, policy sync, and missing audit records for Docker Sandboxes governance.
+keywords: docker sandboxes, governance, troubleshooting, network policy, sbx policy, approval, organization policy, audit logs
+---
+
+These problems come from the governance rules that control what sandboxes can
+reach and mount, and from the audit logs that record those decisions. For other
+Docker Sandboxes problems, see
+[Troubleshooting](../sandboxes/troubleshooting.md).
+
+## A command fails with "global network policy has not been initialized"
+
+No network preset is set, and the CLI can't prompt you to choose one because
+it isn't running in an interactive terminal, for example in a CI pipeline or a
+script. Commands that work with sandboxes, such as `sbx run`, `sbx create`, and
+`sbx exec`, return this error until a preset is set. Set the preset first:
+
+```console
+$ sbx policy init balanced
+```
+
+Available values are `allow-all` (Open), `balanced` (Balanced), and `deny-all`
+(Locked Down). For more details, see
+[Set the preset without the prompt](local/network-rules.md#set-the-preset-without-the-prompt).
+
+## Agent can't install packages or reach an API
+
+Docker Sandboxes uses [network rules](local/network-rules.md) to control
+outbound traffic. If the agent fails to install packages or call an external
+API, the destination probably isn't allowed. Check which requests are being
+blocked:
+
+```console
+$ sbx policy log
+```
+
+Then allow the destinations your workflow needs:
+
+```console
+$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org"
+```
+
+To allow all outbound traffic instead:
+
+```console
+$ sbx policy allow network "**"
+```
+
+If `sbx policy allow` doesn't unblock the request, see
+[A local allow rule has no effect](#a-local-allow-rule-has-no-effect).
+
+## Every request from a sandbox is blocked
+
+When policy enforcement can't get a valid organization policy, it fails closed
+and blocks every network request and workspace mount, whatever your rules
+allow. The message a blocked request returns tells you why:
+
+- `Denied because governance could not be resolved`: run `sbx policy ls`. If
+ the status line shows `Governance: Unresolved`, see
+ [`sbx policy ls` shows Governance: Unresolved](#sbx-policy-ls-shows-governance-unresolved).
+- `Denied because the policy snapshot is stale`: the daemon lost its connection
+ to the governance service, or your Docker session expired. Check your network
+ connection, then run `sbx login` to sign in again if the problem continues.
+
+## A local allow rule has no effect
+
+If a destination is still blocked after you add a local allow rule, an
+organization policy is probably enforced for you. Run `sbx policy ls` and check
+for `Governance: Managed by ` in the status line. When an organization
+policy is enforced, local allow rules are inactive and can't loosen what the
+organization policy allows.
+
+To confirm, run `sbx policy ls --wide --include-inactive` and check that your
+rule shows `inactive` in the `STATUS` column.
+
+Ask your administrator to update the organization policy if you need access to
+another destination. 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).
+
+## `sbx policy ls` shows Governance: Unresolved
+
+Docker can't determine which organization governs your account. For example,
+this happens when your account belongs to more than one organization with
+governance enabled. A `Details` line below the status explains the cause.
+
+Policy enforcement fails closed until the conflict is resolved, so local allow
+rules can't grant access. Contact an administrator for the affected
+organizations to resolve the conflicting governance configuration.
+
+## A request is blocked with "Approval required"
+
+The destination needs your confirmation. Either no allow or deny rule matches
+it and no organization policy is enforced for you, or an organization policy
+allows it but requires approval first.
+
+Run `sbx policy approval ls` to see the pending request and respond to it with
+`sbx policy approval respond`. Approving applies to later requests, not the one
+that was blocked, so run the operation again afterward. For more details, see
+[Respond to approval requests](local/approvals.md).
+
+## An HTTP method or path is blocked on an allowed host
+
+A destination that a host rule allows can still have individual methods or
+paths denied by an HTTP rule. Run `sbx policy ls --type http` to see which HTTP rules
+apply. `sbx policy check network` reports the decision for the host only, so it
+shows a host as allowed even when the specific request is denied. For more
+details, see
+[Allow or block HTTP methods and paths](local/network-rules.md#allow-or-block-http-methods-and-paths).
+
+## A sandbox can't mount its workspace
+
+If a sandbox fails to mount with a `mount policy denied` error, an organization
+filesystem policy doesn't allow the path. Check that the filesystem allow rule
+uses `**` rather than `*`. A single `*` doesn't match across directory
+separators. For more details, see
+[Organization filesystem access policies](organization/policies/filesystem.md).
+
+## Organization policy changes aren't taking effect
+
+After an administrator updates organization policies, changes take up to 5
+minutes to reach developer machines. To apply them right away on a developer
+machine, run `sbx policy refresh`. It fetches and applies the latest
+organization policy without restarting the daemon or stopping running
+sandboxes.
+
+The refreshed policy applies to new connections only. A connection that a
+sandbox opened while the previous policy allowed it stays open even if the new
+policy denies it. Restart the sandbox to close those connections.
+
+When a synced change takes effect also depends on the policy type. For more
+details, see
+[When policy changes reach developers](organization/policies/_index.md#when-policy-changes-reach-developers).
+
+## Audit records are missing
+
+If an organization's audit logs don't include records from a developer, check
+the following:
+
+- The developer is governed. Records come only from signed-in users who have an
+ AI Governance license and are governed by an enforced organization policy. On
+ the developer's machine, run `sbx policy ls` and check for
+ `Governance: Managed by ` in the status line.
+- The developer runs Docker Sandboxes 0.39.0 or later. Run `sbx version` to
+ check, and [install](../sandboxes/install.md) a newer version if needed.
+- Cloud delivery is on. Records reach audit events in Docker Home and SIEM
+ streaming only through cloud delivery. Organizations that used local audit
+ logging before hosted audit logs were available start with cloud delivery
+ off. For more details, see
+ [Configure audit delivery](organization/audit/configure.md).
+- Local files are finalized. With local delivery, the daemon writes records to
+ a `.tmp` file and renames it to `.jsonl` after 5 minutes, 1000 events, or 50
+ MiB, or when the daemon shuts down cleanly. For more details, see
+ [Where records are stored](organization/audit/_index.md#where-records-are-stored).
diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md
index ecb9d47278..12e827f4a4 100644
--- a/content/manuals/ai/sandboxes/_index.md
+++ b/content/manuals/ai/sandboxes/_index.md
@@ -18,7 +18,7 @@ work. Cloud compute uses a
Model-provider charges are separate.
Organization admins can
-[centrally manage sandbox network, filesystem, and MCP policies](governance/access-controls/organization.md),
+[centrally manage sandbox network, filesystem, and MCP policies](../governance/organization/_index.md),
for local sandboxes across developer machines.
Available on a separate paid subscription.
diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md
index 5e9be8737b..b0fbbb904b 100644
--- a/content/manuals/ai/sandboxes/architecture.md
+++ b/content/manuals/ai/sandboxes/architecture.md
@@ -77,8 +77,9 @@ $ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run
All outbound TCP traffic from the sandbox routes through a proxy on your host.
Agents use a forward proxy for HTTP and HTTPS; other TCP traffic is forwarded
-transparently. Both paths enforce
-[network access policies](governance/access-controls/network.md). The forward
+transparently. Both paths enforce network policy, the rules that decide which
+destinations a sandbox can reach. For how those rules are set, see
+[Sandbox governance](../governance/_index.md). The forward
proxy also handles [credential injection](configuration/credentials.md). See
[Network isolation](security/isolation.md#network-isolation) for how this
works and [Default security posture](security/defaults.md) for what is
diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md
index 4acbf1a1c7..d98bb8050e 100644
--- a/content/manuals/ai/sandboxes/configuration/credentials.md
+++ b/content/manuals/ai/sandboxes/configuration/credentials.md
@@ -465,9 +465,10 @@ $ sbx secret set-custom \
```
A `--host` value can also use wildcards, with the same syntax as
-[network rules](../governance/concepts.md#network-rules): `*` matches a
-single label (`*.example.com` covers `api.example.com`) and `**` matches any
-number (`**.example.com` covers `api.example.com` and `v2.api.example.com`).
+[network rule hostname patterns](../../governance/reference/network-rules.md#hostname-patterns):
+`*` matches a single label (`*.example.com` covers `api.example.com`) and `**`
+matches any number (`**.example.com` covers `api.example.com` and
+`v2.api.example.com`).
### Resolve custom secrets dynamically
diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md
index 6d57bd5256..73999f98e3 100644
--- a/content/manuals/ai/sandboxes/configuration/settings.md
+++ b/content/manuals/ai/sandboxes/configuration/settings.md
@@ -628,7 +628,8 @@ $ sbx daemon restart
This shared list applies to sandbox and daemon traffic unless a scope-specific
list replaces it. A value of `*` bypasses the upstream proxy for all destinations.
Proxy exclusions don't grant network access: sandbox requests must still pass
-[network policy](../governance/access-controls/network.md).
+network policy. For how network policy is set, see
+[Sandbox governance](../../governance/_index.md).
#### no_proxy.sandbox {.wrap-anywhere}
diff --git a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md
index 93514fe688..3f2512d86e 100644
--- a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md
+++ b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md
@@ -22,9 +22,9 @@ originating inside a cloud sandbox. For cloud sandbox egress controls, see
An upstream proxy is the corporate or network proxy that Docker Sandboxes
forwards outbound traffic through on its way to the internet. This is separate
-from the [network policy](../governance/access-controls/network.md), which decides
-_which_ destinations are allowed. The upstream proxy decides _how_ allowed
-traffic reaches them.
+from network policy, which decides _which_ destinations are allowed. The
+upstream proxy decides _how_ allowed traffic reaches them. For how network
+policy is set, see [Sandbox governance](../../governance/_index.md).
Docker Sandboxes sends two kinds of outbound traffic, and you can proxy them
independently:
diff --git a/content/manuals/ai/sandboxes/customize/author/_index.md b/content/manuals/ai/sandboxes/customize/author/_index.md
index 525d4c915b..b9a4204a66 100644
--- a/content/manuals/ai/sandboxes/customize/author/_index.md
+++ b/content/manuals/ai/sandboxes/customize/author/_index.md
@@ -29,6 +29,9 @@ each approach.
- [Build an agent workload](/manuals/ai/sandboxes/customize/author/build-an-agent.md)
to control the base environment, agent installation, and launch command.
You can also [use an existing agent image](/manuals/ai/sandboxes/customize/author/base-images.md#use-an-image-in-a-v3-workload).
+- [Debug a kit](/manuals/ai/sandboxes/customize/author/debug.md) when one of its
+ install or startup commands fails. Read the progress output and the logs
+ inside the sandbox.
For complete kits you can study and adapt, see
[Kit examples](https://github.com/docker/sandbox-kit-spec/tree/main/examples)
diff --git a/content/manuals/ai/sandboxes/customize/author/debug.md b/content/manuals/ai/sandboxes/customize/author/debug.md
new file mode 100644
index 0000000000..847fa63f14
--- /dev/null
+++ b/content/manuals/ai/sandboxes/customize/author/debug.md
@@ -0,0 +1,169 @@
+---
+title: Debug a kit
+linkTitle: Debug a kit
+description: Read the setup progress output, find install and startup logs inside the sandbox, and fix a kit whose install or startup command fails.
+keywords: sandboxes, sbx, kits, debug, troubleshooting, install, startup, logs
+weight: 36
+---
+
+{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
+
+When a kit's install or startup command fails, `sbx` shows you which command
+failed, in which kit, and where the full output is. This page shows how to read
+that output, find the logs inside the sandbox, and fix the common causes.
+
+## Read the progress output
+
+During `sbx create` and `sbx run`, the configure agent phase prints one row for
+each kit operation: install commands, init files, file copies, environment
+variables, and the startup commands it registers. A finished row shows ✓ with
+the elapsed time, or ✗ with the exit code.
+
+Each command row shows the command's `description` when the kit sets one.
+Otherwise it shows the first 60 characters of the command. It also shows the
+kit that owns the command (`kit=`) and the user it runs as (`user=`).
+
+Set `description` on every install and startup command so the row says what the
+command is for. Keep it short: a row shows at most 60 characters of it.
+
+```yaml {title="my-kit/my-kit.yaml"}
+capabilities:
+ - type: com.docker.sandbox/lifecycle@1
+ config:
+ install:
+ - command: apt-get update && apt-get install -y ripgrep
+ user: "0"
+ description: Install ripgrep
+ startup:
+ - command: rg --version > /tmp/rg-version
+ description: Record the ripgrep version
+```
+
+The rows for this kit look like this:
+
+```text
+AGENT
+ running 1 install command
+ ✓ Install ripgrep (kit=my-kit, user=0, 12.4s)
+ view install logs: ls /var/log/sbx-kits
+ registering 1 startup command, run on every container start
+ ○ Record the ripgrep version (kit=my-kit, user=agent)
+ view startup log: cat /var/log/sbx-kit-startup.log
+```
+
+## Read a failed install command
+
+A failed install command prints the last 40 lines of its output under the row,
+followed by a `docker run` line that runs the same command against the kit's
+base image:
+
+```text
+ ✗ Install ripgrep (kit=my-kit, user=0, exit 100)
+ ── captured output ──
+ E: Failed to fetch http://deb.debian.org/debian/dists/bookworm/InRelease 403 Forbidden
+ E: Unable to locate package ripgrep
+ ──────────────────────
+ hint: reproduce locally with:
+ docker run --rm -u 0 sh -c 'apt-get update && apt-get install -y ripgrep'
+```
+
+Copy the `docker run` line to iterate on the command without recreating the
+sandbox each time. Change the command, run it again, and copy the working
+version back into the kit. The reproduction runs in plain Docker, outside the sandbox, so the sandbox's
+network policy doesn't apply. If the command works there but fails in the
+sandbox, check the kit's network rules first.
+
+## Find the logs inside the sandbox
+
+The progress output shows only the end of a failed command. The sandbox keeps
+the full record:
+
+| Log | Contents |
+| --- | --- |
+| `/var/log/sbx-kits//install-.log` | Full output of one install command. `` is the command's position in that kit's `install` list, starting at 0. |
+| `/var/log/sbx-kit-startup.log` | Output of every startup command, from every container start. |
+
+Read either log with `sbx exec`:
+
+```console
+$ sbx exec my-sandbox cat /var/log/sbx-kits/my-kit/install-0.log
+$ sbx exec my-sandbox cat /var/log/sbx-kit-startup.log
+```
+
+Startup commands run on every container start. Each one writes these lines to
+the startup log:
+
+```text
+>