Découvrir les exécuteurs disponibles

Utilisez l’API de découverte pour répertorier les exécuteurs enregistrés dans votre organisation, consulter le matériel annoncé par chacun d’eux et vérifier leur capacité en temps réel avant d’y placer une sandbox. Un exécuteur est un déploiement dans un cluster CKS. Il s’enregistre auprès du plan de contrôle managé de CoreWeave et met les ressources de calcul du cluster à la disposition de la plateforme de bacs à sable : les capacités d’un exécuteur reflètent donc le matériel du cluster sous-jacent. La découverte s’applique au placement sur CKS. Une sandbox sans serveur ne s’exécute pas sur un exécuteur qui vous appartient : il n’y a donc rien à découvrir. Décrivez simplement la sandbox souhaitée, et la plateforme se charge de la placer. Voir Placement des sandbox. La découverte indique ce dont un exécuteur est capable, et non ce qu’il autorise. Les ressources qu’une sandbox peut demander sont limitées par la politique associée à l’exécuteur, définie par un administrateur. Voir Aperçu des politiques.

Vous utilisiez les profils ? Le client n’exporte plus Profile, list_profiles(), get_profile() ni ProfileNotFoundError. profile_names et profile_ids subsistent en tant que noms de paramètres de Sandbox, de Session et de leurs méthodes list(), mais toute valeur transmise lève une exception TypeError. Ciblez plutôt un exécuteur avec runner_ids. Les politiques ont remplacé les profils comme modèle de gouvernance, et vous n’avez pas à en sélectionner une : voir Aperçu des politiques.

Lister les exécuteurs

list_runners() renvoie tous les exécuteurs accessibles avec vos identifiants d’authentification :

from cwsandbox import AuthStrategy, Runner, list_runners

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

for runner in runners:
    print(runner)

Runner dispose d’une représentation intégrée qui affiche l’identifiant de l’exécuteur, l’organisation propriétaire, l’état de santé, le CPU et la mémoire en unités lisibles, le nombre de GPU, ainsi que les visibilités de service que l’exécuteur peut appliquer. Exemple de sortie :

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

Lire les capacités des exécuteurs

Chaque exécuteur expose le matériel dont disposent ses Nœuds. Lisez ces attributs pour trouver un exécuteur capable de répondre aux besoins de la sandbox que vous souhaitez créer :

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 contient les chaînes de caractères exactes à transmettre comme clé type d’une requête GPU. La correspondance est sensible à la casse : B200 et b200 ne désignent pas le même type. Voir Exécuter un sandbox GPU. max_gpu_count correspond à la capacité GPU agrégée remontée par l’exécuteur, et non à un plafond par sandbox. Le nombre de GPU qu’un sandbox peut demander est limité par maxGpuCount dans la politique de l’exécuteur et par les GPU disponibles sur un même nœud.

Attributs de l’exécuteur

Un Runner possède les attributs suivants :

Attribut	Type	Description
`runner_id`	`str`	Identifiant de l’exécuteur au sein de son organisation. N’est pas unique à l’échelle globale.
`organization_id`	`str`	Organisation propriétaire de l’exécuteur.
`runner_group_id`	`str`	Groupe auquel appartient l’exécuteur.
`tags`	`tuple[str, ...]`	Étiquettes associées à l’exécuteur.
`healthy`	`bool`	Indique si l’exécuteur est actuellement en bon état de santé.
`is_shared`	`bool`	`True` lorsque l’exécuteur appartient à une organisation partagée.
`connected_at`	`datetime`	Date et heure de connexion de l’exécuteur, sous forme de datetime UTC avec fuseau horaire.
`max_cpu_millicores`	`int`	Capacité CPU agrégée déclarée, en millicœurs.
`max_memory_bytes`	`int`	Capacité mémoire agrégée déclarée, en octets.
`max_gpu_count`	`int`	Capacité GPU agrégée déclarée.
`supported_gpu_types`	`tuple[str, ...]`	Types de GPU dont sont équipés les nœuds de l’exécuteur.
`supported_architectures`	`tuple[str, ...]`	Architectures CPU prises en charge par l’exécuteur, par exemple `amd64`.
`supports_privileged`	`bool`	Indique si les conteneurs privilégiés sont autorisés.
`available_storage_classes`	`tuple[str, ...]`	Classes de stockage Kubernetes disponibles sur le cluster.
`supported_service_visibilities`	`tuple[str, ...]`	Visibilités de service que l’exécuteur peut appliquer : `public`, `private` ou `custom`. Voir `ServiceVisibility`.
`resources`	`RunnerResources \| None`	Disponibilité des ressources en temps réel, ou `None` si l’exécuteur ne la communique pas.

Une valeur max_* égale à 0 peut signifier que l’exécuteur ne divulgue pas ou ne déclare pas cette capacité, et non qu’il ne dispose d’aucune ressource. Les exécuteurs partagés renvoient 0, car leur capacité n’est pas communiquée, et les valeurs CPU et mémoire peuvent exclure la capacité réservée.

Vérifier la capacité en temps réel

Par défaut, list_runners() renvoie uniquement les informations sur les capacités prises en charge. Passez include_resources=True pour renseigner Runner.resources avec la disponibilité en temps réel. Utilisez format_bytes() et format_cpu() pour afficher les valeurs dans des unités lisibles :

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 vaut None lorsqu’un exécuteur ne signale pas sa disponibilité. Vérifiez donc que ce champ est défini avant d’en lire les valeurs.

Attributs de RunnerResources

Un objet RunnerResources comporte les attributs suivants :

Attribut	Type	Description
`available_cpu_millicores`	`int`	CPU non réservé, en millicœurs.
`available_memory_bytes`	`int`	Mémoire non réservée, en octets.
`available_gpu_count`	`int`	Nombre de GPU non réservés.
`running_sandboxes`	`int`	Sandbox en cours d’exécution sur l’exécuteur.

Filtrer la liste

Combinez plusieurs filtres pour restreindre la liste aux exécuteurs capables d’accueillir votre charge de travail. L’appel suivant renvoie les exécuteurs en bon état de santé qui disposent d’un type de GPU donné et d’au moins deux GPU disponibles. Remplacez [GPU-TYPE] par une valeur de 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")

Le service de découverte applique runner_group_id, gpu_type, architecture, healthy_only et service_visibility. Le client applique les trois filtres min_available_* une fois les résultats reçus. Ces trois filtres activent automatiquement include_resources et écartent tout exécuteur qui ne signale aucune donnée de ressources ; resources est donc toujours renseigné dans les résultats qu’ils renvoient.

Paramètres

Les paramètres suivants sont disponibles pour list_runners(). Ils doivent tous être passés par mot-clé (keyword-only).

Paramètre	Type	Description
`auth`	`AuthConfig \| None`	Stratégie d’authentification, en-têtes résolus ou fournisseur à utiliser pour cette requête.
`runner_group_id`	`str \| None`	Limiter les résultats à ce groupe d’exécuteurs.
`gpu_type`	`str \| None`	Renvoyer uniquement les exécuteurs qui prennent en charge ce type de GPU.
`architecture`	`str \| None`	Renvoyer uniquement les exécuteurs qui prennent en charge cette architecture CPU.
`healthy_only`	`bool`	Renvoyer uniquement les exécuteurs en bon état de santé. Par défaut : `False`.
`include_resources`	`bool`	Inclure la disponibilité des ressources en temps réel pour chaque exécuteur. Par défaut : `False`.
`min_available_cpu_millicores`	`int \| None`	Nombre minimum de millicœurs CPU non réservés. Active automatiquement `include_resources`.
`min_available_memory_bytes`	`int \| None`	Quantité minimale de mémoire non réservée, en octets. Active automatiquement `include_resources`.
`min_available_gpu_count`	`int \| None`	Nombre minimum de GPU non réservés. Active automatiquement `include_resources`.
`service_visibility`	`str \| None`	Renvoyer uniquement les exécuteurs capables d’appliquer cette visibilité de service : `public`, `private` ou `custom`.

Obtenir un exécuteur

get_runner() prend en paramètres un identifiant d’exécuteur et l’organisation à laquelle il appartient. Un identifiant d’exécuteur est unique au sein de son organisation, et non de manière globale : les deux sont donc requis. L’appel renvoie toujours les détails complets, mais la disponibilité des ressources n’est incluse que pour les exécuteurs appartenant à votre organisation. Remplacez [RUNNER-ID] et [ORGANIZATION-ID] par l’exécuteur souhaité et l’organisation à laquelle il appartient :

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}")

Chaque exécuteur renvoyé par une liste possède son propre organization_id. Transmettez donc runner.organization_id lorsque vous récupérez un exécuteur obtenu dans un résultat précédent.

Créer une sandbox sur un exécuteur découvert

Définissez placement_mode="cks" et transmettez à runner_ids l’exécuteur que vous avez sélectionné. Remplacez [GPU-TYPE] par l’une des valeurs de 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)

Sans runner_ids, le placement CKS peut utiliser n’importe quel exécuteur éligible de votre organisation. runner_ids est incompatible avec le placement sans serveur ainsi qu’avec placement_spillover="serverless_then_cks".

Appliquer un exécuteur à toutes les Sandbox d’une session

Utilisez SandboxDefaults pour envoyer toutes les Sandbox d’une session vers le même exécuteur :

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)

Pour les autres options de la Sandbox, consultez le guide de configuration de la Sandbox.

Référence des erreurs

Les appels de découverte peuvent lever les exceptions suivantes.

Exception	Cause
`RunnerNotFoundError`	Aucun exécuteur ne correspond aux `runner_id` et `organization_id` indiqués.
`DiscoveryValidationError`	Une requête de découverte n’a pas passé la validation au niveau des champs.
`DiscoveryError`	Erreur réseau ou de service survenue lors d’une opération de découverte. Classe de base des deux exceptions ci-dessus.
`CWSandboxAuthenticationError`	Identifiants d’authentification non valides ou manquants.

Lorsque runner_id ou organization_id est vide, get_runner() lève ValueError avant même d’envoyer une requête. Pour consulter la hiérarchie complète des exceptions, reportez-vous à la référence des exceptions. Pour les étapes de dépannage courantes, consultez les articles d’assistance Sandbox.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Découvrir les exécuteurs disponibles

Lister les exécuteurs

Lire les capacités des exécuteurs

Attributs de l’exécuteur

Vérifier la capacité en temps réel

Attributs de RunnerResources

Filtrer la liste

Paramètres

Obtenir un exécuteur

Créer une sandbox sur un exécuteur découvert

Appliquer un exécuteur à toutes les Sandbox d’une session

Référence des erreurs

​Lister les exécuteurs

​Lire les capacités des exécuteurs

​Attributs de l’exécuteur

​Vérifier la capacité en temps réel

​Attributs de RunnerResources

​Filtrer la liste

​Paramètres

​Obtenir un exécuteur

​Créer une sandbox sur un exécuteur découvert

​Appliquer un exécuteur à toutes les Sandbox d’une session

​Référence des erreurs

Lister les exécuteurs

Lire les capacités des exécuteurs

Attributs de l’exécuteur

Vérifier la capacité en temps réel

Attributs de RunnerResources

Filtrer la liste

Paramètres

Obtenir un exécuteur

Créer une sandbox sur un exécuteur découvert

Appliquer un exécuteur à toutes les Sandbox d’une session

Référence des erreurs