Tutorial: Your first Cortex Sandbox in Cortex Code

This tutorial walks through using Cortex Sandboxes from Cortex Code (CoCo Desktop) step by step. Each section includes a prompt you can paste directly into Cortex Code.

You will go from installing the SDK to running a complete Cortex Sandboxes workflow in five steps: install the package, run your first sandbox, run untrusted code safely, query Snowflake from inside a sandbox using your own session identity, and fan out work across multiple sandboxes in parallel. In each step, Cortex Code generates and runs the code for you.

Time to complete: about 15 minutes.

Prerequisites

  • Cortex Code (CoCo Desktop) installed and connected to Snowflake.
  • A Snowflake account with Cortex Sandboxes enabled. To request access, contact your Snowflake account representative.
  • Python 3.11 or later.
  • A configured Snowflake connection. The SDK resolves credentials from the default connection in ~/.snowflake/connections.toml; if none is configured, creating a sandbox raises snowflake.sandbox has no endpoint to talk to. See Cortex Sandboxes quickstart.

Step 1: Install the SDK

In Cortex Code, paste this prompt:

Install snowflake-sandbox-python using pip.

Confirm the installation succeeded.

Cortex Code runs the install command. When it completes, snowflake-sandbox-python is available in your Python environment.

Important

Installing the SDK does not grant access. The sandbox-creating steps below succeed only once Cortex Sandboxes is enabled for your account, which Snowflake does selectively during preview. Contact your Snowflake account team about availability.

Step 2: Run your first sandbox

Using the snowflake-sandbox-python SDK, create a Cortex Sandbox and run python -c "print(40 + 2)" inside it. Do not specify an image — use the default. Print the output and confirm the sandbox terminated cleanly.

Cortex Code generates and executes:

from snowflake.sandbox import Sandbox

with Sandbox.create() as sb:
    result = sb.exec(["python", "-c", "print(40 + 2)"])
    print(result.stdout)   # 42

Expected output: 42. The with block destroys the sandbox automatically on exit — no cleanup required.

Step 3: Run untrusted code safely

This is the core use case. You have a Python script from an external source. Running it directly in your Cortex Code session gives it access to your local environment: your files, your shell, and your CoCo process. Running it in a sandbox confines it: the script runs in an isolated container, separate from your machine, your local files, and your CoCo session.

The sandbox does inject your session identity (you will see this in Step 4), so the script can still query Snowflake, and your governance policies apply to everything it reads. By default the sandbox runs with your primary role and all of your secondary roles, so the script can use any privilege those roles grant. To restrict it to one role, specify that role when you create the sandbox.

I have this Python script and I want to run it safely in a Cortex Sandbox so it cannot access my local machine or affect my Cortex Code session. Run it and show me the output.

import socket, os
print("hostname:", socket.gethostname())
print("user:", os.environ.get("USER", "unknown"))
print("snowflake account:", os.environ.get("SNOWFLAKE_ACCOUNT", "not set"))

Cortex Code wraps it in a sandbox exec. The hostname will differ from your machine (showing it runs in a separate container). SNOWFLAKE_ACCOUNT is set — the platform injects it so the script can connect to Snowflake using the session token — but the script cannot read your local files, crash your CoCo session, or escape the container.

Step 4: Access Snowflake data from inside a sandbox

Sandboxes run as your Snowflake session. The platform provides your session credential automatically, and get_snowflake_connection() resolves it, so code inside the sandbox can query Snowflake without any credential configuration.

Using the Cortex Sandboxes SDK, create a sandbox using the deployment’s default image and run a Python script inside it that connects to Snowflake with get_snowflake_connection(), then runs SELECT CURRENT_USER(), CURRENT_ROLE(). Print the result.

Cortex Code generates the driver and the in-sandbox script, runs it, and shows the output:

Running as: MY_USER / MY_ROLE

The sandbox connects as your user and role, so your governance policies, including row-level security and column masking, apply to what the script can read. For the code itself and what the helper resolves, see Step 3 of the SDK walkthrough.

Step 5: Fan out across multiple sandboxes

Each sandbox is independent, so work can run across many of them at once.

Using the Cortex Sandboxes SDK, create 5 sandboxes in parallel using ThreadPoolExecutor. Each sandbox should print its index number after sleeping for 1 second. Print all results and the total elapsed time.

Cortex Code writes the fan-out and reports the timing. Because each thread waits for its own container to start, total elapsed time is roughly one container start plus one second, not five times that. Isolation is per-sandbox; execution is parallel.

Two things to know before you use this on real work: nothing expires a sandbox on its own, and a fan-out strands containers if you skip the teardown. For the code, the wait=False idiom that avoids holding a thread per sandbox, and the live-sandbox quota, see Step 4 of the SDK walkthrough.

Next steps

Next
Step 1: Install the SDK