> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with CoreWeave sandboxes

> Create a profile, deploy a runner on a CKS cluster, and run your first sandbox.

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](/products/sandboxes).

Each admin step in the following sections shows the same operation through the [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`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.

<Note>
  CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, [CoreWeave Support](https://cloud.coreweave.com/contact), or email [support@coreweave.com](mailto:support@coreweave.com).
</Note>

## 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](https://console.coreweave.com/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 profiles and runners. Create or update a policy that grants this action on the [Access Policies](https://console.coreweave.com/organization/iam/access-policies) page in the cloud console. {/* TODO: link to a sandboxes IAM walkthrough once that page is published */}
* A CoreWeave API access token. Generate one from the [Tokens](https://console.coreweave.com/tokens) page in the cloud console and copy the **Token Secret** value. For more information about tokens, see [Manage API Access Tokens](/security/authn-authz/manage-api-access-tokens).

Then set up your preferred interface:

<Tabs>
  <Tab title="cwic">
    Install the [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`cwic`), then sign in with the token:

    ```bash theme={"system"}
    cwic auth login
    ```

    The token is stored in your local cwic config. Subsequent cwic commands read it automatically. No environment variable is required.
  </Tab>

  <Tab title="curl">
    Export the token so the examples on this page can pick it up:

    ```bash theme={"system"}
    export TOKEN="[YOUR-ACCESS-TOKEN]"
    ```

    `curl` and (optional) `jq` for pretty-printing responses are the only other requirements.
  </Tab>
</Tabs>

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](/security/authn-authz/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 following example profile 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](/products/sandboxes/profiles/configure).

The cwic from-file tab uses this YAML body. Save it as `profile.yaml`:

```yaml theme={"system"}
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
```

<Tabs>
  <Tab title="cwic wizard">
    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:

    ```bash theme={"system"}
    cwic sandbox profile create
    ```
  </Tab>

  <Tab title="cwic from file">
    Submit the profile YAML directly:

    ```bash theme={"system"}
    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.
  </Tab>

  <Tab title="curl">
    `POST` the profile spec as JSON. A successful response includes the new profile's `id`. Capture it for the next step.

    ```bash title="Create a profile" theme={"system"}
    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" }
                }
              }
            }
          }
        }
      }'
    ```

    ```bash theme={"system"}
    export PROFILE_ID="[ID-FROM-RESPONSE]"
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="Cloud console">
    The cloud console deploy flow requires at least one profile to already exist for your organization. Create a profile before you use this tab.

    1. Open the [Clusters](https://console.coreweave.com/clusters) page in the cloud console.
    2. Select the cluster you want to deploy a runner on.
    3. 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.
  </Tab>

  <Tab title="cwic wizard">
    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:

    ```bash theme={"system"}
    cwic sandbox runner create [RUNNER-ID]
    ```
  </Tab>

  <Tab title="cwic from file">
    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`:

    ```yaml theme={"system"}
    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:

    ```bash theme={"system"}
    cwic sandbox runner create [RUNNER-ID] -f runner.yaml
    ```
  </Tab>

  <Tab title="curl">
    `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.

    ```bash title="Deploy a runner" theme={"system"}
    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
            }
          ]
        }
      }'
    ```

    ```bash theme={"system"}
    export RUNNER_ID="[RUNNER-ID]"
    ```

    For common validation errors, see [Deploy and manage a runner](/products/sandboxes/operations/managed-runners#common-validation-errors).
  </Tab>
</Tabs>

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`:

  ```bash theme={"system"}
  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. The remaining steps cover the researcher workflow: install the Python SDK, set an API token, and run a sandbox against the runner.

To install the SDK, run:

```bash theme={"system"}
uv pip install cwsandbox
```

Generate a CoreWeave API access token from the [Tokens](https://console.coreweave.com/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](/security/authn-authz/manage-api-access-tokens).

```bash theme={"system"}
export CWSANDBOX_API_KEY="[YOUR-ACCESS-TOKEN]"
```

Run a sandbox that prints "Hello!":

```python theme={"system"}
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](/products/sandboxes/client). Notable guides include [RL training](/products/sandboxes/client/guides/rl-training), [SWE-bench evaluation](/products/sandboxes/client/guides/swebench), and the [sandbox lifecycle guide](/products/sandboxes/client/guides/sandbox-lifecycle).

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

<Tabs>
  <Tab title="Cloud console">
    1. Open the cluster's **Sandbox runner** card.
    2. Click **Disable sandbox runner** and confirm.
  </Tab>

  <Tab title="cwic">
    ```bash theme={"system"}
    cwic sandbox runner delete [RUNNER-ID]
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"system"}
    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.
  </Tab>
</Tabs>

## Next steps

The following resources cover next steps:

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