Working with the Cortex Sandboxes CLI¶
Cortex Sandboxes ships with a plugin for the official Snowflake CLI (snow), exposed as snow sandbox. This page walks through the common tasks in the order you meet them: run code, keep a sandbox running, work with it, and end it.
To install the plugin, set up a connection, and run your first command, see the Cortex Sandboxes quickstart. Every command on this page uses your default connection. Add -c your_connection to pick another. For every option, see the Cortex Sandboxes CLI reference.
Run code and exit¶
snow sandbox run creates a sandbox, runs your code, streams the output, and removes the sandbox when the code finishes. The command exits with your code’s exit code, so it works in scripts and CI.
Run a Python file:
Run a directory. The CLI copies it into the sandbox, and you say what to run:
Run a single command with no local files:
Pass environment variables, and size the sandbox:
To see what a run would create without creating anything, add --dry-run:
Keep a sandbox running¶
Add --detach to leave the sandbox running instead of removing it when the command finishes. The CLI waits for the sandbox to start and the command to begin, then prints the sandbox’s name and returns. Give it a name you’ll recognize:
A detached sandbox suspends after a period with no inbound traffic. CPU and disk work don’t reset this timer. The default is 24 hours, longer than the platform’s usual 10 minutes, because a detached workload often has no inbound traffic while it’s still working. Set your own window with --idle-suspend, which takes a duration such as 30m or 2h (one minute at least):
Work with a running sandbox¶
List your sandboxes. The list shows each sandbox’s ID, name, status, and role. It includes running and suspended sandboxes, plus any stopped in the last 24 hours. Add --all to include older ones:
Check a sandbox’s status, or wait up to 600 seconds for its command to finish:
Read its output. A detached run of local code writes its output to /tmp/sandbox-run.out inside the sandbox, so read that file with --file:
Run another command in it, or open a terminal inside it:
You can refer to a sandbox by its name or its ID. Prefer the name: you choose it, and it’s what Sandbox.connect() takes in the SDK.
Pause and resume a sandbox¶
Suspend a sandbox to stop it consuming compute without deleting it. Resuming is a cold start: files in persistent paths such as /home come back, but running processes, memory, and /tmp don’t. A detached run writes its output to /tmp/sandbox-run.out, so read its logs before you suspend.
End a sandbox¶
Cancel stops one running sandbox:
Delete ends one or more sandboxes and frees their capacity. --all deletes every sandbox your role can see, after asking you to confirm:
Open an interactive terminal¶
snow sandbox shell with no sandbox name attaches to one you already have running, letting you pick if there are several. If none are running, it creates a fresh sandbox and removes it when you exit:
To always get a fresh sandbox, add --new. To run one command in a fresh sandbox and exit, use --cmd:
The terminal is a real PTY, so readline, curses apps, and Ctrl-C all work. It isn’t SSH: there’s no server, port 22, or keys. It runs over the same Snowflake REST path as every other sandbox call.
Pass secrets¶
Pass a Snowflake secret to snow sandbox run or snow sandbox shell with --secret ENV_VAR=DB.SCHEMA.NAME@host. The flag is repeatable, and @host is required: it limits where the credential can be sent. The secret’s value is not placed in the sandbox, and it does not appear as a plain command argument. For details, see Cortex Sandboxes concepts and security.
Build and run an agent App¶
An App is a Python module that defines an agent and the functions it exposes, along with its own egress and secrets. snow sandbox init writes a starter App, agent_app.py, and the main.py it runs. Run snow sandbox init in your project directory, because the starter App ships that directory to the sandbox:
Add --infer to have an LLM suggest Egress settings from your project’s imports. The suggestion is advisory. Add --force to overwrite an existing file.
Run the App and choose which @app.function to call. The starter App’s function is agent:
An App declares its secrets in the module, with @app.function(secrets=...), so they travel with the code. The CLI refuses --secret for an App run. See the Cortex Sandboxes SDK reference for the Secret spec.