snowflake-sandbox-python

Python SDK and CLI for Snowflake sandboxes running on Snowflake's container substrate.

Spin up gVisor-isolated Linux containers from Python: parallel fan-out, streaming exec, stage I/O, fire-and-forget async jobs, and keep-alive sessions.

Status: alpha. The public surface is feature-flagged behind the SANDBOX_PUBLIC_API_ENABLED account parameter (default off). APIs may change in 0.x minors until the first GA cut.

Install

Python 3.11+. Three ways in, depending on whether you want the CLI alongside your project's dependencies or isolated from them.

uv, in your project:

uv add snowflake-sandbox-python            # core SDK
uv add 'snowflake-sandbox-python[cli]'     # + the `snow sandbox` CLI plugin
uv run snow plugin enable snow-sandbox     # once — see below
uv run snow sandbox --help

pip, in your project:

pip install snowflake-sandbox-python          # core SDK
pip install 'snowflake-sandbox-python[cli]'   # + the `snow sandbox` CLI plugin
snow plugin enable snow-sandbox               # once — see below
snow sandbox --help

CLI only, isolated from your project's dependencies:

uv tool install snowflake-cli --with snowflake-sandbox-python
snow plugin enable snow-sandbox
snow sandbox --help

Note the shape of that last one: snow is the tool and this package is injected into it. uv tool install 'snowflake-sandbox-python[cli]' fails — this package ships no executable of its own, so uv reports "No executables are provided by package". pipx is the same shape: pipx install snowflake-cli, then pipx inject snowflake-cli snowflake-sandbox-python.

Two things catch people out:

• snow plugin enable snow-sandbox is required. Plugins install disabled, so until you run it snow sandbox is an unknown command. It writes to ~/.snowflake/config.toml, which makes it once per machine, not once per project.
• The plugin must live in the same environment as the snow binary. Enabling it in config.toml while the package sits in a different venv still leaves snow sandbox unknown.

snowflake-connector-python is a core dependency, so password / OAuth / PAT connections work out of the box.

Preview release, gated on the Snowflake side. The SDK is published as PEP 440 pre-releases on two tracks: .devN (e.g. 0.2.1.dev9) on Snowflake's internal index only, and aN/bN/rcN (e.g. 0.2.1a1) on public PyPI. Either way a plain pip install resolves to the latest pre-release automatically — no --pre flag needed. It talks to a preview API behind the SANDBOX_PUBLIC_API_ENABLED account parameter, which Snowflake enables selectively for specific customers during the preview. You can install and import the SDK on any account, but Sandbox.create() calls succeed only once the preview is enabled for your account — contact your Snowflake account team about availability. General availability comes with the first stable (non-pre-release) version.

Hello, sandbox

from snowflake.sandbox import Sandbox

# Prerequisite: a configured Snowflake connection — a ~/.snowflake default
# (snow CLI), SNOWFLAKE_ACCOUNT + SNOWFLAKE_TOKEN env vars, or connection=.
# Without one, Sandbox.create() raises "snowflake.sandbox has no endpoint to talk to". (See below.)
with Sandbox.create() as sb:
    result = sb.exec(["python", "-c", "print(40 + 2)"])
    print(result.stdout)                # "42\n"

Sandbox is blocking. AsyncSandbox is the coroutine twin — same verbs, awaited — for driving many sandboxes concurrently:

import asyncio
from snowflake.sandbox import AsyncSandbox

async def main() -> None:
    async with await AsyncSandbox.create() as sb:
        result = await sb.exec(["python", "-c", "print(40 + 2)"])
        print(result.stdout)

asyncio.run(main())

Auth via SNOWFLAKE_ACCOUNT + SNOWFLAKE_TOKEN env vars, a named connection in ~/.snowflake/connections.toml / config.toml (resolved by snowflake-connector-python), or connection=Config(account=..., pat=...) on the call. With none of those the SDK raises "snowflake.sandbox has no endpoint to talk to: ...", which names every way to supply one.

CLI

Installs as a snow sandbox plugin:

snow plugin enable snow-sandbox
snow sandbox run --app ./my-agent/agent_app.py   # point at the module file
snow sandbox get <sandbox> --wait 600

Project layout

src/snowflake/sandbox/    # SDK — sandboxes, jobs, sessions
  cli_sandbox/            # snow sandbox CLI plugin
examples/sandbox/         # Runnable examples
tests/
docs/                     # Source for the docs site

Building the docs locally

uv run --extra docs mkdocs serve    # live preview at http://127.0.0.1:8000
uv run --extra docs mkdocs build --strict

Contributing

See CONTRIBUTING.md in the source repository for dev setup, how to add new methods, exceptions, and CLI commands.