Cloud Run sandbox CLI reference

The sandbox command-line tool lets you run, configure, and manage isolated sandbox environments within your containers running on Cloud Run. You can only use this CLI from within Cloud Run after you enable sandboxes. For more information on enabling sandboxes, see Configure sandboxes for services.

sandbox

This sandbox CLI provides compartmentalized execution for untrusted code and commands. By default, a sandbox blocks outbound network egress and doesn't inherit host environment variables, secrets, or metadata server credentials. The sandbox mounts the host container's root file system as read-only at /, and only /tmp is writable in memory.

Always place -- before the command and arguments on sandbox do, sandbox run, and sandbox exec so child flags aren't parsed as sandbox flags. Pass --stdin=false when running non-interactively without standard input. The sandbox CLI exits with status 0 when the command succeeds and 1 on CLI errors or any non-zero command exit status. For details on configuring isolation flags safely, see Security boundaries for untrusted code.

Options

  -h, --help                    help for sandbox

The <sandbox-id> in this document refers to the active sandbox session instance (^[a-zA-Z0-9][a-zA-Z0-9-]*$). It's either a unique ID generated by the system or a user-given name (--sandbox-name) that is validated to be unique across all sandbox instances.

sandbox do

The do command runs a command inside a new ephemeral sandbox container and blocks until the command and sandbox teardown finish. Pass --sandbox-name on automated runs so timeout handlers can clean up timed-out sessions with sandbox delete --force. Ignore exit status 1 if do already finished and deleted the sandbox. The /tmp directory is an isolated writable in-memory file system excluded from --export-tar and --sync-tar.

Syntax

sandbox do [flags] -- <command-to-execute> [args...]

Options

      --allow-egress          Allow outbound network egress. Security: disables network isolation and exposes VPC/external endpoints reachable by the host
  -e, --env string            (repeatable) Set env var as KEY=VALUE or bare KEY (reads host env). Security: require KEY=VALUE for untrusted input; never pass secrets
      --export-tar string     Write rootfs-upper tar file to path or gs:// URI on exit (requires --write; excludes /tmp and mounts; exports on exit 0). Security: never extract on host
  -h, --help                  help for do
      --import-tar string     Import rootfs-upper tar file from path or gs:// URI before start. Security: only import archives from the same trust domain
      --mount string          (repeatable) Mount (type=bind,src=<abs-host-path>,dst=<abs-path>[,readonly] in local mode, or type=volume,src=<volume-name>,dst=<abs-path>[,volume-subpath=<subpath>][,readonly] in template mode; rejects '..' in src/dst and sensitive system paths). Security: read-write by default; append ',readonly' and never mount secrets
      --rootfs string         Host root directory for the sandbox (local mode only; read-only unless --write is set). Security: exposes readable host container files (default "/")
      --sandbox-name string   Sandbox ID matching ^[a-zA-Z0-9][a-zA-Z0-9-]*$ (random if omitted; set to allow 'sandbox delete --force <id>' on timeout)
      --stderr                Forward sandbox stderr (negate with --stderr=false) (default true)
      --stdin                 Forward caller stdin (negate with --stdin=false for non-interactive calls) (default true)
      --stdout                Forward sandbox stdout (negate with --stdout=false) (default true)
      --sync-tar string       Sync rootfs-upper tar file at path or gs:// URI (mutually exclusive with --import-tar/--export-tar; exports on exit 0). Security: don't share across tenants or extract on host
      --template string       The name of the container template in your Cloud Run configuration to instantiate
      --template-var string   (repeatable) Template variables to set in the sandbox (format: KEY=VALUE, where KEY matches [a-zA-Z_]+)
  -w, --workdir string        Working directory inside the sandbox (defaults to host cwd)
      --write                 Enable writable rootfs overlay (defaults to true when --template is specified, false otherwise; negate with --write=false). Security: isolate per tenant

sandbox run

The run command creates and starts a sandbox session. Without --detach, run attaches standard I/O and blocks until the sandbox process exits. With --detach, run starts the sandbox in the background and ignores --stdin, --stdout, and --stderr. Run follow-up commands with sandbox exec, and remove the session with sandbox delete --force <sandbox-id>. If you omit -- <command-to-execute>, run starts an idle sandbox ready for exec or fork.

Syntax

sandbox run [flags] <sandbox-id> [-- <command-to-execute> [args...]]

Options

      --allow-egress          Allow outbound network egress. Security: disables network isolation and exposes VPC/external endpoints reachable by the host
      --detach                Start sandbox in the background and return once running (ignores --stdin/--stdout/--stderr)
  -e, --env string            (repeatable) Set env var as KEY=VALUE or bare KEY (reads host env). Security: require KEY=VALUE for untrusted input; never pass secrets
  -h, --help                  help for run
      --import-tar string     Import rootfs-upper tar file from path or gs:// URI before start. Security: only import archives from the same trust domain
      --mount string          (repeatable) Mount (type=bind,src=<abs-host-path>,dst=<abs-path>[,readonly] in local mode, or type=volume,src=<volume-name>,dst=<abs-path>[,volume-subpath=<subpath>][,readonly] in template mode; rejects '..' in src/dst and sensitive system paths). Security: read-write by default; append ',readonly' and never mount secrets
      --rootfs string         Host root directory for the sandbox (local mode only; read-only unless --write is set). Security: exposes readable host container files (default "/")
      --stderr                Forward sandbox stderr (negate with --stderr=false) (default true)
      --stdin                 Forward caller stdin (negate with --stdin=false for non-interactive calls) (default true)
      --stdout                Forward sandbox stdout (negate with --stdout=false) (default true)
      --template string       The name of the container template in your Cloud Run configuration to instantiate
      --template-var string   (repeatable) Template variables to set in the sandbox (format: KEY=VALUE, where KEY matches [a-zA-Z_]+)
  -w, --workdir string        Working directory inside the sandbox (defaults to host cwd)
      --write                 Enable writable rootfs overlay (defaults to true when --template is specified, false otherwise; negate with --write=false). Security: isolate per tenant

sandbox exec

The exec command runs a command inside an existing running sandbox and blocks until the command exits. Always place -- before <command-to-execute> so child flags aren't parsed by sandbox exec. Pass --stdin=false when running non-interactively without standard input.

Syntax

sandbox exec [flags] <sandbox-id> -- <command-to-execute> [args...]

Options

  -e, --env string       (repeatable) Set env var as KEY=VALUE or bare KEY (reads host env). Security: require KEY=VALUE for untrusted input; never pass secrets
  -h, --help             help for exec
      --stderr           Forward sandbox stderr (negate with --stderr=false) (default true)
      --stdin            Forward caller stdin (negate with --stdin=false for non-interactive calls) (default true)
      --stdout           Forward sandbox stdout (negate with --stdout=false) (default true)
  -w, --workdir string   Working directory inside the sandbox (defaults to host cwd)

sandbox fork

The fork command creates a new sandbox from the writable root file system overlay (rootfs-upper) of a running source sandbox. It restarts the source sandbox's startup command from scratch rather than taking a live memory snapshot. Files under /tmp and external --mount paths are excluded from the fork.

Without --detach, fork blocks until <target-sandbox-id> exits. Pass --detach when forking an idle detached sandbox, and always remove forked sessions with sandbox delete --force <target-sandbox-id>. Don't fork a sandbox that has run untrusted code from one tenant to serve another.

Syntax

sandbox fork [flags] <source-sandbox-id> <target-sandbox-id>

Options

      --allow-egress   Allow outbound network egress. Security: disables network isolation and exposes VPC/external endpoints reachable by the host
      --detach         Start the forked sandbox in the background and return once running
  -h, --help           help for fork
      --tar string     Save intermediate rootfs-upper tar file to path or gs:// URI (local mode only). Security: never extract on host

sandbox tar

The tar command exports a tar archive of a running sandbox's writable root file system overlay (rootfs-upper) to --file. The --file flag is required and accepts a local path or gs:// URI; sandbox tar never writes archive bytes to stdout. Files written under /tmp or external --mount paths are excluded. Never extract (tar -xf) an untrusted sandbox archive directly on the host container file system.

Syntax

sandbox tar [flags] --file=<file-path> <sandbox-id>

Options

      --file string   Output path or gs:// URI for rootfs-upper tar file (required). Security: never extract on host; stream validated regular files or re-import into a sandbox
  -h, --help          help for tar

sandbox delete

The delete command removes a sandbox session and releases its overlay, network, and cgroup resources. Sessions created with sandbox run or sandbox fork retain state after their process exits and must be deleted. Pass --force to stop and delete a running sandbox. The delete --force command exits with status 1 if <sandbox-id> doesn't exist or was already deleted. Ignore exit status 1 when calling sandbox delete --force from cleanup handlers.

Syntax

sandbox delete [flags] <sandbox-id>

Options

      --force   Force delete the sandbox, even if it is running
  -h, --help    help for delete