Get started with CoreWeave sandboxes

This guide walks through enabling sandboxes on a CoreWeave Kubernetes Service (CKS) cluster end to end. You’ll do the following:

Create a profile
Enable a runner
Run your first sandbox from the Python client
Disable the runner when you’re done.

Use it when you need sandbox execution on a cluster and want to confirm the setup with a short Python run. The administrator steps create the profile and enable the runner. The researcher step runs sandboxes against it. For background on the components and how they fit together, see About CoreWeave sandboxes. The wizard and from-file tabs are equivalent. The from-file tabs accept YAML or JSON, which makes them a natural interface for agents (such as Claude Code or Codex) that author or modify profile and runner specs on your behalf.

CoreWeave sandboxes are currently in limited availability. Contact CoreWeave Support or email [email protected] for access.

Prerequisites

For the administrator steps, complete the following:

A CKS cluster in your CoreWeave organization, in the STATUS_RUNNING state. View your clusters and their status on the Clusters page in the cloud console.
The SANDBOX_ADMIN action in Identity and Access Management (IAM), which lets you create profiles and runners. Create or update a policy that grants this action on the Access Policies page in the cloud console.
The CoreWeave Intelligent CLI installed and authenticated.

For the researcher step, complete the following:

The SANDBOX_USER IAM action, which lets you create sandboxes against the data plane. Granting SANDBOX_ADMIN also grants SANDBOX_USER.
A CoreWeave API access token. For more information, see Manage API Access Tokens.
Python 3.11 or newer in the environment that runs the SDK. The Python version inside the sandbox is independent and is set by the container_image you pass to Sandbox.run() or by the profile’s default.

When you meet these requirements, work through the following sections in order.

Create a profile

A profile defines the execution environment for sandboxes a runner produces: namespace strategy, network policies, and pod constraints. Use the CoreWeave Intelligent CLI to create one before you enable a runner. The example profile below uses a per-user namespace strategy and denies all outbound network access from sandboxes. Adjust the network policy for your environment: switch the mode type to internet for unrestricted egress, allowlist to permit specific CIDRs, or org, profile, or user to scope traffic to other sandboxes you control. Available egress types are internet, user, org, profile, allowlist, and none. Create a file profile.yaml:

display_name: default
description: Per-user sandboxes with no outbound network access
spec:
  namespace:
    strategy: per-user
  network:
    egress:
      default: deny-all
      modes:
        deny-all:
          type: none

Wizard
From file

The wizard collects display name, description, namespace strategy, and egress modes interactively, then opens your editor with a pre-filled spec to review before submitting:

cwic sandbox profile create

Submit the profile YAML directly:

cwic sandbox profile create -f profile.yaml

The CLI prints the new template’s ID. Reference it when you enable a runner from a file.

At this point, your organization has a profile template you can bind when you enable a runner.

Enable a runner on a CKS cluster

A runner is the Kubernetes workload that schedules sandbox pods on your cluster. CoreWeave operates the runner. You enable it on a specific cluster.

Cloud console
CLI wizard
CLI from file

The cloud console enable flow requires at least one profile template to already exist for your organization. Create a profile template before you use this tab.

Open the Clusters page in the cloud console.
Select the cluster you want to enable sandboxes on.
In the Sandbox runner card, click Enable sandbox runner.

The console binds the first profile template returned for your organization as the default. If you created exactly one template while creating a profile, that profile becomes the default.The card transitions through Pending to Ready. The runner then accepts sandbox requests.

The wizard prompts for a CKS cluster, the profile templates to bind, which template is the default, and the release channel. Use the cluster’s name as the runner ID for clarity:

cwic sandbox runner create [RUNNER-ID]

Provide a runner spec in YAML. Replace [ZONE] and [CLUSTER-NAME] with the availability zone and name of the CKS cluster you want to enable, and [TEMPLATE-ID] with the ID printed by cwic sandbox profile create. To look up an existing template’s ID, run cwic sandbox profile list:

identity:
  zone: [ZONE]
  cluster_name: [CLUSTER-NAME]
managed_spec:
  release_channel: RELEASE_CHANNEL_STABLE
profile_bindings:
  - profile_template_id: "[TEMPLATE-ID]"
    profile_name: default
    is_default: true

Then submit, passing the runner ID as the positional argument:

cwic sandbox runner create [RUNNER-ID] -f runner.yaml

Run your first sandbox

Wait for the runner to reach the Ready state before you send sandbox requests:

Cloud console: Open the cluster’s Sandbox runner card and watch the status badge until it shows Ready.
CLI: Run cwic sandbox runner get [RUNNER-ID] and look for INSTALL to be READY. For a longer view, use cwic sandbox runner describe [RUNNER-ID].

Once the runner is Ready, anyone in your organization with a CoreWeave API access token can create sandboxes against it. To install the SDK, run:

uv pip install cwsandbox

Generate a CoreWeave API access token from the Tokens page in the cloud console, copy the Token Secret value, and set it as CWSANDBOX_API_KEY. For more information, see Manage API Access Tokens.

export CWSANDBOX_API_KEY="[YOUR-ACCESS-TOKEN]"

Run a sandbox that prints “Hello!”:

from cwsandbox import Sandbox

with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "Hello!"]).result()
    print(result.stdout)

If the command succeeds, Hello! appears in the output. This example does the following:

Sandbox.run() creates a sandbox using the runner’s default profile and returns it inside a context manager. The sandbox tears down on context exit.
exec() runs a command inside the sandbox and returns a Process object.
.result() waits for the command to complete and returns the output.

For more SDK patterns, see the Python client documentation. Notable guides include RL training, SWE-bench evaluation, and the sandbox lifecycle guide.

Disable the runner

When you no longer need sandboxes on the cluster, disable the runner. The runner is removed from the cluster and stops accepting sandbox requests. Stop running sandboxes from the Python client before you disable the runner if you need clean teardown.

Cloud console
CLI

Open the cluster’s Sandbox runner card.
Click Disable sandbox runner and confirm.

cwic sandbox runner delete [RUNNER-ID]

Next steps

The following resources cover next steps:

The Python client page introduces the SDK and links into reference material.
The Python client tutorial walks through configuration, command execution, file operations, and cleanup.
The Python client guides cover lifecycle, streaming, RL training, SWE-bench, SUNK integration, and other advanced topics.

Python Client

Documentation Index

​Prerequisites

​Create a profile

​Enable a runner on a CKS cluster

​Run your first sandbox

​Disable the runner

​Next steps

Prerequisites

Create a profile

Enable a runner on a CKS cluster

Run your first sandbox

Disable the runner

Next steps