Français
Commencer

Agent Sandboxes Commandes, fichiers et terminal

Une sandbox d’exécution de code pour agents IA

Votre modèle écrit du code, une sandbox l’exécute, et la sortie revient dans le même appel. Commandes, fichiers et terminaux forment une seule API, servie par le serveur où tourne la sandbox, pas par la console.

Exécuter du code en un appel

Chaque sandbox est une microVM Firecracker avec son propre noyau Linux, root à l’intérieur, démarrée depuis notre template base en 0,15 s environ : Ubuntu 24.04 avec les outils de build, Python 3, Node.js 22 et Docker. run_command exécute une commande via bash -lc en tant que user, qui a sudo, ou en root, dans le dossier de votre choix. L’appel attend jusqu’à 45 secondes que la commande se termine et renvoie son code de sortie et les 32 derniers KiB de son stdout et de son stderr.

Trois champs changent ce que l’appel attend :

  • wait_for_port répond dès que quelque chose écoute sur un port, pendant que la commande continue : npm run dev et 5173.
  • wait_seconds=0 répond dès que la commande a démarré. get_command l’attend de nouveau, et watch_command diffuse sa sortie, les 64 derniers KiB d’abord, puis en direct.
  • timeout_seconds met fin à une commande qui dure trop. Sans lui, seul stop_command en arrête une : SIGTERM, puis SIGKILL 10 s plus tard.

Chaque réponse indique combien d’octets la commande a écrits ; renvoyez ce nombre, et la réponse suivante ne contient que la nouveauté. Avec un request_id, une nouvelle tentative dans les 24 heures ne relance rien et renvoie ce qu’a fait le premier appel. list_commands montre ce qui tourne en ce moment, commandes tapées par SSH comprises, et les 100 dernières terminées sont gardées.

from pethost.sandboxes import FileChange, Sandboxes, TextEdit

sandboxes = Sandboxes()  # lit PETHOST_TOKEN
box = sandboxes.create_sandbox()
code = "x = 1\nprint(x * 42)\n"
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", text=code)])
out = sandboxes.run_command(box.sandbox_id, command="python3 app.py", timeout_seconds=30)
print(out.exit_code, out.stdout)  # 0 42

edit = TextEdit(old_text="x = 1", new_text="x = 2")
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", edit=edit)])
server = sandboxes.run_command(box.sandbox_id, command="python3 -m http.server 8000",
                               wait_for_port=8000)
print(server.state.name)  # RUNNING : il a répondu dès que le port 8000 a écouté
pethost sandbox new --name tests --size small
pethost sandbox cp ./app tests:/home/user/app
pethost sandbox run tests --cwd /home/user/app -- python3 -m unittest
pethost sandbox open tests --terminal

Fichiers : lots et modifications exactes

write_files prend une liste de changements et les applique dans l’ordre : écrire le texte ou les octets d’un fichier, remplacer un texte qui y apparaît exactement une fois, déplacer, supprimer, créer un dossier, changer un mode. Les dossiers parents manquants sont créés. Il s’arrête au premier changement qui échoue et dit lequel, avec une raison sur laquelle brancher votre code, comme un texte à remplacer introuvable. Ainsi, une modification ne s’applique que là où se trouve son texte. Une requête transporte jusqu’à 17 MiB.

read_file lit jusqu’à 1 MiB depuis n’importe quelle position, list_files liste un dossier aussi profondément que vous le demandez, et watch_files diffuse chaque changement en dessous. Un fichier de n’importe quelle taille passe par un lien de create_link : une URL de téléchargement envoie le fichier, ou un dossier en .tar ; une URL d’envoi accepte un PUT. Chacune ne sert qu’une fois.

Un terminal dans le navigateur

create_link avec un terminal donne une page qui lance bash, ou une commande comme claude, et un WebSocket à la même URL qui en transporte les octets, pour un terminal dans votre propre produit. Un lien dure une heure par défaut et un jour au plus.

Ce qui tourne à l’intérieur

Docker tourne dans chaque sandbox : dockerd démarre à la première connexion à son socket et garde les images sur le disque de la sandbox, si bien qu’elles survivent à un arrêt et qu’un template les emporte. Le reste vient d’apt, avec sudo.

Les appels vont directement au serveur de la sandbox, que le SDK trouve pour vous. La première commande après une création répond en 29 à 48 ms. Sur un serveur qui faisait tourner 74 sandboxes, chacune construisant un projet JavaScript et attendant entre deux builds comme le fait un agent, une commande triviale a pris 6 ms (28 ms au 95e centile).

Limites et prix

QuoiLimite
Appels simultanés, par sandbox64 ; un write_files compte pour 16
Une requête1 MiB ; write_files 17 MiB
Une réponseenviron 64 KiB ; read_file 1 MiB ; toute taille via un lien
Sortie dans une réponseles 32 derniers KiB du stdout et du stderr

Commandes, fichiers et liens n’ont pas de prix à eux : vous payez les secondes d’exécution de la sandbox, de 0,018 $ de l’heure pour SMALL (2 vCPU, 4 GiB) à 0,144 $ pour XLARGE (16 vCPU, 32 GiB), chaque exécution arrondie à la seconde supérieure, 10 s au moins. Inactive pendant 5 minutes, elle se met en pause à 30 % de ce prix. Comment marche la facturation à la seconde.

Face aux autres

Le 21 novembre 2026, E2B facturait 0,1656 $ de l’heure une sandbox de 2 vCPU et 4 GiB, tout comme Daytona ; la SMALL de Pethost, de même taille, coûte 0,018 $. Les sessions d’E2B duraient jusqu’à 1 heure sur son offre Hobby et 24 heures sur Pro, celles de Vercel Sandbox 45 minutes sur Hobby et 24 heures sur Pro. Une sandbox Pethost n’a pas de durée de vie limitée.

Lire la documentation

Questions

Quels langages une sandbox d’exécution de code peut-elle exécuter ?

Tout ce qui tourne sous Linux. Python 3 et Node.js 22 sont installés, Docker tourne, et apt installe le reste. Enregistrez une sandbox avec vos outils comme template, et les nouvelles sandboxes démarrent avec eux.

Combien de temps une commande peut-elle tourner ?

Autant qu’il le faut : un appel attend jusqu’à 45 secondes, puis vous lisez ou suivez sa sortie. Inactive pendant 5 minutes, une sandbox se met en pause avec la commande en mémoire, qui reprend au prochain appel. Une commande lancée avec keep_awake tourne d’une traite, de même qu’une commande que vous suivez avec watch_command.

Le code peut-il accéder à Internet ?

Oui, en TCP : par défaut, une sandbox peut se connecter n’importe où. Une liste d’autorisation du trafic sortant restreint cela aux domaines, IP et ports que vous indiquez. Aucun trafic UDP ne sort d’une sandbox.

Comment déplacer de gros fichiers ?

Par un lien de téléchargement ou d’envoi, de n’importe quelle taille, ou avec scp via SSH.

Voir aussi

Donnez un ordinateur à votre agent en 0,15 s

Démarrer l’essai gratuit