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:

Deploy a runner and set the policy it carries.
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 step deploys the runner and sets its policy. The researcher step runs sandboxes against it. For background on the components and how they fit together, see About CoreWeave sandboxes. Each admin step in the following sections 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 runner and policy documents on your behalf.

CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, 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 in later steps.
The SANDBOX_ADMIN action in Identity and Access Management (IAM), which lets you create runners and set their policy. Create or update an access 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 information about 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. No environment variable is required.

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().

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

Deploy a runner and set its policy

A runner is the Kubernetes workload that schedules sandbox pods on your cluster. CoreWeave operates the runner; you deploy it on a specific cluster. Every runner carries exactly one policy, and a cluster hosts at most one runner, so this policy governs every sandbox on the cluster. The policy states what sandboxes may request and what they get by default. A policy must bound sandbox lifetime. The following example policy denies all outbound network access and caps sandboxes at one hour. Adjust it for your environment: widen allowedEgress to permit specific destinations, and raise the resource ceilings as needed. For every constraint group, see Configure a sandbox policy. Save it as policy.json:

policy.json

{
  "displayName": "default",
  "constraints": {
    "resources": {
      "defaultCpu": "1",
      "defaultMemory": "2Gi",
      "maxCpu": "4",
      "maxMemory": "8Gi",
      "requireLimits": true
    },
    "network": {
      "defaultEgress": []
    },
    "security": {
      "allowPrivileged": false,
      "allowedRuntimeClasses": ["kata-qemu"],
      "defaultCpuRuntimeClass": "kata-qemu"
    },
    "lifecycle": { "maxLifetimeSeconds": 3600, "defaultLifetimeSeconds": 900 }
  }
}

Cloud console
cwic
curl

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 card transitions through Pending to Ready. The runner then accepts sandbox requests.Set the policy afterward with cwic or curl, using one of the following tabs.

Create the runner. The wizard prompts for a CKS cluster and the release channel. Use the cluster’s name as the runner ID for clarity:

cwic sandbox runner create [RUNNER-ID]

Then set the policy it carries:

cwic sandbox runner policy edit [RUNNER-ID] -f policy.json

Confirm what the runner is now governed by:

cwic sandbox runner policy describe [RUNNER-ID]

POST the runner with its policy inline. 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.

Deploy a runner with a policy

curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": {
      "runnerId": "[RUNNER-ID]",
      "zone": "[ZONE]",
      "clusterName": "[CLUSTER-NAME]"
    },
    "managedSpec": {
      "releaseChannel": "RELEASE_CHANNEL_STABLE"
    },
    "policy": '"$(cat policy.json)"'
  }'

export RUNNER_ID="[RUNNER-ID]"

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

The runner is now deploying on the cluster. The next step confirms it’s ready before sending sandbox requests.

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/v1/sandbox/managedRunners/$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. The remaining steps cover the researcher workflow: install the Python SDK, set an API token, and run a sandbox against the runner.

The Python client currently targets the v1beta2 API, so it does not yet reach the v1 policy model. A policy you set on a runner governs sandboxes created through the v1 API; sandboxes created through the Python client follow the v1beta2 path and its profile bindings until the client is updated. Plan guardrails for client-created sandboxes accordingly.

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 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.

This example doesn’t set a lifetime, so the sandbox runs for at most 10 minutes before the platform terminates it. The default keeps a forgotten sandbox from running indefinitely. For anything longer, including a long-lived development sandbox, set max_lifetime_seconds explicitly when you create the sandbox:

with Sandbox.run(max_lifetime_seconds=7200) as sandbox:  # 2 hours
    ...

You can’t extend the lifetime after a sandbox starts. For the full set of timeout settings, see Timeouts.

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. For a clean teardown, stop running sandboxes from the Python client before you disable the runner.

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/v1/sandbox/managedRunners/$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.

​Prerequisites

​Deploy a runner and set its policy

​Run your first sandbox

​Disable the runner

​Next steps

Prerequisites

Deploy a runner and set its policy

Run your first sandbox

Disable the runner

Next steps