docker-docs/data/sbx_cli/sbx_run.yaml

name: sbx run
synopsis: Run an agent in a sandbox
description: |-
    Run an agent in a sandbox, creating the sandbox if it does not already exist.

    The first positional argument identifies the agent to run. It may be a built-in
    agent name or a sandbox kit reference. Sandbox kit references may be local
    directories, ZIP files, git repositories, or OCI references. Relative local
    references must be explicit paths such as ./my-kit or ../my-kit.zip; bare values
    retain their agent or sandbox-name meaning. A kit.shortcuts.<agent> setting (sbx
    settings set kit.shortcuts.claude myorg/claude:latest) makes that agent name
    resolve to the configured kit reference instead for local sandboxes; cloud
    sandboxes ignore it. To re-attach to an existing sandbox
    by name, use --name; the agent positional is optional when the named sandbox
    already exists and is read from its spec.

    Pass agent arguments after the "--" separator. Additional workspaces can be
    provided as extra arguments of the form PATH[:TARGET][:ro]. TARGET is an
    absolute path inside the sandbox; omit it to mount PATH at the same path as on
    the host. Append ":ro" to mount a workspace read-only; a read-only argument may
    name a single file, which holds that one path out of reach inside a workspace
    the sandbox can otherwise write.

    Omit the path to mount the current directory. Pass a path to mount a different
    workspace.

    To create a sandbox without attaching, use "sbx create" instead, or
    pass --detach (-d) to print the sandbox ID and exit without opening an
    interactive session.

    Available agents: claude, codex, copilot, cursor, devin, docker-agent, droid, gemini, kiro, opencode, shell

    With --cloud:
    Run an agent in a cloud sandbox, creating the sandbox if it does not already exist.

    The first positional argument identifies the agent to run: a built-in agent
    name or a sandbox kit reference (a local directory, ZIP file, git repository,
    or OCI reference). Relative local references must be explicit paths such as
    ./my-kit or ../my-kit.zip. Cloud sandboxes have no host workspace, so no path
    follows the agent. Pass agent arguments after the "--" separator.

    Running an agent that has existing sandboxes, running or stopped, prompts you
    to pick one to reuse or to create a new one. Pass --new to skip the prompt and
    always create a fresh sandbox. --name NAME reuses and restarts the sandbox of
    that name when it exists and creates it otherwise. A sandbox kit launch always
    creates fresh, as does a launch that bakes a mixin with build content.
    --detach skips the prompt: with --name it restarts that sandbox when it
    exists, otherwise it creates a new one. A non-interactive run without
    --detach is refused, so scripts pass --detach (e.g.
    sbx --cloud run -d claude && sbx --cloud exec ...).

    With --cloud, --env and --env-file only apply when creating a sandbox.
    Existing sandboxes keep their original environment; drop these flags to
    reattach, or pass --new to create a sandbox with the new values.

    Sizing comes from --cpus and --memory and must land on a billable shape; without
    them a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template
    must already exist in the cloud registry; the CLI does not upload it. See
    https://docs.docker.com/ai/sandboxes/ for the cloud sandbox model.
usage: sbx run [flags] [AGENT|SANDBOX_KIT] [PATH...] [-- AGENT_ARGS...]
options:
    - name: allow-network
      usage: |
        Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times)
    - name: clone
      default_value: "false"
      usage: |
        Run the agent on a private in-container clone of the host Git repository; must be set at sandbox creation time (no-op when re-attaching to an existing clone-mode sandbox)
    - name: cpus
      default_value: "0"
      usage: |
        Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs, at most 16 on Linux arm64)
    - name: deny-network
      usage: |
        Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress.
    - name: detach
      shorthand: d
      default_value: "false"
      usage: |
        Start the sandbox and print its ID without opening an agent session
    - name: detach-keys
      usage: |
        Override the detach gesture that leaves the session running (Docker-style, e.g. "ctrl-\", "ctrl-x,ctrl-d"). Default: Ctrl-\. Use this when the default collides with an agent's keymap (cloud only).
    - name: env
      shorthand: e
      default_value: '[]'
      usage: |
        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment. Applies to the agent session, so it takes effect on a re-attach too; also baked into the sandbox when this run creates it
    - name: env-file
      default_value: '[]'
      usage: |
        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one. Applies to the agent session, so it takes effect on a re-attach too; also baked into the sandbox when this run creates it
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for run
    - name: image-ref
      usage: |
        OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory)
    - name: kit
      default_value: '[]'
      experimental: true
      usage: |
        Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times
    - name: kit-arg
      default_value: '[]'
      experimental: true
      usage: |
        Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated)
    - name: kit-args-file
      default_value: '[]'
      experimental: true
      usage: |
        File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides
    - name: memory
      shorthand: m
      usage: |
        Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: host memory. Warns above 75% of host memory
    - name: mount
      default_value: '[]'
      usage: |
        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
    - name: name
      usage: 'Name for the sandbox (default: <agent>-<workdir>)'
    - name: new
      default_value: "false"
      usage: |
        Always create a new cloud sandbox instead of prompting to reuse an existing one (cloud only)
    - name: no-progress
      default_value: "false"
      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - name: platform
      usage: |
        Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
    - name: publish
      shorthand: p
      default_value: '[]'
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]. Applied when the sandbox is created; ignored when re-attaching (use "sbx ports")
    - name: pull
      usage: |
        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: rm
      default_value: "false"
      usage: Remove the sandbox after the agent session exits
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting. Can only be used when creating a new sandbox.
    - name: static-mcp
      default_value: '[]'
      usage: |
        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. Use none for a static set with no servers, local sandboxes only. The set is chosen once at creation time and cannot be changed when re-attaching to an existing sandbox. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
        Container image to use for the sandbox (default: agent-specific image)
    - name: ttl
      usage: |
        Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side)
    - name: volume
      shorthand: v
      default_value: '[]'
      experimental: true
      usage: |
        Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable)
    - name: workdir
      shorthand: w
      usage: |
        Directory to start the agent session in: absolute, or relative to the sandbox workspace. Applies to this session only, so it works on a re-attach too
inherited_options:
    - name: cloud
      default_value: "false"
      usage: |
        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
    - name: debug
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
    - name: no-input
      default_value: "false"
      usage: |
        Never prompt; commands that need an answer fail with the command to run instead
example: |4-
      # Create and run a sandbox with claude in the current directory
      sbx run claude

      # Create and run from a local sandbox kit
      sbx run ../path/to/my-agent/

      # Create and run from an OCI sandbox kit
      sbx run ghcr.io/foo/my-agent:latest

      # Add a mixin to a built-in agent
      sbx run claude --kit ./my-mixin/

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

      # Mount an additional workspace at a chosen path inside the sandbox
      sbx run claude . /path/to/data:/workspace/data

      # Re-attach to an existing sandbox by name (agent read from its spec)
      sbx run --name existing-sandbox

      # Re-attach to an existing sandbox by name and verify the expected agent
      sbx run claude --name existing-sandbox

      # Run a sandbox with agent arguments
      sbx run claude -- --continue

      # Run claude in a new cloud sandbox
      sbx --cloud run claude

      # Create a cloud sandbox non-interactively and print its ID
      sbx --cloud run --detach claude

      # Reuse the cloud sandbox of that name, creating it when it does not exist
      sbx --cloud run --name my-project claude

      # Run with agent arguments
      sbx --cloud run claude -- --continue
see_also:
    - sbx - Manage AI coding agent sandboxes.