Description

Run an agent in a sandbox. Create the sandbox if it does not exist.

Pass agent arguments after the "--" separator.

Examples:

Create and run a sandbox with claude in current directory

docker sandbox run claude .

Run an existing sandbox

docker sandbox run existing-sandbox

Run a sandbox with agent arguments

docker sandbox run claude . -- -p "What version are you running?"

Options

Examples

Run Claude in the current directory

$ docker sandbox run claude

Specify a workspace directory (-w, --workspace)

--workspace PATH

Run the agent in a specific directory:

$ 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

Mount the host's Docker socket into the sandbox, giving the agent access to Docker commands:

$ 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 KEY=VALUE

Pass environment variables to the sandbox:

$ docker sandbox run \
  --env NODE_ENV=development \
  --env DATABASE_URL=postgresql://localhost/myapp \
  claude

Mount additional volumes (-v, --volume)

--volume HOST_PATH:CONTAINER_PATH[:ro]

Mount additional directories or files into the sandbox:

$ docker sandbox run \
  --volume ~/datasets:/data:ro \
  --volume ~/models:/models \
  claude

Use :ro or :readonly to make mounts read-only.

Use a custom base image (-t, --template)

--template IMAGE

Specify a custom container image to use as the sandbox base:

$ 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 NAME

Assign a custom name to the sandbox for easier identification:

$ docker sandbox run --name my-project claude