> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discover available infrastructure

> Use the discovery API to find runners, profiles, and capacity before you create sandboxes.

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:

```python theme={"system"}
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:

```python theme={"system"}
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:

```python theme={"system"}
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:

```python theme={"system"}
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:

```python theme={"system"}
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.

```python theme={"system"}
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:

```python theme={"system"}
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:

```python theme={"system"}
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`:

```python theme={"system"}
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:

```python theme={"system"}
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](/products/sandboxes/client/guides/sandbox-configuration).

## 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](/products/sandboxes/client/ref/exceptions/exceptions).
For common troubleshooting steps, see the
[troubleshooting guide](/products/sandboxes/client/guides/troubleshooting).