Tutorial: Work with sandboxes using the Python SDK¶

The quickstart creates one sandbox inside a with block and terminates it on exit. That covers a single piece of work in a single process.

This tutorial covers the four things you need beyond that: sandboxes that outlive a with block, tasks that outlive the driver process, querying Snowflake from inside the container, and running many sandboxes at once. Each step is independent, so you can read only the one you need.

Prerequisites¶

• The snowflake-sandbox-python SDK installed and a Snowflake connection configured. See Cortex Sandboxes quickstart.
• Run the examples from a local terminal, not from inside a Snowflake Workspace. A driver running in a Workspace creates a sandbox that does not inherit the credentials snowflake.connector needs to connect back to Snowflake from inside the container.

Save each example to a file and run it with python main.py.

Step 1: Run longer-lived work with a named sandbox¶

For work that should persist and be reconnected to later, give the sandbox a name and reconnect by that name:

from snowflake.sandbox import Sandbox

sb = Sandbox.create(name="my-agent")
print("created: my-agent")

# ... later, from another process:
sb2 = Sandbox.connect("my-agent")
result = sb2.exec(["python", "-c", "print('reconnected')"])
print(result.stdout)
sb2.terminate()

The name is the identity you reconnect with. Sandbox.connect() takes a name, not an ID, and a name is unique per owner.

A named sandbox created outside a with block keeps running until something terminates it. It does not bill compute for the whole of that time: the platform auto-suspends a sandbox that has been idle and resumes it on next use, so an idle named sandbox stops consuming compute without being deleted. The default idle window is 10 minutes. Pass idle_suspend= to Sandbox.create() to choose a different one, as a datetime.timedelta or a duration string such as "30m", down to a minimum of one minute.

Suspension is not deletion, though. A suspended sandbox still exists, still counts against your live-sandbox cap, and always resumes as a fresh container that has lost /tmp and every running process. Call terminate() when the work is done, as the example does.

For listing what is running, streaming logs from it, and handling a cold restart, see Tutorial: Reconnect to a running sandbox.

Step 2: Run a detached task and wait for it¶

For work that should run to completion and outlive this driver process, start a sandbox with a command and poll its result with wait(). Give it a name and reattach with Sandbox.connect() to check on it later from any process:

from snowflake.sandbox import Sandbox

# A run-to-completion sandbox; it runs independently of this driver.
Sandbox.create(command=["python", "-c", "print('task complete')"], name="my-task")

# Reattach (for example, later, from another process) and wait for the result.
sb = Sandbox.connect("my-task")
result = sb.wait()
print(result.status, result.exit_code)
sb.terminate()

The task runs to completion on its own; the driver reattaches and waits, then prints succeeded 0. wait() returns a RunResult whose status is "succeeded", "failed", or "timed_out".

A reattached handle reports the outcome but not the returned value: result.result is populated only on the handle that created the run, so on a handle from Sandbox.connect() it is always None. To collect a return value, either keep the handle create() returned and call wait() on it, or have the task write its output somewhere durable, such as a Snowflake table or a stage, and read it from there.

Step 3: Query Snowflake from inside the sandbox¶

Sandboxes run with your own session identity. Code inside the sandbox can query Snowflake without any credential configuration, because the platform provides the credential and get_snowflake_connection() resolves it:

from snowflake.sandbox import Sandbox

QUERY_SCRIPT = """
from snowflake.sandbox import get_snowflake_connection

conn = get_snowflake_connection()
cur = conn.cursor()
cur.execute("SELECT CURRENT_USER(), CURRENT_ROLE()")
row = cur.fetchone()
print("Running as:", row[0], "/", row[1])
"""

with Sandbox.create() as sb:
    result = sb.exec(["python", "-c", QUERY_SCRIPT])
    print(result.stdout)

The script connects from inside the sandbox using your injected session identity and prints the user and role the sandbox runs as, for example:

Running as: MY_USER / MY_ROLE

Your Snowflake governance policies, including row-level security and column masking, apply to what the script can read, exactly as they would for any query you run directly. See Cortex Sandboxes concepts and security and Tutorial: Governance enforcement in a sandbox.

get_snowflake_connection() is the recommended path for in-sandbox code, production included. It handles the host format, the role, a default login timeout, and the platform’s egress-proxy CA, all of which hand-rolled connector code commonly gets wrong. For what it resolves and for the cases where you need to control the connection yourself, see Connect to Snowflake from the SDK.

Step 4: Fan out across sandboxes in parallel¶

Each sandbox is independent, so you can run work across many sandboxes at once using threads:

from concurrent.futures import ThreadPoolExecutor
from snowflake.sandbox import Sandbox

def run_one(i: int) -> str:
    with Sandbox.create() as sb:
        r = sb.exec(["python", "-c", f"import time; time.sleep(1); print({i})"])
        return r.stdout.strip()

with ThreadPoolExecutor() as pool:
    results = list(pool.map(run_one, range(5)))
for r in results:
    print(r)

The five sandboxes run in parallel, so the whole fan-out finishes in roughly the time of a single run and prints 0 through 4.

This example omits image, so each sandbox uses the server’s default base image. To select a specific image, pass image= to Sandbox.create().

Fan out without holding a thread per sandbox¶

The pattern above holds a thread for each sandbox’s whole lifetime, because Sandbox.create() blocks until the container is live. For a larger fan-out, wait=False returns immediately and lets you fire every create first, then wait for readiness:

from contextlib import ExitStack
from concurrent.futures import ThreadPoolExecutor
from snowflake.sandbox import Sandbox

# wait=False returns before the container is live, so these cannot be created
# with `with` directly. Register each one for teardown as it is created.
with ExitStack() as stack:
    sandboxes = []
    for _ in range(10):
        sb = Sandbox.create(wait=False)
        stack.callback(sb.terminate)   # runs even if a later create raises
        sandboxes.append(sb)

    with ThreadPoolExecutor() as pool:
        pool.map(lambda sb: sb.wait_until_ready(), sandboxes)

    # ... use the sandboxes here; all ten are terminated when the block exits.

wait_until_ready() is a no-op on a sandbox that is already ready. It raises SandboxNotReadyError if the timeout expires first, and SandboxTransportError if the server reports a create failure.

What this demonstrates¶

• A name is an identity, not a label. It is what Sandbox.connect() resolves, it is unique per owner, and it is what makes a sandbox outlive the process that created it.
• Idle suspension is not cleanup. It stops compute; it does not release quota or free the container. Termination is explicit, always.
• Identity is supplied, not configured. Code inside the sandbox reaches Snowflake as you, with your governance applied, and no credential is placed in the container.
• Parallelism is per-sandbox. Isolation does not weaken as you fan out, but quota is shared, so teardown matters more the wider you go.

Going further¶

• To list running sandboxes, stream logs, and handle cold restarts, see Tutorial: Reconnect to a running sandbox.
• To apply the fan-out pattern to real work, see Tutorial: Run Cortex batch inference over a Snowflake table.
• To give a sandbox access to an external API without placing a credential in it, see Tutorial: Give a sandbox secure access to an external API.
• For the full API surface, see the Cortex Sandboxes SDK reference.