Discover available infrastructure

Use the discovery API to list available runners and profiles, filter by hardware and networking capabilities, and check live resource capacity before you create sandboxes. Runners are deployments in CKS clusters. Runners register with CoreWeave’s managed control plane and bridge cluster compute into the sandbox platform. Runner capabilities reflect the underlying cluster hardware. Infrastructure administrators configure profiles on runners to set guardrails for networking modes, GPU types, and other capabilities. Every sandbox lands on a profile. You can target specific profiles to control where your sandboxes run.

List available profiles

Profiles describe the runner capabilities and guardrails a sandbox runs under. List them first to decide where to place a sandbox. Use list_profiles() to query profiles and their capabilities:

import cwsandbox
from cwsandbox import Profile

profiles: list[Profile] = cwsandbox.list_profiles()

for p in profiles:
    ingress = ", ".join(m.name for m in p.ingress_modes)
    egress = ", ".join(m.name for m in p.egress_modes)
    print(f"{p.profile_name}  runner={p.runner_id}")
    print(f"  ingress: {ingress}")
    print(f"  egress:  {egress}")

Filter by networking

Pass networking filters to list_profiles() to narrow results to profiles that support a specific ingress and egress combination:

import cwsandbox

profiles = cwsandbox.list_profiles(
    egress_mode="internet",
    ingress_mode="public",
)

for p in profiles:
    print(f"{p.profile_name}  runner={p.runner_id}")

The API applies every filter together with logical AND, so this call returns only profiles that support both internet egress and public ingress.

Parameters

The following parameters are available on list_profiles():

Parameter	Type	Description
`gpu_type`	`str`	Only return profiles that support this GPU type.
`architecture`	`str`	Only return profiles that support this CPU architecture.
`runner_id`	`str`	Only return profiles belonging to this runner.
`ingress_mode`	`str`	Only return profiles that support this ingress mode.
`egress_mode`	`str`	Only return profiles that support this egress mode.

Get a single profile

Use get_profile() to fetch a specific profile by name:

import cwsandbox
from cwsandbox import ProfileNotFoundError

try:
    profile = cwsandbox.get_profile("default")
    print(f"{profile.profile_name}  runner={profile.runner_id}")
except ProfileNotFoundError as e:
    print(f"Profile not found: {e.profile_name}")

Optionally scope the lookup to a specific runner with the runner_id parameter.

List available runners

List runners to see which clusters are registered, what hardware they expose, and how much capacity is free before you target one. Use list_runners() to query runners and their capabilities:

import cwsandbox
from cwsandbox import Runner

runners: list[Runner] = cwsandbox.list_runners()

for runner in runners:
    print(runner)

Runner objects have a built-in representation that shows the runner ID, health status, CPU and memory in human-readable units, GPU count, and profile list.

Check resource availability

Pass include_resources=True to include live resource data on each runner. Use format_bytes() and format_cpu() to display values in human-readable units:

import cwsandbox
from cwsandbox import format_bytes, format_cpu

runners = cwsandbox.list_runners(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:
        avail_cpu = format_cpu(r.resources.available_cpu_millicores)
        avail_mem = format_bytes(r.resources.available_memory_bytes)
        print(f"  available: {avail_cpu}, {avail_mem}")
        print(f"  running sandboxes: {r.resources.running_sandboxes}")

Filter by capacity

Use capacity filters to find runners that have enough free resources. These filters enable include_resources automatically.

import cwsandbox
from cwsandbox import format_bytes, format_cpu

runners = cwsandbox.list_runners(
    min_available_cpu_millicores=2000,
    min_available_memory_bytes=4 * 1024**3,
)

for r in runners:
    if r.resources:
        print(f"{r.runner_id}")
        print(f"  cpu: {format_cpu(r.resources.available_cpu_millicores)}")
        print(f"  memory: {format_bytes(r.resources.available_memory_bytes)}")

Parameters

The following parameters are available on list_runners():

Parameter	Type	Description
`runner_group_id`	`str`	Restrict results to this runner group.
`profile_name`	`str`	Only return runners that have this profile.
`gpu_type`	`str`	Only return runners that support this GPU type.
`architecture`	`str`	Only return runners that support this CPU architecture.
`include_resources`	`bool`	Include live resource availability on each runner. Defaults to `False`.
`min_available_cpu_millicores`	`int`	Minimum unreserved CPU millicores. Enables `include_resources` automatically.
`min_available_memory_bytes`	`int`	Minimum unreserved memory bytes. Enables `include_resources` automatically.
`min_available_gpu_count`	`int`	Minimum unreserved GPU count. Enables `include_resources` automatically.
`ingress_mode`	`str`	Only return runners whose profiles support this ingress mode.
`egress_mode`	`str`	Only return runners whose profiles support this egress mode.

Get a single runner

Use get_runner() to fetch a specific runner by ID. The call always returns full runner details, including resource availability:

import cwsandbox
from cwsandbox import RunnerNotFoundError

try:
    runner = cwsandbox.get_runner("runner-abc-123")
    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}")

Create a sandbox from discovery results

After you select a profile, pass it directly into sandbox creation to control where the sandbox runs. Each Profile exposes profile_name as its identifier. Pass that value to the profile_ids parameter on Sandbox.run() or SandboxDefaults.

Target a profile directly

Pass a discovered profile name to Sandbox.run() through the profile_ids parameter:

import cwsandbox
from cwsandbox import Sandbox

profiles = cwsandbox.list_profiles(egress_mode="internet")

if profiles:
    profile = profiles[0]
    with Sandbox.run(profile_ids=[profile.profile_name]) as sandbox:
        result = sandbox.exec(["curl", "-s", "https://httpbin.org/ip"]).result()
        print(result.stdout)

Use discovery with NetworkOptions

Filter profiles by networking capabilities, then configure the sandbox with matching NetworkOptions:

import cwsandbox
from cwsandbox import NetworkOptions, Sandbox

profiles = cwsandbox.list_profiles(
    egress_mode="internet",
    ingress_mode="public",
)

if profiles:
    profile = profiles[0]
    with Sandbox.run(
        profile_ids=[profile.profile_name],
        network=NetworkOptions(egress_mode="internet"),
    ) as sandbox:
        result = sandbox.exec(["echo", "connected"]).result()
        print(result.stdout)

Set profile in SandboxDefaults

Use SandboxDefaults to apply a discovered profile to all sandboxes in a session:

import cwsandbox
from cwsandbox import SandboxDefaults, Session

profiles = cwsandbox.list_profiles(egress_mode="internet")

if profiles:
    profile = profiles[0]
    defaults = SandboxDefaults(profile_ids=(profile.profile_name,))

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

For additional sandbox configuration options, see the sandbox configuration guide.

Error reference

Discovery calls can raise the following exceptions. Use them to handle missing resources and authentication failures in your code.

Exception	Cause
`RunnerNotFoundError`	No runner with the given ID.
`ProfileNotFoundError`	No profile matching the name and optional `runner_id`.
`DiscoveryError`	Network or service error during a discovery operation.
`CWSandboxAuthenticationError`	Invalid or missing credentials.

For the full exception hierarchy, see the exceptions reference. For common troubleshooting steps, see the troubleshooting guide.

​List available profiles

​Filter by networking

​Parameters

​Get a single profile

​List available runners

​Check resource availability

​Filter by capacity

​Parameters

​Get a single runner

​Create a sandbox from discovery results

​Target a profile directly

​Use discovery with NetworkOptions

​Set profile in SandboxDefaults

​Error reference

List available profiles

Filter by networking

Parameters

Get a single profile

List available runners

Check resource availability

Filter by capacity

Parameters

Get a single runner

Create a sandbox from discovery results

Target a profile directly

Use discovery with NetworkOptions

Set profile in SandboxDefaults

Error reference