Skip to main content
The control plane exposes a REST API for managing runners and the policy each one carries. This page covers authentication, versioning, error shapes, pagination, and updates for the managed-runner endpoints. The generated endpoint reference and OpenAPI specification also cover supported sandbox data plane and sandbox template operations. For per-endpoint request bodies, response schemas, and field descriptions, follow the endpoint links in Resource families.

​
Base URL and versioning

This is the control plane base URL. It hosts the runner endpoints documented on this page: deploy runners, set the policy each one carries, and query state. It’s distinct from the sandbox data plane that the cwsandbox Python client uses to start sandboxes and stream commands and output (Sandbox.run(), sb.exec(), file operations). Control plane operations create and configure the infrastructure that produces sandboxes. Data plane operations interact with running sandboxes. The managed-runner endpoints documented here use the v1 URL prefix. An earlier v1beta2 surface remains available and is where profile templates and profile bindings live. Use policy instead of legacy profile bindings when creating or updating a runner through v1. New integrations should target v1.

​
Authentication

All requests use bearer-token authentication over Transport Layer Security (TLS). Replace API_ACCESS_TOKEN with a CoreWeave API access token:
Generate an API access token from the Tokens page in the cloud console. Tokens inherit the permissions of the user they belong to, and the server enforces those permissions on every request. Two Identity and Access Management (IAM) actions apply to CoreWeave Sandboxes. Their identifiers are lowercase and case-sensitive:
  • sandbox_admin: create, read, update, and delete runners, and set the policy they carry. Every managed-runner endpoint requires it, including reads. Implies sandbox_user. On runners using legacy v1beta2 profiles, this action also permits privileged profile settings. These settings include privileged containers, host namespaces, and host filesystem mounts. These settings can give sandboxes Node access comparable to that of a cluster administrator. The v1 policy’s allow_privileged setting governs in-guest privilege within the sandbox’s isolation boundary.
  • sandbox_user: create and operate sandboxes, including their network configurations. It doesn’t grant access to managed-runner administration.
To grant these actions, assign the Sandbox Admin or Sandbox User role on the Access Policies page in the cloud console. The Sandbox Admin role grants sandbox_admin. The Sandbox User role grants sandbox_user. For role descriptions, see IAM roles. For background on how Access Policies work and the step-by-step grant flow, see Identity and Access Management (IAM) and Manage Access Policies. For more on tokens, see Manage API access tokens. Unauthenticated API requests return HTTP 401 Unauthorized. Authentication middleware can return a plain-text body. Don’t assume that every error has a google.rpc.Status body. The CoreWeave Intelligent CLI provides commands for the control plane. In version 1.49.0, cwic sandbox runner commands, including cwic sandbox runner policy, use the v1 API through Connect RPC. Legacy cwic sandbox profile commands use v1beta2 through Connect RPC. These commands share the same --api-url. The REST examples use the HTTP paths documented on this page. Authenticate with cwic auth login. The CLI stores credentials locally using its configured storage backend. See Configure a sandbox policy for the CLI workflow.

​
Content type

REST requests and responses with JSON payloads use:
The API runs over HTTP/2 through Connect, but standard curl or fetch-style clients work transparently. You don’t need a gRPC client. The NetworkConfig API is served on the sandbox data plane at https://api.cwsandbox.com and uses sandbox_user. Use it to change a sandbox’s desired network rules. Use the control plane to set the runner policy that bounds those rules.

​
Resource families

The managed-runner resource family has these endpoints: A policy isn’t independently addressable. It’s a field on the runner, so you read it by fetching the runner. To replace the policy, send the complete document in a runner update masked to policy, together with the etag from the same read. Selecting the root policy path replaces the whole document, including clearing groups omitted from the body. An update that changes policy requires the current etag. A stale value returns FAILED_PRECONDITION. Profile templates remain available on the v1beta2 surface at /v1beta2/sandbox/profile-templates, together with the profile_bindings field on a runner. These legacy fields are rejected by v1 managed-runner writes. Configure the runner policy instead.

​
Pagination

Managed-runner listing supports cursor-based pagination. Other API services have their own pagination limits, documented on their endpoint pages:
  • pageSize: page size. Default 50, max 100.
  • pageToken: cursor returned as nextPageToken on the previous page. An empty string means no more pages.
Replace NEXT_PAGE_TOKEN with the returned nextPageToken:
Paginate managed runners
The CoreWeave Intelligent CLI automatically paginates list commands such as cwic sandbox runner get.

​
Field masks on updates

Managed runner updates on the v1 API accept an optional update_mask to select the mutable fields to update. An omitted or empty mask replaces the whole mutable resource, including policy, so it requires the complete policy and its current etag. The wildcard * is supported only over binary Protobuf, not in the REST updateMask query parameter or JSON requests. Paths use dotted notation and snake_case field names (standard google.protobuf.FieldMask convention). Commonly used mutable paths: The version 1.49.0 CLI builds explicit update masks. File-based runner edits select fields present in the input and group nested fields at supported replacement boundaries. For example, nested policy fields select policy, replacing the entire policy document. Runner YAML uses spec, not the legacy managed_spec, and accepts both Protobuf snake_case and JSON camelCase field names. Exported YAML uses snake_case. Legacy v1beta2 updates infer an omitted or empty mask from mutable field values and message presence instead of replacing the whole mutable resource. The version 1.49.0 profile commands build explicit masks for description, labels, and spec, replacing each selected field as a whole. On the REST surface, supply the mask as a single comma-separated updateMask query parameter. Use the JSON (camelCase) form of each path, and send the resource itself as the request body with no wrapper. Replace RUNNER_ID with the ID of the runner to update:
The runner’s zone and cluster ID are immutable after creation.

​
Runner affinity

The managed runner spec accepts spec.overrides.affinity, a Kubernetes Affinity object with Kubernetes camel case keys. It supports nodeAffinity, podAffinity, and podAntiAffinity. This field controls runner Pods only. It doesn’t change sandbox Pod placement or Node-budget eligibility. The resolved deploymentSpec.affinity is output-only. Affinity updates replace the whole object. With updateMask=spec.overrides.affinity, an explicit "affinity": {} clears all rules, including inherited affinity. Omitting affinity from the request body with the same mask removes the customer override and restores platform defaults. Node selectors and tolerations remain independent. For CLI and REST examples, scheduling behavior, and rollout verification, see Configure runner affinity. The legacy v1beta2 equivalent is managed_spec.overrides.affinity.

​
Errors

RPC errors transcoded to REST use an HTTP status and a google.rpc.Status body, as in the following example. Failures from authentication or authorization middleware, or from an edge service, can use a different body format. Check the HTTP status before decoding the body.
Example output
The following table lists common HTTP-to-RPC code mappings. A failure outside the RPC handler might not include the numeric code in its body: When an error includes structured RPC details, use its code and details for programmatic error handling. Treat the message as explanatory text.

​
Idempotency

Managed-runner operations have the following retry behavior:
  • Deleting an absent runner returns 404 by default. Set allowMissing=true to return a successful empty response when the runner is absent.
  • Create supports an optional requestId idempotency token, at most 128 UTF-8 bytes. Reusing it with the same create content returns the original runner without provisioning again. Reusing it with different content or after the original runner was deleted returns 409 Conflict. Without a token, check the runner with GET before retrying an uncertain create.
  • Send an explicit field mask when updating a runner. If the update changes policy, include the etag captured with that policy. After a stale-ETag error or an uncertain write result, fetch the current runner, reconcile the intended changes, and submit them with the current etag.

​
Heartbeats

Runner health includes connection status and installation status. A runner Get response exposes connectionStatus, installStatus, and lastHeartbeatTime. When a ready runner’s heartbeat becomes stale, the API can report installStatus as RUNNER_INSTALL_STATUS_FAILED with the reason RUNNER_INSTALL_FAILURE_REASON_RUNNER_OFFLINE. The staleness threshold is configurable. Use the status fields and last heartbeat together when checking runner health.

​
See also

For related guidance, see the following pages:

​
OpenAPI specification

The curated OpenAPI 3.0 specification for supported Sandboxes v1 REST endpoints is embedded in the following code block. It covers both data plane and control plane services. Expand the code block by clicking See all at the bottom, or use the download and copy buttons in the title bar.
Sandboxes OpenAPI
Last modified on November 10, 2026