> ## 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. # Deploy and manage a runner > Deploy a runner on a CKS cluster, check its health, update its configuration, and delete it. A **managed runner** is the CoreWeave-managed component that runs sandboxes inside your CKS cluster. This page covers the full lifecycle: deploy a runner, confirm it is healthy, adjust its configuration as your needs change, and remove it when you no longer need it. For where the runner sits in the sandbox architecture and how the gateway brokers requests to it, see [Sandboxes architecture](/products/sandboxes/architecture). {/* */} 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). ## 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](https://console.coreweave.com/tokens) page in the cloud console and copy the **Token Secret** value. For more on tokens, see [Manage API access tokens](/security/authn-authz/manage-api-access-tokens). **CLI**: install the [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`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. You don't need to set an environment variable. ```bash theme={"system"} cwic auth login ``` **`curl`**: export the token in your shell so the examples on this page can pick it up: ```bash theme={"system"} export TOKEN="[YOUR-ACCESS-TOKEN]" ``` ## Runner commands The `cwic sandbox runner` group manages runners. The following table maps each lifecycle task to the command that performs it. Later sections walk through these commands in context. | Goal | Command | | --------------------------- | ------------------------------------------------------- | | Deploy a runner (wizard) | `cwic sandbox runner create [RUNNER-ID]` | | Deploy 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. ## Deploy a runner Each CKS cluster hosts at most one managed runner. To deploy one, 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](https://console.coreweave.com/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. The wizard collects cluster, profiles, release channel, and maintenance windows interactively, then opens your editor with a pre-filled spec before submitting: ```bash theme={"system"} 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 good fit for agents like Claude Code or Codex that generate runner specs on your behalf. The CLI also reads from stdin with `-f -`. ```yaml title="runner.yaml" theme={"system"} 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: ```bash theme={"system"} cwic sandbox runner create prod-us-east-1 -f runner.yaml ``` ```bash title="Deploy a managed 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": "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. Use it 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](https://console.coreweave.com/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](https://console.coreweave.com/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](/products/sandboxes/profiles/configure#create-a-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](#update-a-runner), or [delete it](#delete-a-runner) first. | ## Check runner status After creation, check the runner's status to confirm it rolled out successfully and to diagnose problems if it did not. ```bash theme={"system"} cwic sandbox runner describe prod-us-east-1 ``` For a quick summary in tabular form, use the alias `get`: ```bash theme={"system"} 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. ```bash title="Fetch a runner" theme={"system"} 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`: ```json theme={"system"} { "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. Internally, updates use a field mask: only the fields you change are applied. Everything else is read-only, including `installStatus`, `connectionStatus`, timestamps, and the resolved deployment spec. 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 The following examples show the most frequent edits applied to a runner: switching release channels, attaching another profile, and tuning where the runner pod lands in your cluster. #### Example: switch release channel Apply a one-line patch from stdin: ```bash theme={"system"} 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: ```yaml title="patch.yaml" theme={"system"} managed_spec: release_channel: RELEASE_CHANNEL_RAPID ``` ```bash theme={"system"} cwic sandbox runner edit prod-us-east-1 -f patch.yaml ``` ```bash title="Move a runner to the RAPID channel" theme={"system"} 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: ```yaml title="bindings.yaml" theme={"system"} profile_bindings: - profile_template_id: "[DEFAULT-PROFILE-ID]" profile_name: default is_default: true - profile_template_id: "[GPU-PROFILE-ID]" profile_name: gpu ``` ```bash theme={"system"} cwic sandbox runner edit prod-us-east-1 -f bindings.yaml ``` ```bash title="Attach an additional profile" theme={"system"} 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 pod requires 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](/products/sandboxes/profiles/sunk-integration) for the available annotations and required setup. ```yaml title="overrides.yaml" theme={"system"} managed_spec: overrides: node_selector: node-pool: system tolerations: - key: dedicated operator: Equal value: system effect: NoSchedule ``` ```bash theme={"system"} cwic sandbox runner edit prod-us-east-1 -f overrides.yaml ``` ```bash title="Pin the runner to a specific node pool" theme={"system"} 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: ```bash theme={"system"} cwic sandbox runner upgrade prod-us-east-1 ``` ```bash title="Apply an available update immediately" theme={"system"} 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 To see every runner in your organization, or to narrow the view to a specific zone, cluster, or connection state, use the following list commands. ```bash theme={"system"} cwic sandbox runner get ``` Filter by zone, cluster, or connection status: ```bash theme={"system"} cwic sandbox runner get --zone us-east-1 cwic sandbox runner get --connection-status CONNECTED ``` ```bash title="List managed runners" theme={"system"} 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 Remove a runner when you no longer need sandbox capacity on its cluster, or before you redeploy a fresh runner on the same cluster. ```bash theme={"system"} cwic sandbox runner delete prod-us-east-1 ``` The CLI prompts for confirmation. Pass `--yes` to skip the prompt for scripted use: ```bash theme={"system"} cwic sandbox runner delete prod-us-east-1 --yes ``` ```bash title="Decommission a runner" theme={"system"} 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. ## See also * [Sandboxes architecture](/products/sandboxes/architecture): the four-resource taxonomy, control plane compared to data plane, and multi-cluster topology. * [Understanding profiles](/products/sandboxes/profiles/profiles): how profiles, bindings, and overrides combine at sandbox launch. * [Configure a sandbox profile](/products/sandboxes/profiles/configure): `cwic` workflow plus field-by-field walkthrough of the profile spec. * [Control plane API overview](/products/sandboxes/reference/control-plane-api): authentication, field masks, and the request and response shapes for every endpoint. * [Profile reference](/products/sandboxes/reference/profile): every field you can set on a profile.