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

command: docker sandbox run
short: Run an AI agent inside a sandbox
long: |-
    Run an AI agent inside a sandbox with access to a host workspace.

    The agent argument must be one of: claude, gemini.
    Agent-specific options can be passed after the agent name.
    If no workspace is specified via the "--workspace" option, the current working directory is used.
    The workspace is exposed inside the sandbox at the same path as on the host.
usage: docker sandbox run [options] <agent> [agent-options]
pname: docker sandbox
plink: docker_sandbox.yaml
options:
    - option: credentials
      value_type: string
      default_value: sandbox
      description: Credentials source (host, sandbox, or none)
      details_url: '#credentials'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: detached
      shorthand: d
      value_type: bool
      default_value: "false"
      description: Create sandbox without running agent interactively
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: env
      shorthand: e
      value_type: stringSlice
      default_value: '[]'
      description: 'Set environment variables (format: KEY=VALUE)'
      details_url: '#env'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: mount-docker-socket
      value_type: bool
      default_value: "false"
      description: Mount the host's Docker socket into the sandbox
      details_url: '#mount-docker-socket'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: name
      value_type: string
      description: Name for the sandbox
      details_url: '#name'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: quiet
      shorthand: q
      value_type: bool
      default_value: "false"
      description: Suppress verbose output
      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
    - option: volume
      shorthand: v
      value_type: stringSlice
      default_value: '[]'
      description: |
        Bind mount a volume or host file or directory into the sandbox (format: hostpath:sandboxpath[:readonly|:ro])
      details_url: '#volume'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: workspace
      shorthand: w
      value_type: string
      default_value: .
      description: Workspace path
      details_url: '#workspace'
      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
examples: |-
    ### Run Claude in the current directory

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

    ### Specify a workspace directory (-w, --workspace) {#workspace}

    ```text
    --workspace PATH
    ```

    Run the agent in a specific directory:

    ```console
    $ docker sandbox run --workspace ~/projects/my-app claude
    ```

    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.

    ### Configure credential access (--credentials) {#credentials}

    ```text
    --credentials MODE
    ```

    Control how the agent accesses credentials. Valid modes are:

    - `sandbox` (default): Authenticate once and share credentials across sandboxes
    - `host`: Share host credentials (~/.gitconfig, ~/.ssh, etc.)
    - `none`: Handle authentication manually

    ```console
    $ docker sandbox run --credentials host claude
    ```

    ### 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:

    ```console
    $ docker sandbox run --name my-project claude
    ```
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false