sbx run

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. 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; 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 --detached (-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 launch that bakes a kit template (a sandbox kit or a mixin with build content) always creates fresh. --detached skips the prompt: with --name it restarts that sandbox when it exists, otherwise it creates a new one. A non-interactive run without --detached is refused, so scripts pass --detached (e.g. sbx --cloud run -d claude && sbx --cloud exec ...).

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.

Options

Global options

Examples

# 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

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