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 is the agent to run. 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. Append ":ro" to mount them read-only.

    To create a sandbox without attaching, use "sbx create" instead.

    Available agents: claude, codex, copilot, cursor, docker-agent, droid, gemini, kiro, opencode, shell
usage: sbx run [flags] [AGENT] [PATH...] [-- AGENT_ARGS...]
options:
    - 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: N-1 host CPUs, min 1)
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for run
    - name: kit
      default_value: '[]'
      experimental: true
      usage: |
        Kit reference (directory, ZIP, or OCI). Can be specified multiple times
    - name: memory
      shorthand: m
      usage: |
        Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
    - name: name
      usage: 'Name for the sandbox (default: <agent>-<workdir>)'
    - name: template
      shorthand: t
      usage: |
        Container image to use for the sandbox (default: agent-specific image)
inherited_options:
    - name: debug
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
example: |4-
      # Create and run a sandbox with claude in current directory
      sbx run claude

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

      # 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
see_also:
    - sbx - Manage AI coding agent sandboxes.
