Discover available runners

Use the discovery API to list the runners registered to your organization, read the hardware each one advertises, and check live capacity before you place a sandbox on it. A runner is a deployment in a CKS cluster. It registers with CoreWeave’s managed control plane and bridges the cluster’s compute into the sandbox platform, so a runner’s capabilities reflect the hardware of the cluster behind it. Discovery applies to CKS placement. A serverless sandbox doesn’t run on a runner you own, so there’s nothing to discover: describe the sandbox you want and the platform places it. See Sandbox placement. Discovery reports what a runner is capable of, not what it allows. What an individual sandbox may request is bounded by the policy the runner carries, which an administrator authors. See Policies overview.

Coming from profiles? The client no longer exports Profile, list_profiles(), get_profile(), or ProfileNotFoundError. profile_names and profile_ids survive as parameter names on Sandbox, Session, and their list() methods, but passing a value raises TypeError. Target a runner with runner_ids instead. Policies replaced profiles as the governance model, and you don’t select one: see Policies overview.

List runners

list_runners() returns every runner your credentials can see:

from cwsandbox import AuthStrategy, Runner, list_runners

runners: list[Runner] = list_runners(auth=AuthStrategy.COREWEAVE_API_KEY)

for runner in runners:
    print(runner)

Runner has a built-in representation that prints the runner ID, the owning organization, health, CPU and memory in human-readable units, the GPU count, and the service visibilities the runner can enforce. Sample output:

Runner(runner_id='prod-us-east-1', organization_id='1a2b3c4d', healthy=True, cpu=512.0 vCPU, memory=4.0 TiB, gpus=64, visibilities=['public', 'private'])

Read runner capabilities

Each runner advertises the hardware its Nodes carry. Read these attributes to find a runner that can satisfy the sandbox you want to create:

from cwsandbox import AuthStrategy, list_runners

for runner in list_runners(auth=AuthStrategy.COREWEAVE_API_KEY):
    print(runner.runner_id)
    print(f"  gpu types:     {', '.join(runner.supported_gpu_types) or 'none'}")
    print(f"  max gpus:      {runner.max_gpu_count}")
    print(f"  architectures: {', '.join(runner.supported_architectures)}")
    print(f"  storage:       {', '.join(runner.available_storage_classes)}")

supported_gpu_types holds the exact strings to pass as the type key of a GPU request. Matching is case-sensitive, so B200 and b200 aren’t the same type. See Run a GPU sandbox. max_gpu_count is the runner’s reported aggregate GPU capacity, not a per-sandbox cap. How many GPUs one sandbox may request is bounded by maxGpuCount in the runner’s policy and by the free GPUs on a single Node.

Runner attributes

A Runner carries the following attributes:

Attribute	Type	Description
`runner_id`	`str`	Identifier for the runner within its organization. Not globally unique.
`organization_id`	`str`	Organization that owns the runner.
`runner_group_id`	`str`	Group the runner belongs to.
`tags`	`tuple[str, ...]`	Tags on the runner.
`healthy`	`bool`	Whether the runner is currently healthy.
`is_shared`	`bool`	`True` when the runner belongs to a shared organization.
`connected_at`	`datetime`	When the runner connected, as a UTC-aware datetime.
`max_cpu_millicores`	`int`	Reported aggregate CPU capacity, in millicores.
`max_memory_bytes`	`int`	Reported aggregate memory capacity, in bytes.
`max_gpu_count`	`int`	Reported aggregate GPU capacity.
`supported_gpu_types`	`tuple[str, ...]`	GPU types the runner’s Nodes carry.
`supported_architectures`	`tuple[str, ...]`	CPU architectures the runner supports, such as `amd64`.
`supports_privileged`	`bool`	Whether privileged containers are allowed.
`available_storage_classes`	`tuple[str, ...]`	Kubernetes storage classes available on the cluster.
`supported_service_visibilities`	`tuple[str, ...]`	Service visibilities the runner can enforce: `public`, `private`, or `custom`. See `ServiceVisibility`.
`resources`	`RunnerResources \| None`	Live resource availability, or `None` when the runner doesn’t report it.

A max_* value of 0 can mean the runner doesn’t disclose or report that capacity, not that it has no resources. Shared runners return 0 because their capacity is withheld, and CPU and memory values can exclude reserved capacity.

Check live capacity

By default, list_runners() returns capability data only. Pass include_resources=True to populate Runner.resources with live availability. Use format_bytes() and format_cpu() to print the values in human-readable units:

from cwsandbox import AuthStrategy, format_bytes, format_cpu, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    include_resources=True,
)

for r in runners:
    print(f"{r.runner_id}  healthy={r.healthy}")
    print(f"  max: {format_cpu(r.max_cpu_millicores)}, {format_bytes(r.max_memory_bytes)}")
    if r.resources:
        free_cpu = format_cpu(r.resources.available_cpu_millicores)
        free_mem = format_bytes(r.resources.available_memory_bytes)
        print(f"  free:  {free_cpu}, {free_mem}, {r.resources.available_gpu_count} GPUs")
        print(f"  running sandboxes: {r.resources.running_sandboxes}")

resources is None when a runner doesn’t report availability, so guard on it before you read the values.

RunnerResources attributes

A RunnerResources object carries the following attributes:

Attribute	Type	Description
`available_cpu_millicores`	`int`	Unreserved CPU, in millicores.
`available_memory_bytes`	`int`	Unreserved memory, in bytes.
`available_gpu_count`	`int`	Unreserved GPUs.
`running_sandboxes`	`int`	Sandboxes currently running on the runner.

Filter the list

Combine filters to narrow the list to runners that can take your workload. The following call returns healthy runners that carry a given GPU type and have at least two GPUs free. Replace [GPU-TYPE] with a value from supported_gpu_types:

from cwsandbox import AuthStrategy, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    gpu_type="[GPU-TYPE]",
    healthy_only=True,
    min_available_gpu_count=2,
)

for r in runners:
    print(f"{r.runner_id}: {r.resources.available_gpu_count} GPUs free")

The discovery service applies runner_group_id, gpu_type, architecture, healthy_only, and service_visibility. The client applies the three min_available_* filters after the results arrive. Those three turn on include_resources for you, and they drop any runner that reports no resource data, so resources is always populated on what they return.

Parameters

The following parameters are available on list_runners(). All are keyword-only.

Parameter	Type	Description
`auth`	`AuthConfig \| None`	Authentication strategy, resolved headers, or provider for this request.
`runner_group_id`	`str \| None`	Restrict results to this runner group.
`gpu_type`	`str \| None`	Only return runners that support this GPU type.
`architecture`	`str \| None`	Only return runners that support this CPU architecture.
`healthy_only`	`bool`	Only return healthy runners. Defaults to `False`.
`include_resources`	`bool`	Include live resource availability on each runner. Defaults to `False`.
`min_available_cpu_millicores`	`int \| None`	Minimum unreserved CPU millicores. Enables `include_resources` automatically.
`min_available_memory_bytes`	`int \| None`	Minimum unreserved memory bytes. Enables `include_resources` automatically.
`min_available_gpu_count`	`int \| None`	Minimum unreserved GPU count. Enables `include_resources` automatically.
`service_visibility`	`str \| None`	Only return runners that can enforce this service visibility: `public`, `private`, or `custom`.

Get a single runner

get_runner() takes a runner ID and the organization that owns it. A runner ID is unique within its organization rather than globally, so both are required. The call always returns full details, but resource availability is included only for runners your organization owns. Replace [RUNNER-ID] and [ORGANIZATION-ID] with the runner you want and the organization that owns it:

from cwsandbox import AuthStrategy, RunnerNotFoundError, get_runner

try:
    runner = get_runner(
        "[RUNNER-ID]",
        organization_id="[ORGANIZATION-ID]",
        auth=AuthStrategy.COREWEAVE_API_KEY,
    )
    print(f"{runner.runner_id}  healthy={runner.healthy}")
    if runner.resources:
        print(f"  running sandboxes: {runner.resources.running_sandboxes}")
except RunnerNotFoundError as e:
    print(f"Runner not found: {e.runner_id}")

Every runner you list carries its own organization_id, so pass runner.organization_id when you look up a runner you found in an earlier result.

Create a sandbox on a discovered runner

Set placement_mode="cks" and pass the runner you selected to runner_ids. Replace [GPU-TYPE] with a value from supported_gpu_types:

from cwsandbox import AuthStrategy, ResourceOptions, Sandbox, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    gpu_type="[GPU-TYPE]",
    min_available_gpu_count=1,
)

if runners:
    with Sandbox.run(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=[runners[0].runner_id],
        resources=ResourceOptions(
            requests={"cpu": "2", "memory": "8Gi"},
            limits={"cpu": "2", "memory": "8Gi"},
            gpu={"count": 1, "type": "[GPU-TYPE]"},
        ),
        max_lifetime_seconds=3600,
    ) as sandbox:
        print(sandbox.exec(["nvidia-smi", "-L"]).result().stdout)

Without runner_ids, CKS placement can use any eligible runner in your organization. runner_ids is incompatible with serverless placement and with placement_spillover="serverless_then_cks".

Apply a runner to every sandbox in a session

Use SandboxDefaults to send every sandbox in a session to the same runner:

from cwsandbox import AuthStrategy, SandboxDefaults, Session, list_runners

runners = list_runners(auth=AuthStrategy.COREWEAVE_API_KEY, healthy_only=True)

if runners:
    defaults = SandboxDefaults(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=(runners[0].runner_id,),
    )

    with Session(defaults) as session:
        sb = session.sandbox()
        print(sb.exec(["echo", "running on a discovered runner"]).result().stdout)

For the rest of the sandbox options, see the sandbox configuration guide.

Error reference

Discovery calls can raise the following exceptions.

Exception	Cause
`RunnerNotFoundError`	No runner matches the given `runner_id` and `organization_id`.
`DiscoveryValidationError`	A discovery request failed field-level validation.
`DiscoveryError`	Network or service error during a discovery operation. Base class for the two above.
`CWSandboxAuthenticationError`	Invalid or missing credentials.

When runner_id or organization_id is empty, get_runner() raises ValueError before it makes a request. For the full exception hierarchy, see the exceptions reference. For common troubleshooting steps, see the Sandboxes support articles.

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Discover available runners

List runners

Read runner capabilities

Runner attributes

Check live capacity

RunnerResources attributes

Filter the list

Parameters

Get a single runner

Create a sandbox on a discovered runner

Apply a runner to every sandbox in a session

Error reference

​List runners

​Read runner capabilities

​Runner attributes

​Check live capacity

​RunnerResources attributes

​Filter the list

​Parameters

​Get a single runner

​Create a sandbox on a discovered runner

​Apply a runner to every sandbox in a session

​Error reference

List runners

Read runner capabilities

Runner attributes

Check live capacity

RunnerResources attributes

Filter the list

Parameters

Get a single runner

Create a sandbox on a discovered runner

Apply a runner to every sandbox in a session

Error reference