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. For a walkthrough from enabling a runner to running your first sandbox, see Use your own compute. To manage a runner as infrastructure as code, see Manage runners with Terraform.

Before you begin

The CLI, curl, and Terraform 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. Replace [API-ACCESS-TOKEN] with your CoreWeave API access token:

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

Terraform: install Terraform and the CoreWeave Terraform provider, and use a token with sandbox_admin permission. The deployment example uses provider 0.26.0 or later in the 0.x series. Set the provider’s authentication variable from the token exported in the preceding shell command:

export COREWEAVE_API_TOKEN="$TOKEN"

If your cluster already has a runner, import it into Terraform state before applying. For provider setup and the full Terraform lifecycle, see Manage runners with Terraform.

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

Within your organization, 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. A policy is required to run sandboxes. If you omit it, CoreWeave supplies a default when the runner connects. The policy can supply a default sandbox lifetime; the platform enforces the 30-day maximum. See Configure a sandbox policy.

CLI
curl
Terraform

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 -. Replace [CLUSTER-NAME] with the name of the CKS cluster to deploy the runner on:

runner.yaml

identity:
  zone: us-east-1
  cluster_name: [CLUSTER-NAME]
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:
      default_lifetime_seconds: 3600

Submit the spec:

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

Replace [CLUSTER-ID] with the ID of the CKS cluster to deploy the runner on:

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": "[CLUSTER-ID]"
    },
    "spec": {
      "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": { "defaultLifetimeSeconds": 3600 }
      }
    }
  }'

Save the following configuration in a main.tf file. Replace [CLUSTER-ID] with your CKS cluster UUID and [ZONE] with its Availability Zone. The resource requires an explicit policy object.

main.tf

terraform {
  required_providers {
    coreweave = {
      source  = "coreweave/coreweave"
      version = "~> 0.26"
    }
  }
}

provider "coreweave" {}

resource "coreweave_sandbox_managed_runner" "runner" {
  runner_id  = "prod-us-east-1"
  cluster_id = "[CLUSTER-ID]"
  zone       = lower("[ZONE]")

  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 = { default_lifetime_seconds = 3600 }
    }
  }
}

output "runner_status" {
  value = {
    install_status    = coreweave_sandbox_managed_runner.runner.install_status
    connection_status = coreweave_sandbox_managed_runner.runner.connection_status
    active_revision   = coreweave_sandbox_managed_runner.runner.active_revision
    target_revision   = coreweave_sandbox_managed_runner.runner.target_revision
  }
}

Review and apply the configuration:

terraform init
terraform validate
terraform plan -out=runner.tfplan
terraform apply runner.tfplan

A successful apply means the API accepted the configuration. Installation continues asynchronously. Use the Terraform example in Check runner status to confirm the rollout completed.Keep Terraform state in a backend with access controls.

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

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.

From the directory containing the deployment configuration, refresh the observed status and read the runner_status output:

terraform plan -refresh-only -out=runner-status.tfplan
terraform apply runner-status.tfplan
terraform output runner_status

The runner is ready when install_status is RUNNER_INSTALL_STATUS_READY, connection_status is RUNNER_CONNECTION_STATUS_CONNECTED, and active_revision equals target_revision. If the rollout is still in progress, refresh again.

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

For a runner managed with Terraform, edit its resource configuration, review terraform plan, and apply the plan. Keep the complete desired policy and overrides in the configuration. Later applies can revert changes made through the CLI or API. For drift and replacement behavior, see Update the Terraform configuration. 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
spec (whole object)
spec.release_channel
spec.maintenance_policy
spec.overrides
spec.overrides.affinity
spec.enforce_resource_limits
policy (whole document)

In the REST API, the PATCH body is the managed runner itself, with no request wrapper, and the field mask travels as the updateMask query parameter. An absent mask, or updateMask=*, replaces the whole mutable resource. Two paths are accepted only on the legacy v1beta2 surface and are rejected by v1 managed-runner writes: profile_bindings (configure policy instead) and spec.allow_privileged_profile_annotations.

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

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

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. A policy update also carries an etag, the opaque revision token the runner returns when you read it. Send the value from the read your edit was based on, not a fresher one. A stale token fails with FAILED_PRECONDITION and changes nothing, so a concurrent edit is reported rather than silently overwritten.

CLI
curl

cwic sandbox runner get prod-us-east-1 -o json > runner.json
jq '.[0].policy' runner.json > policy.json

Edit policy.json, then submit it pinned to the etag from that same read:

cwic sandbox runner policy edit prod-us-east-1 -f policy.json \
  --etag "$(jq -r '.[0].etag' runner.json)"

policy get exports the policy without its etag, and policy edit -f without --etag reads the runner’s current revision as it submits, so neither pins the revision your file came from. Reading the token separately, for example with policy describe after the export, has the same gap: a token newer than your document passes the check and overwrites the change made in between. The cwic sandbox runner edit template avoids the extra step: --print-template exports the mutable settings, the policy, and its etag together, and -f uses the value in the file.

Read the runner to capture both its current policy and its etag:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \
  | jq '{policy, etag}' > policy-and-etag.json

Edit the policy object in that file, then send it back with the etag it came with:

Replace a runner's policy

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @policy-and-etag.json

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

Example: pin node placement through deployment overrides

The 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

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

Example: configure runner affinity

Use spec.overrides.affinity to set Kubernetes node affinity, Pod affinity, or Pod anti-affinity for the runner’s own Pods. The value is a Kubernetes Affinity object, with Kubernetes camel case keys inside it. Runner affinity doesn’t configure sandbox Pod placement or change node budgets. The following example prefers Nodes labeled example.com/capacity-class: on-demand while leaving other eligible Nodes available. Replace this illustrative label with one used by your cluster.

CLI
REST
Terraform

Use a version of the CoreWeave Intelligent CLI that supports runner affinity. If the command reports an unknown affinity field, upgrade the CLI or use the REST example.

Save the affinity patch:

affinity.yaml

spec:
  overrides:
    affinity:
      nodeAffinity:
        preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            preference:
              matchExpressions:
                - key: example.com/capacity-class
                  operator: In
                  values: [on-demand]

Apply it to your runner:

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

An affinity-only patch targets spec.overrides.affinity, preserving other overrides. If the same patch includes other override fields, the CLI replaces the whole spec.overrides object. Include every sibling override you want to keep.

This request replaces affinity while preserving other overrides:

Set runner affinity

curl --fail-with-body -X PATCH \
  'https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=spec.overrides.affinity' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "overrides": {
        "affinity": {
          "nodeAffinity": {
            "preferredDuringSchedulingIgnoredDuringExecution": [
              {
                "weight": 100,
                "preference": {
                  "matchExpressions": [
                    {
                      "key": "example.com/capacity-class",
                      "operator": "In",
                      "values": ["on-demand"]
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }'

Affinity requires a provider release that includes spec.overrides.affinity. Provider 0.26.0 doesn’t include it. Until a supporting release is available, use the REST example and coordinate changes with Terraform to avoid overwriting them in later applies.With a supporting provider installed, add the following attribute inside spec.overrides in your runner resource. Keep any other overrides you need because Terraform replaces the whole overrides object:

Affinity attribute inside spec.overrides

affinity = jsonencode({
  nodeAffinity = {
    preferredDuringSchedulingIgnoredDuringExecution = [{
      weight = 100
      preference = {
        matchExpressions = [{
          key      = "example.com/capacity-class"
          operator = "In"
          values   = ["on-demand"]
        }]
      }
    }]
  }
})

Review and apply the update:

terraform plan -out=runner.tfplan
terraform apply runner.tfplan

To clear all rules, including inherited affinity, set affinity = jsonencode({}). To restore platform defaults, remove the attribute. In either case, retain the other overrides you need. For the complete configuration, see Manage runners with Terraform.

Kubernetes combines preferred affinity with other scheduling scores. This preference doesn’t guarantee on-demand-first placement or move an already running Pod when preferred capacity becomes available. Existing node_selector restrictions still apply. Nodes with NoSchedule or NoExecute taints require matching tolerations. To allow spot fallback, don’t use a node selector that excludes spot Nodes. For a hard placement restriction, use requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms. Required node affinity and node_selector must both match. Terms are combined with logical OR. Expressions within a term are combined with logical AND. Required node affinity participates in runner preflight checks. Kubernetes evaluates preferred affinity and Pod affinity or anti-affinity during scheduling. After an update, use cwic sandbox runner describe prod-us-east-1 to check rollout progress. In the API response, verify that activeRevision matches targetRevision, installStatus is RUNNER_INSTALL_STATUS_READY, and connectionStatus is RUNNER_CONNECTION_STATUS_CONNECTED. The resolved configuration appears in the output-only deploymentSpec.affinity field. Affinity is replaced as a whole, rather than merged rule by rule. To remove all affinity rules, including inherited rules, apply an explicit empty object:

printf '%s\n' 'spec: {overrides: {affinity: {}}}' \
  | cwic sandbox runner edit prod-us-east-1 -f -

To remove the override and restore platform defaults, use affinity: null in an affinity-only CLI patch. For REST, keep updateMask=spec.overrides.affinity and send {"spec":{"overrides":{}}}. Clearing affinity leaves node selectors and tolerations unchanged. The legacy v1beta2 field is managed_spec.overrides.affinity. New integrations use the v1 field spec.overrides.affinity shown here.

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
Terraform

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"

Remove the runner resource and its runner_status output from your Terraform configuration, along with any other references to the resource. Review the deletion plan before applying it:

terraform plan -out=runner.tfplan
terraform apply runner.tfplan

Deleting the resource decommissions the managed runner. The provider waits up to 30 minutes for deletion to complete.

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.

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Deploy and manage a runner

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: configure runner affinity

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: configure runner affinity

​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: configure runner affinity

Example: allow a privileged profile posture

Trigger an on-demand runner update

List runners

Delete a runner

See also