Cortex Sandboxes CLI reference¶

The snow sandbox CLI plugin provides the init, run, shell, logs, list, get, delete, and cancel commands. This page is the reference for each command and its options. Ensure snow --version succeeds before running any snow sandbox command.

Commands¶

Command	What it does
`snow sandbox init`	Scaffold a starter Python module that defines a deployable agent App.
`snow sandbox run`	Run a workload in a sandbox: local code (TARGET) or an image (–image).
`snow sandbox shell`	Run a command, open a terminal, or attach to a running sandbox.
`snow sandbox logs`	Print or follow a sandbox’s output.
`snow sandbox list`	List your sandboxes: id, name, created_at, stopped_at, status, reason, and role.
`snow sandbox get`	Show a sandbox’s status; with –wait, block for its result.
`snow sandbox delete`	Delete (terminate) sandboxes and free their capacity.
`snow sandbox cancel`	Cancel (destroy) a running sandbox.
`snow sandbox suspend`	Suspend a sandbox, snapshotting its filesystem.
`snow sandbox resume`	Resume a suspended sandbox.

Every snow sandbox command also accepts the standard Snowflake CLI output and diagnostic options — --format, --verbose, --debug, --silent, --enhanced-exit-codes and --decimal-precision — which are documented once in the Snowflake CLI reference and omitted from the per-command option tables below.

`snow sandbox init`¶

Scaffold a starter Python module that defines a deployable agent App.

Syntax¶

snow sandbox init [PATH] [--infer] [--force]

Options¶

Option	Description
`PATH`	Module to write (default: ./agent_app.py).
`--infer`	Use LLM to suggest Egress settings from project imports (advisory; degrades gracefully).
`--force`	Overwrite an existing file.

Examples¶

snow sandbox init                  # creates ./agent_app.py
snow sandbox init my_agent.py      # custom name
snow sandbox init . --infer        # ask an LLM to suggest Egress settings

`snow sandbox run`¶

Run a workload in a sandbox: local code (TARGET) or an image (–image).

Syntax¶

snow sandbox run [TARGETS] [--app MODULE.py] [--command CMD] [--detach] [--dry-run] [--function NAME] [--env KEY=VAL] [--image IMAGE] [--include GLOB] [--exclude GLOB] [--allow-credential-file PATH] [--eai NAME] [--secret ENV_VAR=DB.SCHEMA.NAME] [--no-default-egress] [--allow-large] [--memory TIER] [--cpu CORES] [--idle-suspend DURATION] [--name NAME] [--quiet] [--use-snow-connection|--no-snow-connection] [--connection CONNECTION]

Options¶

Option	Description
`TARGETS`	Local paths to run: files and/or directories, repeatable. Never an image reference – pass images as –image. Omit to run –image (or the default image) directly, or use –app for an App module.
`--app MODULE.py`	Deploy a .py module that declares an App, via the SDK authoring path. Explicit: a plain script is never treated as an App because of its contents.
`--command CMD`	Command to run after the code is in place (streamed, exits with its code). Overrides extension detection; required for a directory, an unrecognized file type, and for a TARGET-less run unless –detach runs the image’s own entrypoint. Not valid for an App module. `--cmd` is an accepted alias (same flag on `shell`).
`--detach`	Create the sandbox and leave it running instead of running to completion: wait for it to spin up and the command to start, then print the handle and return. (Supervised restart across platform interruptions is a separate, not-yet-available feature.)
`--dry-run`	Print the resolved plan and exit without creating anything.
`--function NAME`, `-f`	For an App module: which @app.function to run (default: the first). Errors on any other target.
`--env KEY=VAL`, `-e`	Runtime env var passed into the container as KEY=VAL; repeatable.
`--image IMAGE`	The image to run. With no TARGET it IS the workload; with local TARGETs it is the base image that code runs on. Default: the deployment’s default runtime image. Invalid with –app (the App declares it).
`--include GLOB`	Re-admit paths an exclusion dropped; repeatable, applied after every –exclude. gitignore syntax, relative to each TARGET. Cannot resurrect a credential-shaped file.
`--exclude GLOB`	Skip matching paths; repeatable. gitignore syntax relative to each TARGET, so `node_modules/` and `data/` work as written.
`--allow-credential-file PATH`	Upload one credential-shaped file (.env, *.pem, id_rsa, …) that is excluded by default. Exact path only, never a glob; repeatable.
`--eai NAME`	External Access Integration granting egress to hosts outside the built-in baseline; repeatable. Your role needs USAGE on it, and its network rules must be readable or the platform refuses the create.
`--secret ENV_VAR=DB.SCHEMA.NAME`	Snowflake SECRET to inject, as ENV_VAR=DB.SCHEMA.NAME@host[,host]; repeatable. The @host scopes where the credential may be sent and is required. Omit ENV_VAR= for the derived CNG_SECRET_<FQN> name.
`--no-default-egress`	Close the default egress: Snowflake and its stages only, dropping the baseline package-manager hosts. An –eai still grants on top of this.
`--allow-large`	Proceed with an upload over the size or file-count limit. /tmp is RAM-backed, so a large upload competes with the workload for –memory.
`--memory TIER`	Memory tier: 1g/4g/8g/16g/32g/64g (default: 4g).
`--cpu CORES`	CPU cores (0.25-8.0).
`--idle-suspend DURATION`	Idle-suspend timeout (e.g. 30m/2h) for a –detach image or local-code run (default: 24h).
`--name NAME`	Name for a –detach image or local-code sandbox (unique per owner).
`--quiet`	Suppress the status lines on stderr; the command’s own output is unaffected.
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.

Examples¶

snow sandbox run agent.py                           # local script: stream, exit
snow sandbox run src/ config.yaml main.py           # several paths at once
snow sandbox run ./project --command "python -m app"
snow sandbox run ./project --exclude "data/" --exclude "*.log"
snow sandbox run main.py --image /repo/node:20 --command "node main.js"
snow sandbox run agent.py --detach                  # leave it running
snow sandbox run --image /repo/snowbots:8 --detach --command "node /boot.mjs"
snow sandbox run --image /repo/snowbots:8 --detach  # the image's own entrypoint
snow sandbox run --command "echo hi"                # ad-hoc, default image
snow sandbox run --app agent_app.py --function triage
snow sandbox run --app agent_app.py --dry-run

`snow sandbox shell`¶

Run a command, open a terminal, or attach to a running sandbox.

Note

The interactive terminal is a PTY over the ordinary Snowflake REST path, not the SSH protocol – no server, no port 22, no keys, no scp. –no-sanitize passes the sandbox’s output through byte-exact, including clipboard-write sequences (see Shell.attach’s trust note); it affects the interactive terminal only.

Syntax¶

snow sandbox shell [SANDBOX_ID] [--cmd COMMAND] [--image IMAGE] [--memory TIER] [--cpu CORES] [--env KEY=VAL] [--eai NAME] [--secret ENV_VAR=DB.SCHEMA.NAME@host] [--no-default-egress] [--keep] [--new] [--cwd DIR] [--no-sanitize] [--quiet] [--use-snow-connection|--no-snow-connection] [--connection CONNECTION]

Options¶

Option	Description
`SANDBOX_ID`	Existing sandbox (name or app id) to attach to. Omit to attach to a running one (picker), or create a fresh ephemeral one if none are running. Use –new to always create a fresh one.
`--cmd COMMAND`	Command to run (streamed, exits with its code). Omit for an interactive terminal. `--command` is an accepted alias (same flag on `run`).
`--image IMAGE`	Image for a fresh sandbox (default: the deployment’s default image). Not valid with SANDBOX_ID.
`--memory TIER`	Memory tier for a fresh sandbox: 1g/4g/8g/16g/32g/64g (default: 4g). Not valid with SANDBOX_ID.
`--cpu CORES`	CPU cores (0.25-8.0) for a fresh sandbox. Not valid with SANDBOX_ID.
`--env KEY=VAL`, `-e`	Runtime env var passed into the container as KEY=VAL; repeatable.
`--eai NAME`	External Access Integration granting egress to hosts outside the built-in baseline; repeatable. Your role needs USAGE on it, and its network rules must be readable or the platform refuses the create.
`--secret ENV_VAR=DB.SCHEMA.NAME@host`	Snowflake SECRET to inject, as ENV_VAR=DB.SCHEMA.NAME@host[,host]; repeatable. The @host scopes where the credential may be sent and is required. Omit ENV_VAR= for the derived CNG_SECRET_<FQN> name.
`--no-default-egress`	Close the default egress: Snowflake and its stages only, dropping the baseline package-manager hosts. An –eai still grants on top of this.
`--keep`	Leave a fresh sandbox running on exit (prints its name). Not valid with SANDBOX_ID.
`--new`	Always create a fresh sandbox, even if some are already running (skips the attach/picker path). Not valid with SANDBOX_ID.
`--cwd DIR`	Working directory for the shell/command.
`--no-sanitize`	Interactive only: pass the sandbox’s output through byte-exact. See the trust note.
`--quiet`	Suppress the status lines on stderr (spinning up / ready / running). The command’s own output is unaffected, so `--quiet` is safe for scripting.
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.

Examples¶

snow sandbox shell --cmd "python -c 'print(40 + 2)'"   # fresh box: run, tear down
snow sandbox shell --cmd "python train.py" --memory 16g
snow sandbox shell                                     # pick a running box (or make one if none)
snow sandbox shell --new                               # always a fresh box, interactive
snow sandbox shell --image sandbox-base                # fresh box, interactive
snow sandbox shell cntr_9f2a1b                         # attach to an existing box
snow sandbox shell cntr_9f2a1b --cmd "ls -la"          # run once in an existing box

`snow sandbox logs`¶

Print or follow a sandbox’s output.

Syntax¶

snow sandbox logs CONTAINER_ID [--tail N] [--follow] [--since MS] [--source WHICH] [--pid N] [--file PATH] [--use-snow-connection|--no-snow-connection] [--connection CONNECTION]

Options¶

Option	Description
`CONTAINER_ID`	Sandbox (name or app id) whose captured output to read.
`--tail N`	Print only the last N lines (0 = all). With –follow, print the last N, then stream new lines. Default: `0`.
`--follow`	Stream the output live until the process finishes (Ctrl-C to stop).
`--since MS`	Only lines at or after this server timestamp (Unix epoch ms). Ignored with –follow. Default: `0`.
`--source WHICH`	Which output to read: all (the default when omitted: base + managed, and it does NOT include exec), managed (just the command= process), exec (what `exec()` calls printed), or base (the container’s own stdout/stderr). Snapshot only — –follow tails the managed process and cannot follow another source.
`--pid N`	With –source exec, read only this producer instead of every exec merged by capture time. The pid is shown per line in the merged output. Default: `0`.
`--file PATH`	Read this file inside the sandbox instead of the managed-process log. Use it for a `run --detach` local-code run, whose output is tee’d to /tmp/sandbox-run.out. Not valid with –since.
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.

Examples¶

snow sandbox logs SANDBOX_ID
snow sandbox logs SANDBOX_ID --tail 50
snow sandbox logs SANDBOX_ID --follow
snow sandbox logs SANDBOX_ID --source exec
snow sandbox logs SANDBOX_ID --source exec --pid 295
snow sandbox logs SANDBOX_ID --file /tmp/sandbox-run.out --follow

`snow sandbox list`¶

List your sandboxes: id, name, created_at, stopped_at, status, reason, and role.

Syntax¶

snow sandbox list [--use-snow-connection|--no-snow-connection] [--connection CONNECTION] [--all]

Options¶

Option	Description
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.
`--all`	Also show sandboxes stopped more than 24h ago and other terminal states the backend still retains. By default only running/suspended and recently-stopped (<=24h) sandboxes are listed.

Examples¶

snow sandbox list

`snow sandbox get`¶

Show a sandbox’s status; with –wait, block for its result.

Syntax¶

snow sandbox get SANDBOX [--wait SECONDS] [--use-snow-connection|--no-snow-connection] [--connection CONNECTION]

Options¶

Option	Description
`SANDBOX`	Sandbox name (or id) whose status to show.
`--wait SECONDS`, `-w`	Block up to SECONDS for a terminal result, then print it.
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.

Examples¶

snow sandbox get SANDBOX
snow sandbox get SANDBOX --wait 120

`snow sandbox delete`¶

Delete (terminate) sandboxes and free their capacity.

Syntax¶

snow sandbox delete [SANDBOX_IDS] [--all] [--yes] [--use-snow-connection|--no-snow-connection] [--connection CONNECTION]

Options¶

Option	Description
`SANDBOX_IDS`	Sandbox ids (cntr_…) or names to delete. Omit when using –all.
`--all`	Delete every sandbox this connection’s role can see.
`--yes`	Skip the confirmation prompt for –all.
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.

Examples¶

snow sandbox delete cntr_9f2a1b
snow sandbox delete my-box other-box
snow sandbox delete --all
snow sandbox delete --all --yes          # no prompt (scripting)

`snow sandbox cancel`¶

Cancel (destroy) a running sandbox.

Syntax¶

snow sandbox cancel SANDBOX [--use-snow-connection|--no-snow-connection] [--connection CONNECTION]

Options¶

Option	Description
`SANDBOX`	Sandbox name (or id) to cancel.
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.

Examples¶

snow sandbox cancel SANDBOX

`snow sandbox suspend`¶

Suspend a sandbox, snapshotting its filesystem.

Syntax¶

snow sandbox suspend SANDBOX [--use-snow-connection|--no-snow-connection] [--connection CONNECTION]

Options¶

Option	Description
`SANDBOX`	Sandbox name (or id) to suspend.
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.

Examples¶

snow sandbox suspend SANDBOX

`snow sandbox resume`¶

Resume a suspended sandbox.

Syntax¶

snow sandbox resume SANDBOX [--use-snow-connection|--no-snow-connection] [--connection CONNECTION]

Options¶

Option	Description
`SANDBOX`	Sandbox name (or id) to resume.
`--use-snow-connection / --no-snow-connection`	Use the active snow connection’s credentials (default). –no-snow-connection falls back to SDK env/config resolution (SNOWFLAKE_PAT, ~/.snowflake). An explicit SNOWFLAKE_PAT/TOKEN in the environment is used either way.
`--connection`, `-c`	Named connection from ~/.snowflake to use (defaults to your default connection). Provided by the plugin because `snow sandbox` commands do not take the CLI’s global -c.

Examples¶

snow sandbox resume SANDBOX

Cortex Sandboxes CLI reference¶

Commands¶

snow sandbox init¶

Syntax¶

Options¶

Examples¶

snow sandbox run¶

Syntax¶

Options¶

Examples¶

snow sandbox shell¶

Syntax¶

Options¶

Examples¶

snow sandbox logs¶

Syntax¶

Options¶

Examples¶

snow sandbox list¶

Syntax¶

Options¶

Examples¶

snow sandbox get¶

Syntax¶

Options¶

Examples¶

snow sandbox delete¶

Syntax¶

Options¶

Examples¶

snow sandbox cancel¶

Syntax¶

Options¶

Examples¶

snow sandbox suspend¶

Syntax¶

Options¶

Examples¶

snow sandbox resume¶

Syntax¶

Options¶

Examples¶

`snow sandbox init`¶

`snow sandbox run`¶

`snow sandbox shell`¶

`snow sandbox logs`¶

`snow sandbox list`¶

`snow sandbox get`¶

`snow sandbox delete`¶

`snow sandbox cancel`¶

`snow sandbox suspend`¶

`snow sandbox resume`¶