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

pip install snowflake-sandbox-python          # core SDK
pip install 'snowflake-sandbox-python[cli]'   # + the `snow sandbox` CLI plugin
snow plugin enable snow-sandbox            # required once before `snow sandbox` works

Python 3.11+. 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.