Shells interactifs et TTY

Utilisez Sandbox.shell() pour les sessions TTY interactives. Conçue pour un usage interactif, cette méthode renvoie un objet TerminalSession qui diffuse les octets bruts en continu, sans mise en mémoire tampon de la sortie. Pour exécuter des commandes par lots, utilisez plutôt exec().

Choisir l’authentification

Ces exemples s’exécutent sur une capacité sans serveur, sauf si une section indique CKS. Choisissez l’identifiant d’authentification du compte propriétaire de vos bacs à sable. Consultez Choisir et obtenir des identifiants d’authentification pour obtenir une clé ou un jeton. Exécutez les commandes d’installation dans un environnement virtuel Python actif. Enregistrez le code Python de l’onglet correspondant à votre identifiant d’authentification sous le nom sandbox_auth.py, dans le même répertoire que les scripts Python que vous exécutez à partir de cette page. Ce fichier enregistre le mode d’authentification choisi, et non votre identifiant d’authentification. Les exemples importent AUTH depuis ce fichier et le transmettent explicitement à chaque nouvelle sandbox ou session.

Clé API Forge
Jeton d’accès à l’API CoreWeave

Utilisez votre clé API Forge via la stratégie d’authentification W&B du SDK :

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

Utilisez le jeton de votre organisation CoreWeave :

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

Pour un placement sur CKS, choisissez le jeton CoreWeave, activez un exécuteur et définissez placement_mode="cks" lors de la création de la sandbox ou dans SandboxDefaults. Créer une session avec auth=AUTH authentifie également les bacs à sable qui lui appartiennent. Utilisez le même identifiant d’authentification pour vous reconnecter à vos bacs à sable, les lister ou les nettoyer.

Session shell

Créez une sandbox et ouvrez une session de shell interactif. Appelée sans commande, Sandbox.run() utilise la commande longue durée par défaut. Les exemples suivants partent du principe que ce contexte est toujours actif.

from sandbox_auth import AUTH
from cwsandbox import Sandbox

with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    terminal = sandbox.shell(
        ["/bin/bash"],
        width=80,
        height=24,
    )

shell() alloue toujours un TTY et active stdin. La TerminalSession renvoyée diffuse les octets bruts en flux, sans aller-retour de décodage ou d’encodage UTF-8, ce qui permet de l’utiliser sans risque avec les séquences d’échappement de terminal et les sorties binaires.

Envoyer des commandes et lire la sortie

Une fois la session de terminal ouverte, écrivez des commandes sur stdin et récupérez en streaming la sortie brute fusionnée (en octets) du shell distant.

import sys

terminal.stdin.writeline("echo hello").result()
terminal.stdin.writeline("ls -la /tmp").result()
terminal.stdin.writeline("exit").result()

# Parcourir la sortie brute en octets
for chunk in terminal.output:
    sys.stdout.buffer.write(chunk)
    sys.stdout.buffer.flush()  # Vider la mémoire tampon pour que la sortie s’affiche au fil de l’exécution de la session.

# Obtenir le code de sortie
exit_code = terminal.wait(timeout=5.0)

TerminalSession ne met pas la sortie en mémoire tampon. Stdout et stderr sont fusionnés en un seul flux d’octets bruts sur terminal.output. Le résultat ne comporte pas d’attributs stdout ou stderr distincts. Lisez terminal.output en continu. Si vous cessez de le lire, la contre-pression exercée par la file d’attente bornée bloque la session distante.

Redimensionnement du terminal

Envoyez des messages de redimensionnement lorsque les dimensions du terminal changent.

terminal.resize(120, 40)

resize() fonctionne en mode fire-and-forget sur TerminalSession.

Quitter une session shell

Pour mettre fin à une session shell, fermez stdin ou envoyez une commande de sortie :

terminal.stdin.writeline("exit").result()  # Demander au shell distant de se terminer
# ou
terminal.stdin.close().result()            # Fermer le flux stdin

La session shell se termine lorsque le processus distant s’arrête. Appelez terminal.wait() ou terminal.result() pour bloquer l’exécution jusqu’à l’obtention du code de sortie.

Attacher votre terminal local

Pour travailler dans une sandbox en cours d’exécution depuis votre propre terminal, passez le terminal local en mode brut (raw) et redirigez son entrée vers une session shell(). Le script suivant s’attache à une sandbox existante à partir de son ID, transmet vos frappes clavier à un shell Bash dans la sandbox, puis restaure les paramètres de votre terminal local à la fermeture du shell. Comme il utilise termios, il fonctionne sous macOS ou Linux. Enregistrez le script sous le nom attach_sandbox.py, dans le même répertoire que sandbox_auth.py :

attach_sandbox.py

import os
import shutil
import sys
import termios
import threading
import tty

from cwsandbox import Sandbox
from sandbox_auth import AUTH

if not sys.stdin.isatty() or not sys.stdout.isatty():
    raise SystemExit("Run this script in an interactive terminal.")

sandbox = Sandbox.from_id(sys.argv[1], auth=AUTH).result()
size = shutil.get_terminal_size()
terminal = sandbox.shell(["/bin/bash"], width=size.columns, height=size.lines)
fd = sys.stdin.fileno()
saved = termios.tcgetattr(fd)

def forward_input():
    while data := os.read(fd, 1024):
        terminal.stdin.write(data).result()
    terminal.stdin.close().result()

try:
    tty.setraw(fd)
    threading.Thread(target=forward_input, daemon=True).start()
    for chunk in terminal.output:
        sys.stdout.buffer.write(chunk)
        sys.stdout.buffer.flush()
    result = terminal.result()
finally:
    termios.tcsetattr(fd, termios.TCSADRAIN, saved)
    terminal.stdin.close().result()

raise SystemExit(result.returncode)

Remplacez [SANDBOX-ID] par l’ID d’une sandbox en cours d’exécution, puis exécutez le script depuis un terminal interactif :

python attach_sandbox.py [SANDBOX-ID]

Le script se termine avec le code de sortie du shell distant.

Commandes et cas d’utilisation

Cas d’utilisation	Approche
Commande ponctuelle depuis le terminal	`cwsandbox exec [ID] echo hello`
Shell interactif depuis le terminal	`cwsandbox sh [ID]`
Exécuter un script et capturer la sortie (SDK)	`exec(["python", "script.py"])`
Session de shell interactif (SDK)	`shell(["/bin/bash"])`
Envoyer une entrée à une commande (SDK)	`exec(["cat"], stdin=True)`
Application en mode terminal (vim, htop)	`shell(["vim"])` + mode brut (raw) de la CLI

Voir aussi

Exécution de commandes - Exécutez des commandes avec exec().
Journalisation de la sandbox - Diffusez en continu les journaux du conteneur.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Choisir l’authentification

Session shell

Envoyer des commandes et lire la sortie

Redimensionnement du terminal

Quitter une session shell

Attacher votre terminal local

Commandes et cas d’utilisation

Voir aussi

​Choisir l’authentification

​Session shell

​Envoyer des commandes et lire la sortie

​Redimensionnement du terminal

​Quitter une session shell

​Attacher votre terminal local

​Commandes et cas d’utilisation

​Voir aussi

Choisir l’authentification

Session shell

Envoyer des commandes et lire la sortie

Redimensionnement du terminal

Quitter une session shell

Attacher votre terminal local

Commandes et cas d’utilisation

Voir aussi