Create and manage a runner

A managed runner is the CoreWeave-managed component that runs sandboxes inside your CKS cluster. This page covers the full lifecycle: register a runner, confirm it is healthy, adjust its configuration as your needs change, and remove it when you no longer need it.

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

Before you begin

Both the CLI and the curl examples on this page authenticate with 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. CLI: install the CoreWeave Intelligent CLI (cwic), then run cwic auth login and paste the token when prompted. The token is stored in your local cwic config; subsequent commands read it automatically. There is no environment variable to set.

cwic auth login

curl: export the token in your shell so the examples on this page can pick it up:

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

Runner commands

The cwic sandbox runner group manages runners.

Goal	Command
Create a runner (wizard)	`cwic sandbox runner create [RUNNER-ID]`
Create a runner from a file	`cwic sandbox runner create [RUNNER-ID] -f runner.yaml`
List runners	`cwic sandbox runner get` (alias `ls`)
Inspect one runner	`cwic sandbox runner get [RUNNER-ID]`
Detailed view	`cwic sandbox runner describe [RUNNER-ID]`
Edit a runner	`cwic sandbox runner edit [RUNNER-ID]`
Apply an available update	`cwic sandbox runner upgrade [RUNNER-ID]`
Delete a runner	`cwic sandbox runner delete [RUNNER-ID]`

All input accepts YAML or JSON.

Create a runner

Each CKS cluster hosts at most one managed runner. On create you must supply:

Runner ID: a client-assigned human-readable ID, unique within your organization.
Zone: the geographic zone the cluster belongs to.
Cluster ID (or cluster name): which CKS cluster the runner runs on. You can find both on the Clusters page in the cloud console.
Profile bindings: at least one binding, with exactly one default. The profile referenced in each binding must already exist.

CLI
curl

The wizard collects cluster, profiles, release channel, and maintenance windows interactively, then opens your editor with a pre-filled spec before submitting:

cwic sandbox runner create prod-us-east-1

File mode accepts YAML or JSON, which makes it the preferred path for repeatable setups and a natural interface for agents like Claude Code or Codex that generate runner specs on your behalf (the CLI also reads from stdin with -f -):

runner.yaml

identity:
  zone: us-east-1
  cluster_name: [YOUR-CKS-CLUSTER-NAME]
managed_spec:
  release_channel: RELEASE_CHANNEL_STABLE
  maintenance_policy:
    windows:
      - cron: "0 9 * * SAT"
        duration_seconds: 14400
profile_bindings:
  - profile_template_id: "[PROFILE-ID]"
    profile_name: default
    is_default: true

Submit the spec:

cwic sandbox runner create prod-us-east-1 -f runner.yaml

Create a managed runner

curl -X POST https://api.coreweave.com/v1beta2/sandbox/managed-runners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runnerId": "prod-us-east-1",
    "runner": {
      "displayName": "Production runner (US East)",
      "identity": {
        "zone": "us-east-1",
        "clusterId": "[YOUR-CKS-CLUSTER-ID]"
      },
      "managedSpec": {
        "releaseChannel": "RELEASE_CHANNEL_STABLE",
        "maintenancePolicy": {
          "windows": [
            { "cron": "0 9 * * SAT", "durationSeconds": 14400 }
          ]
        }
      },
      "profileBindings": [
        { "profileTemplateId": "[PROFILE-ID]", "profileName": "default", "isDefault": true }
      ]
    }
  }'

Note the following behaviors:

maintenance_policy.windows is optional. When set, automatic updates apply only during the specified cron windows.
runner_group_id is optional and is used for scheduling affinity when you have multiple runners in the same zone.

Common validation errors

Error	Fix
`runner.identity.zone is required`	Supply a zone. Find zones where you have a CKS cluster (and therefore quota for a runner) on the Clusters page in the cloud console, or by running `cwic cluster get`.
`runner.identity.cluster_id or cluster_name is required`	Supply one. You can find both on the Clusters page in the cloud console, or by running `cwic cluster get`.
`one or more profile_bindings reference a template that does not exist`	Create the profile first, or double-check the ID by running `cwic sandbox profile get [PROFILE-ID]` (or `cwic sandbox profile get` with no args to list all profiles).
`runner cannot have more than one default profile binding`	Exactly one binding must be the default.
`a managed runner already exists for this cluster`	A cluster hosts at most one managed runner. Update the existing one, or delete it first.

Check runner status

After creation, check the runner’s status to confirm it rolled out successfully and to diagnose problems if it didn’t.

CLI
curl

cwic sandbox runner describe prod-us-east-1

For a quick summary in tabular form, use the alias get:

cwic sandbox runner get prod-us-east-1

Either command accepts the runner ID you supplied on create (prod-us-east-1) or the server-assigned UUID.

Fetch a runner

curl -H "Authorization: Bearer $TOKEN" \
  https://api.coreweave.com/v1beta2/sandbox/managed-runners/prod-us-east-1

You can pass either the runner ID you supplied on create or the server-assigned UUID.

The response carries two status fields to track:

installStatus: progress of the runner deployment into your cluster (PENDING, PROVISIONING, READY, or FAILED).
connectionStatus: live connectivity (CONNECTED or DISCONNECTED). The runner’s heartbeat updates this value. Expect up to 30 seconds of lag.

When installStatus == FAILED, the response includes a structured installError:

{
  "installError": {
    "reason": "...",
    "message": "...",
    "remediationHints": ["Add toleration for taint 'workload=gpu:NoSchedule'"],
    "occurredAt": "2026-04-24T12:03:11Z"
  }
}

remediationHints are the actions you should take. diagnosticDetail also contains internal logs that are useful to attach if you open a support ticket.

Update a runner

The runner edit command supports both an interactive wizard and a file-driven patch. Under the hood, updates use a field mask: only the fields you change are applied. Everything else (installStatus, connectionStatus, timestamps, and the resolved deployment spec) is read-only. The following paths are mutable:

identity.zone
identity.runner_group_id
managed_spec (whole object)
managed_spec.release_channel
managed_spec.maintenance_policy
managed_spec.overrides
profile_bindings (whole list)

Common runner updates

Example: switch release channel

CLI
curl

Apply a one-line patch from stdin:

echo 'managed_spec: {release_channel: RELEASE_CHANNEL_RAPID}' \
  | cwic sandbox runner edit prod-us-east-1 -f -

Or write the patch to a file and submit it:

patch.yaml

managed_spec:
  release_channel: RELEASE_CHANNEL_RAPID

cwic sandbox runner edit prod-us-east-1 -f patch.yaml

Move a runner to the RAPID channel

curl -X PATCH https://api.coreweave.com/v1beta2/sandbox/managed-runners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runner": {
      "id": "prod-us-east-1",
      "managedSpec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" }
    },
    "updateMask": "managedSpec.releaseChannel"
  }'

Example: attach a second profile

profile_bindings is replaced as a whole list. To attach a new profile while you preserve the existing default, send both bindings:

CLI
curl

bindings.yaml

profile_bindings:
  - profile_template_id: "[DEFAULT-PROFILE-ID]"
    profile_name: default
    is_default: true
  - profile_template_id: "[GPU-PROFILE-ID]"
    profile_name: gpu

cwic sandbox runner edit prod-us-east-1 -f bindings.yaml

Attach an additional profile

curl -X PATCH https://api.coreweave.com/v1beta2/sandbox/managed-runners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runner": {
      "id": "prod-us-east-1",
      "profileBindings": [
        { "profileTemplateId": "[DEFAULT-PROFILE-ID]", "profileName": "default", "isDefault": true },
        { "profileTemplateId": "[GPU-PROFILE-ID]",     "profileName": "gpu" }
      ]
    },
    "updateMask": "profileBindings"
  }'

The API matches entries by profile_template_id. Missing entries are detached, new entries are attached, and changed entries are updated in place, all in one transaction.

Example: pin node placement through deployment overrides

The managed_spec.overrides field tunes the runner’s own pod, not sandbox pods. Use it when the runner needs specific tolerations, node selectors, or runtime classes to land on the right nodes. A common case is routing the runner pod through the SUNK Pod Scheduler so it can run in your SUNK cluster alongside Slurm jobs. Set the scheduler name and the SUNK annotations on the runner overrides; see SUNK Pod Scheduler integration for the available annotations and required setup.

CLI
curl

overrides.yaml

managed_spec:
  overrides:
    node_selector:
      node-pool: system
    tolerations:
      - key: dedicated
        operator: Equal
        value: system
        effect: NoSchedule

cwic sandbox runner edit prod-us-east-1 -f overrides.yaml

Pin the runner to a specific node pool

curl -X PATCH https://api.coreweave.com/v1beta2/sandbox/managed-runners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runner": {
      "id": "prod-us-east-1",
      "managedSpec": {
        "overrides": {
          "nodeSelector": { "node-pool": "system" },
          "tolerations":  [ { "key": "dedicated", "operator": "Equal", "value": "system", "effect": "NoSchedule" } ]
        }
      }
    },
    "updateMask": "managedSpec.overrides"
  }'

Trigger an on-demand runner update

When updateAvailable is true on the runner, you can apply the update immediately rather than wait for the next maintenance window:

CLI
curl

cwic sandbox runner upgrade prod-us-east-1

Apply an available update immediately

curl -X POST https://api.coreweave.com/v1beta2/sandbox/managed-runners/prod-us-east-1/apply-update \
  -H "Authorization: Bearer $TOKEN"

The control plane resolves the latest version on the runner’s release channel and bumps target_revision. The in-cluster controller rolls it out.

List runners

CLI
curl

cwic sandbox runner get

Filter by zone, cluster, or connection status:

cwic sandbox runner get --zone us-east-1
cwic sandbox runner get --connection-status CONNECTED

List managed runners

curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1beta2/sandbox/managed-runners?pageSize=50&zone=us-east-1'

Supported query parameters: zone, clusterId, connectionStatus, runnerId, managementMode, pageSize (default 50, max 100), and pageToken. Pagination is cursor-based.

Delete a runner

CLI
curl

cwic sandbox runner delete prod-us-east-1

The CLI prompts for confirmation. Pass --yes to skip the prompt for scripted use:

cwic sandbox runner delete prod-us-east-1 --yes

Decommission a runner

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

Deleting a runner tears down the runner deployment in your cluster. Any sandboxes running on that runner stop. The profiles the runner referenced are not deleted; they remain available for other runners.

Deletion is permanent. If you only want to pause traffic, move sandboxes to another runner before you delete this one.

Manage sandboxes

Reference

Python Client

Create and manage a runner

Before you begin

Runner commands

Create a runner

Common validation errors

Check runner status

Update a runner

Common runner updates

Example: switch release channel

Example: attach a second profile

Example: pin node placement through deployment overrides

Trigger an on-demand runner update

List runners

Delete a runner

See also

Manage sandboxes

Reference

Python Client

Documentation Index

​Before you begin

​Runner commands

​Create a runner

​Common validation errors

​Check runner status

​Update a runner

​Common runner updates

​Example: switch release channel

​Example: attach a second profile

​Example: pin node placement through deployment overrides

​Trigger an on-demand runner update

​List runners

​Delete a runner

​See also

Before you begin

Runner commands

Create a runner

Common validation errors

Check runner status

Update a runner

Common runner updates

Example: switch release channel

Example: attach a second profile

Example: pin node placement through deployment overrides

Trigger an on-demand runner update

List runners

Delete a runner

See also