Libérez le client HTTP local sans mettre fin au bac à sable. Idempotent.

Aucune opération pour les sandbox de pool (le client appartient à l'hôte du pool).

Reconnectez-vous à un bac à sable en cours d’exécution depuis n’importe où, en utilisant uniquement son identifiant.

Créez un bac à sable dédié (un Job HF) et bloquez jusqu'à ce qu'il soit prêt (~7 s sur cpu-basic).

Chaque bac à sable est une VM isolée complète, ce qui en fait le bon choix pour les charges de travail GPU ou le code non fiable. Pour déployer de nombreux bacs à sable CPU peu coûteux, utilisez plutôt SandboxPool.

Le job s'exécute avec une durée de vie maximale fixe de 24 h ; idle_timeout est le véritable gardien — un bac à sable inactif se ferme bien avant cela.

L’image n’a besoin que de /bin/sh. Le serveur sandbox est téléchargé au démarrage avec wget/curl si disponible, sinon lu depuis un bucket de serveur toujours monté (ce qui ajoute ~2-3 s au démarrage à froid, donc inclure wget/curl le maintient rapide).

Listez les processus en arrière-plan de cette sandbox.

Retourne les processus démarrés avec Sandbox.run()(..., background=True) ; arrêtez-en un avec SandboxProcess.kill(). Les processus récemment terminés restent listés (avec running=False et leur exit_code) ; le serveur conserve un nombre limité de ces processus, de sorte qu’une sandbox ayant exécuté des milliers de commandes courtes ne les listera pas tous.

URL publique qui effectue un proxy vers un serveur exécuté à l'intérieur de cette sandbox.

Les requêtes envoyées à l’URL renvoyée sont transmises par le serveur sandbox du job vers un serveur que vous avez démarré dans le sandbox sur le port, y compris les mises à niveau WebSocket (ws(s)://) et les réponses en streaming. Associez-le à proxy_headers pour l’authentification.

Comment le bac à sable doit écouter sur le port :

• Pool / bac à sable partagé : il ne peut pas lier un port TCP (Landlock), il faut donc lier un socket unix à $SBX_PROXY_DIR/<port>.sock (la variable d’environnement SBX_PROXY_DIR est définie dans chaque bac à sable). Par exemple : uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock.
• Sandbox dédié : liez un port TCP normal sur 127.0.0.1:<port>. (Vous pouvez également exposer le port directement via le proxy du job sans passer par ici.)

>>> url = sandbox.proxy_url_for(8000, "/ws", scheme="wss://")
>>> import websockets
>>> async with websockets.connect(url, additional_headers=sandbox.proxy_headers) as ws:
...     await ws.send("hello")

Exécuter une commande dans le bac à sable et attendre sa fin, en diffusant la sortie en direct.

Avec background=True, la commande est lancée en tâche détachée et run renvoie immédiatement un SandboxProcess, sans attendre sa fin — pratique pour les serveurs et autres processus de longue durée. Vous pouvez les lister plus tard avec Sandbox.processes() et en arrêter un avec SandboxProcess.kill(). Les options de streaming/attente uniquement (timeout, stdin, on_stdout, on_stderr, check) ne s’appliquent pas dans ce mode.

Retourne : un SandboxCommandResult (avec exit_code, stdout, stderr, duration_ms), ou un SandboxProcess lorsque background=True.

Libère le pool. Idempotent.

Pour un pool que nous avons créé, cela met fin à tous les jobs d’hôtes (et donc à tous leurs sandboxes). Pour un handle obtenu via connect(), cela ne libère que les clients HTTP locaux : les hôtes partagés peuvent servir d’autres clients, donc — comme Sandbox.connect() — quitter un bloc with ne doit pas les détruire. Mettez fin explicitement aux hôtes d’un pool connecté avec hf sandbox pool delete <id>.

Seuls les hôtes qui ont démarré sont annulés. Un hôte découvert via des étiquettes peut servir les boîtes à sable d’un autre processus, il est donc libéré plutôt que terminé.

Lève SandboxError si un travail hôte n’a pas pu être annulé, en indiquant les travaux toujours en cours d’exécution — ils continuent d’être facturés et leurs entrées de cache sont conservées afin de rester découvrables. Lorsque close() est atteint via __exit__ alors qu’une exception est déjà en cours, l’échec est journalisé à la place, afin de ne pas masquer l’erreur d’origine.

Se reconnecter à un pool en cours d’exécution par son identifiant, depuis n’importe quelle machine — aucun état local requis.

Recherche un hôte en cours d’exécution étiqueté avec pool_id et reconstruit la configuration du pool (image/flavor/density/host-idle) à partir de la spécification et des variables d’environnement du job de cet hôte, en renvoyant un SandboxPool prêt à create() d’autres sandboxes — en les regroupant sur les hôtes en cours d’exécution, ou en démarrant un duplicata (même configuration) lorsque ceux-ci sont pleins.

Lève SandboxError si aucun hôte en cours d’exécution n’est trouvé (un pool cesse d’exister dès que tous ses hôtes ont disparu — par expiration d’inactivité ou par arrêt).

Créez un seul bac à sable, en provisionnant un hôte si nécessaire.

Réutilise un hôte disposant d’une capacité libre (celui de ce pool, ou un hôte chaud trouvé via les étiquettes de tâche / le cache local) avant d’en démarrer un nouveau, de sorte qu’un create() sur un hôte chaud coûte environ un aller-retour. Appelez-le de manière répétée pour répartir la charge ; utilisez warm_up (ou warm) pour pré-provisionner les hôtes et éviter un démarrage à froid lors des premiers appels. Si un hôte se remplit sous nos pieds (un autre processus l’a saturé) ou si un hôte en cache a disparu, le sandbox est repositionné sur un autre hôte (ou un hôte neuf).

Vérifiez que num_hosts hôte(s) vide(s) sont en cours d’exécution et laissez-les tels quels. Renvoie les identifiants des tâches des hôtes du pool.

Utilisé pour « créer » un pool à l’avance : les hôtes portent l’étiquette et la configuration du pool (dans leurs variables d’environnement), de sorte qu’un appel ultérieur à SandboxPool.connect(pool_id) (même depuis une autre machine) les trouve et crée des sandboxes sans démarrage à froid. Les hôtes continuent d’être facturés jusqu’à leur arrêt ou leur inactivité.

Adopte les hôtes déjà en cours d’exécution pour ce pool (trouvés via les étiquettes de tâche) avant le démarrage, de sorte qu’un warm() après connect() — ou un warm() répété — complète jusqu’à num_hosts au lieu de dupliquer les hôtes actifs et de dépasser max_hosts.

Arrêter le processus en arrière-plan. Idempotent.

Indique si cet appel est celui qui l'a arrêtée : False signifie qu'elle s'était déjà terminée ou avait été interrompue, ce qui n'est pas une erreur.

Notez qu'un descendant qui se détache via setsid() quitte le groupe de processus signalé et survit à cet appel. Supprimez le bac à sable pour vous assurer que tout ce qu'il a démarré a bien été supprimé.