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