Get started with CoreWeave sandboxes

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

Create a profile
Deploy a runner
Run your first sandbox from the Python client
Delete 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 deploy the runner. The researcher step runs sandboxes against it. For background on the components and how they fit together, see About CoreWeave sandboxes. Each admin step below shows the same operation through the CoreWeave Intelligent CLI (cwic) and through direct curl calls against the control plane REST API. Pick whichever fits your workflow. The wizard and from-file cwic tabs are equivalent; the from-file and curl tabs accept YAML or JSON bodies, which makes them a natural interface for CI scripts and for agents (such as Claude Code or Codex) that author profile and runner specs on your behalf.

CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, reach out to CoreWeave Support, or email support@coreweave.com.

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. Note the cluster’s zone and name; both are reused below.
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.
A CoreWeave API access token. Generate one from the Tokens page in the cloud console and copy the Token Secret value. For more on tokens, see Manage API Access Tokens.

Then set up your preferred interface:

cwic
curl

Install the CoreWeave Intelligent CLI (cwic), then sign in with the token:

cwic auth login

The token is stored in your local cwic config; subsequent cwic commands read it automatically. There is no environment variable to set.

Export the token so the examples on this page can pick it up:

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

curl and (optional) jq for pretty-printing responses are the only other requirements.

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. Create one before you deploy 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. For namespace strategies, ingress, pod placement, and binding management, see Configure a sandbox profile. The cwic from-file tab uses this YAML body. Save it as 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

cwic wizard
cwic from file
curl

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 profile’s ID. Reference it when you deploy a runner from a file.

POST the profile spec as JSON. A successful response includes the new profile’s id; capture it for the next step.

Create a profile

curl -X POST https://api.coreweave.com/v1beta2/sandbox/profile-templates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileTemplate": {
      "displayName": "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" }
            }
          }
        }
      }
    }
  }'

export PROFILE_ID="[ID-FROM-RESPONSE]"

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

Deploy a runner on a CKS cluster

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

Cloud console
cwic wizard
cwic from file
curl

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

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

The console binds the first profile returned for your organization as the default. If you created exactly one 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 profiles to bind, which profile 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 deploy a runner on, and [PROFILE-ID] with the ID printed by cwic sandbox profile create. To look up an existing profile’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: "[PROFILE-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

POST the runner spec as JSON. Replace [RUNNER-ID] with a stable identifier (for example, prod-us-east-1), and [ZONE] and [CLUSTER-NAME] with the zone and cluster name from the Prerequisites. $PROFILE_ID comes from the curl tab on the previous step.

Deploy a runner

curl -X POST https://api.coreweave.com/v1beta2/sandbox/managed-runners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runnerId": "[RUNNER-ID]",
    "runner": {
      "identity": {
        "zone": "[ZONE]",
        "clusterName": "[CLUSTER-NAME]"
      },
      "managedSpec": {
        "releaseChannel": "RELEASE_CHANNEL_STABLE"
      },
      "profileBindings": [
        {
          "profileTemplateId": "'"$PROFILE_ID"'",
          "profileName": "default",
          "isDefault": true
        }
      ]
    }
  }'

export RUNNER_ID="[RUNNER-ID]"

For common validation errors, see Deploy and manage a runner.

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.
cwic: 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].

curl: Poll the runner until installStatus is READY:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.coreweave.com/v1beta2/sandbox/managed-runners/$RUNNER_ID" \
  | jq '{installStatus, connectionStatus}'

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
cwic
curl

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

cwic sandbox runner delete [RUNNER-ID]

curl -X DELETE https://api.coreweave.com/v1beta2/sandbox/managed-runners/$RUNNER_ID \
  -H "Authorization: Bearer $TOKEN"

DELETE is idempotent. A second call against the same runner returns 404 NOT_FOUND with no side effects.

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.

Documentation Index

​Prerequisites

​Create a profile

​Deploy a runner on a CKS cluster

​Run your first sandbox

​Disable the runner

​Next steps

Prerequisites

Create a profile

Deploy a runner on a CKS cluster

Run your first sandbox

Disable the runner

Next steps