update sandbox cli ref (#24042)

- **sandboxes: regenerate, vendor cli reference docs**
- **chore: move `docker sandbox create` to a section page**

---------

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

data/sandbox-cli/docker_sandbox_create.yaml

@@ -11,12 +11,14 @@ cname:
     - docker sandbox create cagent
     - docker sandbox create claude
     - docker sandbox create codex
+    - docker sandbox create copilot
     - docker sandbox create gemini
     - docker sandbox create kiro
 clink:
     - docker_sandbox_create_cagent.yaml
     - docker_sandbox_create_claude.yaml
     - docker_sandbox_create_codex.yaml
+    - docker_sandbox_create_copilot.yaml
     - docker_sandbox_create_gemini.yaml
     - docker_sandbox_create_kiro.yaml
 options:
@@ -25,6 +27,7 @@ options:
       default_value: "false"
       description: |
         Load a locally built template image into the sandbox (useful for testing local changes)
+      details_url: '#load-local-template'
       deprecated: false
       hidden: false
       experimental: false
@@ -57,6 +60,7 @@ options:
       value_type: string
       description: |
         Container image to use for the sandbox (default: agent-specific image)
+      details_url: '#template'
       deprecated: false
       hidden: false
       experimental: false
@@ -85,6 +89,57 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Create a Claude sandbox
+
+    ```console
+    $ docker sandbox create claude ~/my-project
+    ```
+
+    ### Create with a custom name
+
+    ```console
+    $ docker sandbox create --name my-sandbox claude ~/my-project
+    ```
+
+    ### Use a custom base image (-t, --template) {#template}
+
+    ```text
+    --template IMAGE
+    ```
+
+    Specify a custom container image to use as the sandbox base:
+
+    ```console
+    $ docker sandbox create --template python:3-alpine claude ~/my-project
+    ```
+
+    By default, each agent uses a pre-configured image.
+
+    ### Use locally built template (--load-local-template) {#load-local-template}
+
+    Load a locally built template image for testing:
+
+    ```console
+    $ docker sandbox create --load-local-template claude ~/my-project
+    ```
+
+    This is useful when developing or testing changes to sandbox templates.
+
+    ### Create and run immediately
+
+    After creating a sandbox, use `run` to start the agent:
+
+    ```console
+    $ docker sandbox create --name my-sandbox claude ~/my-project
+    $ docker sandbox run my-sandbox
+    ```
+
+    Or use `docker sandbox run` directly to create and run in one step:
+
+    ```console
+    $ docker sandbox run claude ~/my-project
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_create_cagent.yaml

@@ -31,6 +31,25 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Create a Cagent sandbox in the current directory
+
+    ```console
+    $ docker sandbox create cagent .
+    ```
+
+    ### Create with an absolute path
+
+    ```console
+    $ docker sandbox create cagent /home/user/my-project
+    ```
+
+    ### Create and then run
+
+    ```console
+    $ docker sandbox create --name my-cagent cagent ~/my-project
+    $ docker sandbox run my-cagent
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_create_claude.yaml

@@ -42,6 +42,25 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Create a Claude sandbox in the current directory
+
+    ```console
+    $ docker sandbox create claude .
+    ```
+
+    ### Create with an absolute path
+
+    ```console
+    $ docker sandbox create claude /home/user/my-project
+    ```
+
+    ### Create and then run
+
+    ```console
+    $ docker sandbox create --name my-claude claude ~/my-project
+    $ docker sandbox run my-claude
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_create_codex.yaml

@@ -31,6 +31,25 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Create a Codex sandbox in the current directory
+
+    ```console
+    $ docker sandbox create codex .
+    ```
+
+    ### Create with an absolute path
+
+    ```console
+    $ docker sandbox create codex /home/user/my-project
+    ```
+
+    ### Create and then run
+
+    ```console
+    $ docker sandbox create --name my-codex codex ~/my-project
+    $ docker sandbox run my-codex
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_create_gemini.yaml

@@ -31,6 +31,25 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Create a Gemini sandbox in the current directory
+
+    ```console
+    $ docker sandbox create gemini .
+    ```
+
+    ### Create with an absolute path
+
+    ```console
+    $ docker sandbox create gemini /home/user/my-project
+    ```
+
+    ### Create and then run
+
+    ```console
+    $ docker sandbox create --name my-gemini gemini ~/my-project
+    $ docker sandbox run my-gemini
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_create_kiro.yaml

@@ -31,6 +31,25 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Create a Kiro sandbox in the current directory
+
+    ```console
+    $ docker sandbox create kiro .
+    ```
+
+    ### Create with an absolute path
+
+    ```console
+    $ docker sandbox create kiro /home/user/my-project
+    ```
+
+    ### Create and then run
+
+    ```console
+    $ docker sandbox create --name my-kiro kiro ~/my-project
+    $ docker sandbox run my-kiro
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_exec.yaml

@@ -13,6 +13,7 @@ options:
       value_type: bool
       default_value: "false"
       description: 'Detached mode: run command in the background'
+      details_url: '#detach'
       deprecated: false
       hidden: false
       experimental: false
@@ -33,6 +34,7 @@ options:
       value_type: stringArray
       default_value: '[]'
       description: Set environment variables
+      details_url: '#env'
       deprecated: false
       hidden: false
       experimental: false
@@ -85,6 +87,7 @@ options:
       shorthand: u
       value_type: string
       description: 'Username or UID (format: <name|uid>[:<group|gid>])'
+      details_url: '#user'
       deprecated: false
       hidden: false
       experimental: false
@@ -95,6 +98,7 @@ options:
       shorthand: w
       value_type: string
       description: Working directory inside the container
+      details_url: '#workdir'
       deprecated: false
       hidden: false
       experimental: false
@@ -123,6 +127,65 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Execute a command in a sandbox
+
+    ```console
+    $ docker sandbox exec my-sandbox ls -la
+    ```
+
+    ### Run an interactive shell
+
+    ```console
+    $ docker sandbox exec -it my-sandbox /bin/bash
+    ```
+
+    ### Set environment variables (-e, --env) {#env}
+
+    ```text
+    --env KEY=VALUE
+    ```
+
+    Pass environment variables to the command:
+
+    ```console
+    $ docker sandbox exec \
+      --env NODE_ENV=development \
+      --env DATABASE_URL=postgresql://localhost/myapp \
+      my-sandbox npm test
+    ```
+
+    ### Set working directory (-w, --workdir) {#workdir}
+
+    ```text
+    --workdir PATH
+    ```
+
+    Run the command in a specific directory:
+
+    ```console
+    $ docker sandbox exec --workdir /app my-sandbox python script.py
+    ```
+
+    ### Run as specific user (-u, --user) {#user}
+
+    ```text
+    --user USER[:GROUP]
+    ```
+
+    Execute command as a different user:
+
+    ```console
+    $ docker sandbox exec --user 1000:1000 my-sandbox id
+    ```
+
+    ### Run in background (-d, --detach) {#detach}
+
+    Run a long-running command in the background:
+
+    ```console
+    $ docker sandbox exec -d my-sandbox python server.py
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_network.yaml

@@ -32,6 +32,22 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### View network logs
+
+    ```console
+    $ docker sandbox network log
+    ```
+
+    ### Configure proxy for a sandbox
+
+    ```console
+    $ docker sandbox network proxy my-sandbox --block-host example.com
+    ```
+
+    See the subcommands for more details:
+    - [`docker sandbox network log`](/reference/cli/docker/sandbox/network/log/) - Show network logs
+    - [`docker sandbox network proxy`](/reference/cli/docker/sandbox/network/proxy/) - Manage proxy configuration
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_network_log.yaml

@@ -9,6 +9,7 @@ options:
       value_type: bool
       default_value: "false"
       description: Output in JSON format
+      details_url: '#json'
       deprecated: false
       hidden: false
       experimental: false
@@ -19,6 +20,7 @@ options:
       value_type: int
       default_value: "0"
       description: Maximum number of log entries to show
+      details_url: '#limit'
       deprecated: false
       hidden: false
       experimental: false
@@ -30,6 +32,7 @@ options:
       value_type: bool
       default_value: "false"
       description: Only display log entries
+      details_url: '#quiet'
       deprecated: false
       hidden: false
       experimental: false
@@ -58,6 +61,61 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Show network logs
+
+    ```console
+    $ docker sandbox network log
+    2026-01-29T10:15:23Z sandbox=my-sandbox request GET https://api.example.com/data allowed
+    2026-01-29T10:15:24Z sandbox=my-sandbox request POST https://api.example.com/submit allowed
+    2026-01-29T10:15:25Z sandbox=my-sandbox request GET https://blocked.example.com/ denied
+    ```
+
+    ### Show only log entries (--quiet) {#quiet}
+
+    ```text
+    --quiet
+    ```
+
+    Suppress headers and only show log entries:
+
+    ```console
+    $ docker sandbox network log --quiet
+    2026-01-29T10:15:23Z sandbox=my-sandbox request GET https://api.example.com/data allowed
+    2026-01-29T10:15:24Z sandbox=my-sandbox request POST https://api.example.com/submit allowed
+    ```
+
+    ### Limit number of entries (--limit) {#limit}
+
+    ```text
+    --limit N
+    ```
+
+    Show only the last N log entries:
+
+    ```console
+    $ docker sandbox network log --limit 10
+    ```
+
+    ### JSON output (--json) {#json}
+
+    Output logs in JSON format for parsing:
+
+    ```console
+    $ docker sandbox network log --json
+    {
+      "entries": [
+        {
+          "timestamp": "2026-01-29T10:15:23Z",
+          "sandbox": "my-sandbox",
+          "type": "request",
+          "method": "GET",
+          "url": "https://api.example.com/data",
+          "action": "allowed"
+        }
+      ]
+    }
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_network_proxy.yaml

@@ -18,6 +18,7 @@ options:
     - option: allow-host
       value_type: string
       description: Permit access to a domain or IP (can be specified multiple times)
+      details_url: '#allow-host'
       deprecated: false
       hidden: false
       experimental: false
@@ -28,6 +29,7 @@ options:
       value_type: string
       description: |
         Block access to an IP range in CIDR notation (can be specified multiple times)
+      details_url: '#block-cidr'
       deprecated: false
       hidden: false
       experimental: false
@@ -47,6 +49,7 @@ options:
       value_type: string
       description: |
         Bypass proxy for an IP range in CIDR notation (can be specified multiple times)
+      details_url: '#bypass-cidr'
       deprecated: false
       hidden: false
       experimental: false
@@ -56,6 +59,7 @@ options:
     - option: bypass-host
       value_type: string
       description: Bypass proxy for a domain or IP (can be specified multiple times)
+      details_url: '#bypass-host'
       deprecated: false
       hidden: false
       experimental: false
@@ -65,6 +69,7 @@ options:
     - option: policy
       value_type: allow|deny
       description: Set the default policy
+      details_url: '#policy'
       deprecated: false
       hidden: false
       experimental: false
@@ -93,6 +98,99 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Block access to a domain
+
+    ```console
+    $ docker sandbox network proxy my-sandbox --block-host example.com
+    ```
+
+    ### Block multiple domains
+
+    ```console
+    $ docker sandbox network proxy my-sandbox \
+      --block-host example.com \
+      --block-host malicious.site
+    ```
+
+    ### Block IP range (--block-cidr) {#block-cidr}
+
+    ```text
+    --block-cidr CIDR
+    ```
+
+    Block access to an IP range in CIDR notation:
+
+    ```console
+    $ docker sandbox network proxy my-sandbox --block-cidr 192.168.1.0/24
+    ```
+
+    ### Allow specific domain (--allow-host) {#allow-host}
+
+    ```text
+    --allow-host DOMAIN
+    ```
+
+    Permit access to a domain (useful with deny-by-default policy):
+
+    ```console
+    $ docker sandbox network proxy my-sandbox \
+      --policy deny \
+      --allow-host api.trusted-service.com
+    ```
+
+    ### Bypass proxy for domain (--bypass-host) {#bypass-host}
+
+    ```text
+    --bypass-host DOMAIN
+    ```
+
+    Bypass proxy for specific domains:
+
+    ```console
+    $ docker sandbox network proxy my-sandbox --bypass-host localhost
+    ```
+
+    ### Bypass proxy for IP range (--bypass-cidr) {#bypass-cidr}
+
+    ```text
+    --bypass-cidr CIDR
+    ```
+
+    Bypass proxy for an IP range:
+
+    ```console
+    $ docker sandbox network proxy my-sandbox --bypass-cidr 127.0.0.0/8
+    ```
+
+    ### Set default policy (--policy) {#policy}
+
+    ```text
+    --policy allow|deny
+    ```
+
+    Set the default policy for network access:
+
+    ```console
+    # Allow by default, block specific hosts
+    $ docker sandbox network proxy my-sandbox \
+      --policy allow \
+      --block-host dangerous.example
+
+    # Deny by default, allow specific hosts
+    $ docker sandbox network proxy my-sandbox \
+      --policy deny \
+      --allow-host api.trusted.com \
+      --allow-host cdn.trusted.com
+    ```
+
+    ### Remove rules
+
+    Use `--allow-cidr` to remove IP ranges from block or bypass lists:
+
+    ```console
+    $ docker sandbox network proxy my-sandbox --allow-cidr 192.168.1.0/24
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_reset.yaml

@@ -24,6 +24,7 @@ options:
       value_type: bool
       default_value: "false"
       description: Skip confirmation prompt
+      details_url: '#force'
       deprecated: false
       hidden: false
       experimental: false
@@ -52,6 +53,28 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Reset with confirmation prompt
+
+    ```console
+    $ docker sandbox reset
+    ⚠️  WARNING: This will permanently delete all VM data and stop all running agents!
+    Are you sure you want to continue? (y/N): y
+    All VMs reset successfully
+    ```
+
+    ### Force reset without confirmation (-f, --force) {#force}
+
+    Skip the confirmation prompt:
+
+    ```console
+    $ docker sandbox reset --force
+    All VMs reset successfully
+    ```
+
+    > [!CAUTION]
+    > This is a destructive operation that cannot be undone!
+    > All running agents will be terminated and their work will be lost.
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_run.yaml

@@ -84,101 +84,67 @@ inherited_options:
       kubernetes: false
       swarm: false
 examples: |-
-    ### Run Claude in the current directory
+    ### Create and run Claude in the current directory
 
     ```console
-    $ docker sandbox run claude
+    $ docker sandbox run claude .
     ```
 
-    ### Specify a workspace directory (-w, --workspace) {#workspace}
-
-    ```text
-    --workspace PATH
-    ```
-
-    Run the agent in a specific directory:
+    ### Run an existing sandbox
 
     ```console
-    $ docker sandbox run --workspace ~/projects/my-app claude
+    $ docker sandbox run my-sandbox
+    ```
+
+    ### Create and run with a specific workspace
+
+    ```console
+    $ docker sandbox run claude ~/projects/my-app
     ```
 
     The workspace directory is mounted at the same absolute path inside the sandbox.
 
-    ### Enable Docker-in-Docker (--mount-docker-socket) {#mount-docker-socket}
-
-    ```text
-    --mount-docker-socket
-    ```
-
-    Mount the host's Docker socket into the sandbox, giving the agent access to Docker commands:
-
-    ```console
-    $ docker sandbox run --mount-docker-socket claude
-    ```
-
-    > [!CAUTION]
-    > This grants the agent full access to your Docker daemon with root-level
-    > privileges. Only use when you trust the code being executed.
-
-    The agent can now build images, run containers, and manage your Docker environment.
-
-    ### Set environment variables (-e, --env) {#env}
-
-    ```text
-    --env KEY=VALUE
-    ```
-
-    Pass environment variables to the sandbox:
-
-    ```console
-    $ docker sandbox run \
-      --env NODE_ENV=development \
-      --env DATABASE_URL=postgresql://localhost/myapp \
-      claude
-    ```
-
-    ### Mount additional volumes (-v, --volume) {#volume}
-
-    ```text
-    --volume HOST_PATH:CONTAINER_PATH[:ro]
-    ```
-
-    Mount additional directories or files into the sandbox:
-
-    ```console
-    $ docker sandbox run \
-      --volume ~/datasets:/data:ro \
-      --volume ~/models:/models \
-      claude
-    ```
-
-    Use `:ro` or `:readonly` to make mounts read-only.
-
-    ### Use a custom base image (-t, --template) {#template}
-
-    ```text
-    --template IMAGE
-    ```
-
-    Specify a custom container image to use as the sandbox base:
-
-    ```console
-    $ docker sandbox run --template python:3-alpine claude
-    ```
-
-    By default, each agent uses a pre-configured image. The `--template` option
-    lets you substitute a different image.
-
     ### Name the sandbox (--name) {#name}
 
     ```text
     --name NAME
     ```
 
-    Assign a custom name to the sandbox for easier identification:
+    Assign a custom name when creating a sandbox:
 
     ```console
-    $ docker sandbox run --name my-project claude
+    $ docker sandbox run --name my-project claude .
+    ```
+
+    ### Use a custom base image (-t, --template) {#template}
+
+    ```text
+    --template IMAGE
+    ```
+
+    Specify a custom container image when creating a sandbox:
+
+    ```console
+    $ docker sandbox run --template python:3-alpine claude .
+    ```
+
+    By default, each agent uses a pre-configured image. The `--template` option
+    lets you substitute a different image.
+
+    ### Pass arguments to the agent
+
+    Use `--` to separate sandbox options from agent arguments:
+
+    ```console
+    $ docker sandbox run claude . -- -p "What version are you running?"
+    ```
+
+    ### Run with locally built template
+
+    Use `--load-local-template` to test local template changes:
+
+    ```console
+    $ docker sandbox run --load-local-template claude .
     ```
 deprecated: false
 hidden: false

data/sandbox-cli/docker_sandbox_stop.yaml

@@ -27,6 +27,27 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Stop a sandbox
+
+    ```console
+    $ docker sandbox stop my-sandbox
+    my-sandbox
+    ```
+
+    ### Stop multiple sandboxes
+
+    ```console
+    $ docker sandbox stop sandbox1 sandbox2
+    sandbox1
+    sandbox2
+    ```
+
+    ### Stop all running sandboxes
+
+    ```console
+    $ docker sandbox stop $(docker sandbox ls -q)
+    ```
 deprecated: false
 hidden: false
 experimental: false

data/sandbox-cli/docker_sandbox_version.yaml

@@ -26,6 +26,13 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+examples: |-
+    ### Show version information
+
+    ```console
+    $ docker sandbox version
+    github.com/docker/sandboxes/cli-plugin v0.7.1 f00f0d6473647c2201cd0507ce31613345c48ae6
+    ```
 deprecated: false
 hidden: false
 experimental: false