diff --git a/content/reference/cli/docker/sandbox/create.md b/content/reference/cli/docker/sandbox/create/_index.md similarity index 100% rename from content/reference/cli/docker/sandbox/create.md rename to content/reference/cli/docker/sandbox/create/_index.md diff --git a/data/sandbox-cli/docker_sandbox_create.yaml b/data/sandbox-cli/docker_sandbox_create.yaml index ea3dbc0ed95e..c5722369f093 100644 --- a/data/sandbox-cli/docker_sandbox_create.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_create_cagent.yaml b/data/sandbox-cli/docker_sandbox_create_cagent.yaml index 6b9035b0fe05..146f1c3abb44 100644 --- a/data/sandbox-cli/docker_sandbox_create_cagent.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_create_claude.yaml b/data/sandbox-cli/docker_sandbox_create_claude.yaml index e1ecab4613b8..feefd7d80dc9 100644 --- a/data/sandbox-cli/docker_sandbox_create_claude.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_create_codex.yaml b/data/sandbox-cli/docker_sandbox_create_codex.yaml index b5ed8c460efe..df70fb07dcb8 100644 --- a/data/sandbox-cli/docker_sandbox_create_codex.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_create_gemini.yaml b/data/sandbox-cli/docker_sandbox_create_gemini.yaml index 6b7a0ec11916..7491928a4820 100644 --- a/data/sandbox-cli/docker_sandbox_create_gemini.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_create_kiro.yaml b/data/sandbox-cli/docker_sandbox_create_kiro.yaml index 0f3fbd29f440..1eac3307e530 100644 --- a/data/sandbox-cli/docker_sandbox_create_kiro.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_exec.yaml b/data/sandbox-cli/docker_sandbox_exec.yaml index 096918d4eb1e..8871866dd335 100644 --- a/data/sandbox-cli/docker_sandbox_exec.yaml +++ b/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: [:])' + 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 diff --git a/data/sandbox-cli/docker_sandbox_network.yaml b/data/sandbox-cli/docker_sandbox_network.yaml index 9d40fd65c9f8..ae2bbf15aecd 100644 --- a/data/sandbox-cli/docker_sandbox_network.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_network_log.yaml b/data/sandbox-cli/docker_sandbox_network_log.yaml index 36ad716f4714..3cc4f2947a71 100644 --- a/data/sandbox-cli/docker_sandbox_network_log.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_network_proxy.yaml b/data/sandbox-cli/docker_sandbox_network_proxy.yaml index 2e068aa8aa7d..8accbb6a7400 100644 --- a/data/sandbox-cli/docker_sandbox_network_proxy.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_reset.yaml b/data/sandbox-cli/docker_sandbox_reset.yaml index 41f438c6e94a..007204af9504 100644 --- a/data/sandbox-cli/docker_sandbox_reset.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_run.yaml b/data/sandbox-cli/docker_sandbox_run.yaml index 3e7eaefdbe4b..c5c0ee09bc0b 100644 --- a/data/sandbox-cli/docker_sandbox_run.yaml +++ b/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 ``` - 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: + ### Create and run with a specific workspace ```console - $ docker sandbox run --mount-docker-socket claude + $ docker sandbox run claude ~/projects/my-app ``` - > [!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 - ``` + The workspace directory is mounted at the same absolute path inside the sandbox. - ### Mount additional volumes (-v, --volume) {#volume} + ### Name the sandbox (--name) {#name} ```text - --volume HOST_PATH:CONTAINER_PATH[:ro] + --name NAME ``` - Mount additional directories or files into the sandbox: + Assign a custom name when creating a sandbox: ```console - $ docker sandbox run \ - --volume ~/datasets:/data:ro \ - --volume ~/models:/models \ - claude + $ docker sandbox run --name my-project 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: + Specify a custom container image when creating a sandbox: ```console - $ docker sandbox run --template python:3-alpine claude + $ 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} + ### Pass arguments to the agent - ```text - --name NAME + Use `--` to separate sandbox options from agent arguments: + + ```console + $ docker sandbox run claude . -- -p "What version are you running?" ``` - Assign a custom name to the sandbox for easier identification: + ### Run with locally built template + + Use `--load-local-template` to test local template changes: ```console - $ docker sandbox run --name my-project claude + $ docker sandbox run --load-local-template claude . ``` deprecated: false hidden: false diff --git a/data/sandbox-cli/docker_sandbox_stop.yaml b/data/sandbox-cli/docker_sandbox_stop.yaml index 97551892c3a2..516286d6258d 100644 --- a/data/sandbox-cli/docker_sandbox_stop.yaml +++ b/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 diff --git a/data/sandbox-cli/docker_sandbox_version.yaml b/data/sandbox-cli/docker_sandbox_version.yaml index bd5a940139cc..8a3ff7f50c5d 100644 --- a/data/sandbox-cli/docker_sandbox_version.yaml +++ b/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