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

CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, 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. You don’t need to set an environment variable.

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. 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]`
Read the runner’s policy	`cwic sandbox runner policy get [RUNNER-ID]`
Edit the runner’s policy	`cwic sandbox runner policy edit [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 page in the cloud console.
Policy: the rules the runner enforces for sandboxes on its cluster. Required, and it must bound sandbox lifetime. See Configure a sandbox policy.

CLI
curl

The wizard collects cluster, 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 good fit 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
policy:
  display_name: default
  constraints:
    resources:
      default_cpu: "1"
      default_memory: "2Gi"
      max_cpu: "4"
      max_memory: "8Gi"
      require_limits: true
    lifecycle:
      max_lifetime_seconds: 3600

Submit the spec:

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

Deploy a managed runner

curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Production runner (US East)",
    "identity": {
      "runnerId": "prod-us-east-1",
      "zone": "us-east-1",
      "clusterId": "[YOUR-CKS-CLUSTER-ID]"
    },
    "managedSpec": {
      "releaseChannel": "RELEASE_CHANNEL_STABLE",
      "maintenancePolicy": {
        "windows": [
          { "cron": "0 9 * * SAT", "durationSeconds": 14400 }
        ]
      }
    },
    "policy": {
      "displayName": "default",
      "constraints": {
        "resources": {
          "defaultCpu": "1",
          "defaultMemory": "2Gi",
          "maxCpu": "4",
          "maxMemory": "8Gi",
          "requireLimits": true
        },
        "lifecycle": { "maxLifetimeSeconds": 3600 }
      }
    }
  }'

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 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`.
`policy must set constraints.lifecycle.max_lifetime_seconds > 0`	Every policy must bound sandbox lifetime so sandboxes self-terminate. Set a positive value.
`policy exceeds 256 KiB limit`	Trim the policy document. The encoded document is capped at 256 KiB.
`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 did not.

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/v1/sandbox/managedRunners/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. 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
managed_spec.allow_privileged_profile_annotations
policy (whole document)
profile_bindings (whole list, legacy, v1beta2 only)

Common runner updates

The following examples show the most frequent edits applied to a runner: switching release channels, replacing the policy it carries, tuning where the runner pod lands in your cluster, and allowing legacy profile templates to carry a privileged posture.

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/v1/sandbox/managedRunners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "managedRunner": {
      "identity": { "runnerId": "prod-us-east-1" },
      "managedSpec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" }
    },
    "updateMask": "managedSpec.releaseChannel"
  }'

Example: replace the policy

The policy is replaced as a whole document. Read the current one, change what you need, and send it back. There is no field-level mask inside policy, so a partial body clears the groups you leave out.

CLI
curl

cwic sandbox runner policy get prod-us-east-1 -o json > policy.json
cwic sandbox runner policy edit prod-us-east-1 -f policy.json

Replace a runner's policy

curl -X PATCH https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "managedRunner": { "policy": '"$(cat policy.json)"' },
    "updateMask": "policy"
  }'

For every constraint group and worked examples, see Configure a sandbox policy.

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 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/v1/sandbox/managedRunners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "managedRunner": {
      "identity": { "runnerId": "prod-us-east-1" },
      "managedSpec": {
        "overrides": {
          "nodeSelector": { "node-pool": "system" },
          "tolerations":  [ { "key": "dedicated", "operator": "Equal", "value": "system", "effect": "NoSchedule" } ]
        }
      }
    },
    "updateMask": "managedSpec.overrides"
  }'

Example: allow a privileged profile posture

allow_privileged_profile_annotations controls whether the legacy profile templates bound to a runner may carry a privileged posture. It applies to runners that still use profile bindings rather than a policy, so the request goes to the v1beta2 surface. It defaults to false, and a template that carries one is rejected on a runner where the flag is not set. Despite the name, the flag governs two kinds of content:

Privileged pod annotations, meaning the runtime and scheduler prefixes.
Privileged structured pod-spec fields, such as serviceAccountName, host namespaces, hostPath volumes, and privileged or escalating containers.

A template that a runner rejects returns permission_denied and names the offending fields. For example, a template that sets securityContext.appArmorProfile and securityContext.seccompProfile fails with the following:

Example output

Error: updating runner: permission_denied: profile_bindings[7]: template
"[TEMPLATE-ID]" contains privileged pod-spec fields
[securityContext.appArmorProfile securityContext.seccompProfile];
runner does not have allow_privileged_profile_annotations=true

Set the flag on the runner that rejected the template. The flag is scoped to one runner, so repeat this for each runner that needs the privileged posture.

CLI
curl

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

Allow a privileged profile posture on one runner

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": { "allowPrivilegedProfileAnnotations": true }
    },
    "updateMask": "managedSpec.allowPrivilegedProfileAnnotations"
  }'

After the update succeeds, reapply the profile template that was rejected.

Setting this flag widens what sandboxes on the runner can do, including reaching host resources. Set it only on runners where the privileged posture is required.

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/v1/sandbox/managedRunners/prod-us-east-1:applyAvailableUpdate \
  -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.

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

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/v1/sandbox/managedRunners/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 policy is part of the runner, so it is deleted with it. Keep the policy document in version control if you intend to redeploy the cluster.

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

​Before you begin

​Runner commands

​Deploy a runner

​Common validation errors

​Check runner status

​Update a runner

​Common runner updates

​Example: switch release channel

​Example: replace the policy

​Example: pin node placement through deployment overrides

​Example: allow a privileged profile posture

​Trigger an on-demand runner update

​List runners

​Delete a runner

​See also

Before you begin

Runner commands

Deploy a runner

Common validation errors

Check runner status

Update a runner

Common runner updates

Example: switch release channel

Example: replace the policy

Example: pin node placement through deployment overrides

Example: allow a privileged profile posture

Trigger an on-demand runner update

List runners

Delete a runner

See also