docker-docs/data/cli/sandbox/docker_sandbox_run.yaml

command: docker sandbox run
short: Run an agent in a sandbox
long: |-
    Run an agent in a sandbox. Create the sandbox if it does not exist.

    Pass agent arguments after the "--" separator.
    Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

    Examples:
      # Create and run a sandbox with claude in current directory
      docker sandbox run claude

      # Create and run a sandbox with claude in current directory (explicit)
      docker sandbox run claude .

      # Create and run with additional workspaces (read-only)
      docker sandbox run claude . /path/to/docs:ro

      # Run an existing sandbox
      docker sandbox run existing-sandbox

      # Run a sandbox with agent arguments
      docker sandbox run claude -- --continue
usage: docker sandbox run SANDBOX [-- AGENT_ARGS...] | AGENT [WORKSPACE] [EXTRA_WORKSPACE...] [-- AGENT_ARGS...]
pname: docker sandbox
plink: docker_sandbox.yaml
options:
    - option: detached
      shorthand: d
      value_type: bool
      default_value: "false"
      description: Return sandbox ID without running agent (hidden, for testing)
      deprecated: false
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: name
      value_type: string
      description: 'Name for the sandbox (default: <agent>-<workdir>)'
      details_url: '#name'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: patch-settings
      value_type: bool
      default_value: "false"
      description: Intercept claude settings API call and patch payload
      deprecated: false
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: pull-template
      value_type: string
      default_value: missing
      description: |
        Template image pull policy: always (always pull from registry), missing (pull only if not cached), never (use only cached images)
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: template
      shorthand: t
      value_type: string
      description: |
        Container image to use for the sandbox (default: agent-specific image)
      details_url: '#template'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
inherited_options:
    - option: debug
      shorthand: D
      value_type: bool
      default_value: "false"
      description: Enable debug logging
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: socket
      value_type: string
      description: |
        Connect to daemon at specific socket path (for development/debugging)
      deprecated: false
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
examples: |-
    ### Create and run Claude in the current directory

    ```console
    $ docker sandbox run claude .
    ```

    ### Run an existing sandbox

    ```console
    $ 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.

    ### Name the sandbox (--name) {#name}

    ```text
    --name NAME
    ```

    Assign a custom name when creating a sandbox:

    ```console
    $ 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?"
    ```
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false