Français
Menu de la documentation

Documentation Agent Sandboxes · Premiers pas

Comment marchent Pethost Agent Sandboxes

Mis à jour le · 9 min de lecture

Une sandbox est une VM Linux que votre code ou votre agent démarre en 0,15 s environ, utilise par une API, puis laisse tranquille. Quand il ne s’y passe rien, elle se met en pause avec sa mémoire et ses processus, puis s’arrête en ne gardant que son disque. Le prochain appel la réveille là où elle en était. Cette page en donne le modèle : ce qu’est une sandbox, ses trois états, ce qui la fait passer de l’un à l’autre, et où vit chaque octet.

En bref
  • Une microVM par sandbox : Firecracker, son propre noyau, root à l’intérieur, Ubuntu avec Python, Node.js, Docker, trois agents de code et Chrome.
  • Trois états : RUNNING dans la mémoire de son serveur, PAUSED sur le disque de son serveur avec mémoire et processus gardés, STOPPED en stockage objet avec son disque seul.
  • Réveil à l’usage : tout appel vers une sandbox en pause, une connexion SSH ou une requête vers l’un de ses ports la reprend en 0,1 s environ.
  • Deux API : la console tient le registre de chaque sandbox, et le serveur de la sandbox exécute ce qui se passe à l’intérieur. Les SDK et la CLI masquent la différence.
  • Facturé à la seconde pour chaque état : facturation.

Ce qu’est une sandbox

Une sandbox est une machine virtuelle, créée à partir d’un template. Vous y êtes root, et les commandes s’exécutent en tant qu’utilisateur user, qui a sudo sans mot de passe, dans /home/user. Son nom d’hôte est son ID : 16 caractères, des lettres minuscules et des chiffres.

Notre template, base, contient Ubuntu 24.04 avec les outils de build et git, Python 3, Node.js 22, Docker, les agents de code Claude Code, Codex et OpenCode, et un bureau avec Google Chrome. Deux d’entre eux ne démarrent qu’à leur première utilisation et ne coûtent rien jusque-là : le bureau, à la première capture d’écran ou au premier lien de bureau (quelques secondes), et le démon de Docker, à la première connexion à /var/run/docker.sock.

Isolement : une microVM Firecracker chacune

Chaque sandbox est sa propre microVM Firecracker, avec son propre noyau Linux. Firecracker lance chaque VM dans son jailer : son propre chroot, un utilisateur sans privilèges, un cgroup, un filtre seccomp et son propre namespace réseau. L’invité est à vous, root et noyau compris ; c’est l’hôte qui décide de ce qu’il reçoit.

  • Sa taille est tenue par l’hôte. Une VM reçoit du serveur les vCPU et la mémoire de sa taille, et rien de ce que dit l’invité n’y change quoi que ce soit.
  • Sa propre identité. Chaque sandbox reçoit un aléa noyau neuf, son propre nom d’hôte et son propre machine-id, même quand elle démarre du même snapshot qu’une autre.
  • Aucun secret à l’intérieur. Les secrets de l’espace de travail n’entrent jamais dans une VM, pas plus que les tokens d’API : on joint une sandbox avec un token pour elle seule, qui expire.

Tailles

Une sandbox a l’une de quatre tailles, pour toute la vie de sa VM :

TaillevCPUMémoireDisque
SMALL24 GiB10 GiB
DEFAULT48 GiB20 GiB
LARGE816 GiB40 GiB
XLARGE1632 GiB80 GiB

Le disque, c’est ce que la sandbox peut écrire : les fichiers propres au template n’y comptent pas. Une nouvelle taille (UpdateSandbox) redémarre une sandbox RUNNING dans une VM de cette taille, ses fichiers gardés et ses processus terminés ; une sandbox STOPPED prend la nouvelle taille à son prochain démarrage, et une sandbox PAUSED doit d’abord être reprise ou arrêtée. Une nouvelle taille garde le disque, sauf si vous fixez grow_disk, qui l’agrandit à celui de la nouvelle taille. Un disque ne rétrécit jamais.

Templates

Un template, ce sont les fichiers avec lesquels une sandbox démarre. Le nôtre est base, reconstruit chaque mois, et aussitôt pour un correctif de sécurité. Le vôtre est le disque d’une sandbox enregistré avec CreateTemplate : ses fichiers, les paquets que vous avez installés et ses images Docker. Un template ne garde ni mémoire, ni processus, ni conversations d’agents : une sandbox créée à partir de lui démarre à neuf.

Chaque enregistrement est une nouvelle version, name@1, name@2, et une sandbox démarrée depuis name prend la plus récente. Chaque serveur démarre des sandboxes depuis n’importe quelle version. Le min_size d’une version est la plus petite taille dont le disque contient ce qu’elle a enregistré. Une sandbox issue de votre propre template démarre en 0,22 s environ une fois que son serveur a la version ; la première sur chaque serveur la rapatrie, en 10 s environ par GiB : templates.

Deux API : la console et le serveur de la sandbox

Deux services répondent, selon ce qu’ils savent :

  • SandboxService est la console, à https://console.pethost.dev, appelée avec votre token d’API. Elle tient l’espace de travail et chaque sandbox comme un registre : création, paramètres, pause, reprise, duplication, suppression, templates, volumes, événements et consommation.
  • SandboxRuntimeService est le serveur de la sandbox, à l’url de sa connexion, appelé avec un token de connexion pour cette seule sandbox. Il exécute ce qui se passe à l’intérieur : commandes, fichiers, bureau, agents de code et liens.

Les SDK et la CLI se connectent pour vous : run_command est un seul appel, et le SDK trouve le serveur et garde le token à jour. Les appels au runtime vont directement au serveur : la console n’est donc jamais sur le chemin de ce qui tourne dans une sandbox, et un serveur fait tourner ses sandboxes sans elle.

Les trois états

RUNNING

Dans la mémoire de son serveur

Fait tourner vos processus et répond à chaque appel.

0,036 $ de l’heure, DEFAULT

Inactive 5 min, ou PauseSandbox

Tout appel, connexion SSH ou requête vers un port, en 0,1 s environ

PAUSED

Sur le disque de son serveur

Garde mémoire, processus et disque, et sa place sur le serveur.

0,0108 $ de l’heure, DEFAULT

Inactive 30 min, ou StopSandbox

STOPPED

En stockage objet

Garde son disque ; ses processus prennent fin.

0,03 $ par GiB et par mois de ses propres données

ResumeSandbox la redémarre : 0,2 s environ avec son disque sur le serveur, 10 s environ par GiB depuis le stockage objet

Les délais par défaut, comptés depuis la dernière chose qui s’est passée dans la sandbox. Une sandbox RUNNING peut aussi s’arrêter tout de suite, et toute sandbox peut être supprimée.
ÉtatOù elle vitCe qu’elle gardeComment elle se réveille
RUNNINGLa mémoire de son serveurTout, en marcheElle est éveillée
PAUSEDLe disque de son serveurMémoire, processus, disqueAu prochain appel, connexion SSH ou requête vers un port, en 0,1 s environ ; jamais refusé faute de place
STOPPEDLe stockage objet, et le disque de son serveur tant qu’il y a de la placeSon disquePar ResumeSandbox, ou comme une sandbox en pause avec wake_when_stopped
DELETEDNulle partSon registre pendant 30 jours, ses événements et métriques pendant un jourJamais

Pourquoi PAUSED existe

La VM d’un agent passe surtout son temps à attendre : que le modèle réfléchisse, qu’une personne lise la réponse, que le message suivant arrive. L’arrêter met fin à ses processus, et avec eux au serveur de développement, au REPL, à l’état du shell et au navigateur ouvert dont se servait l’agent. La garder RUNNING, c’est payer plein tarif pour attendre.

PAUSED garde tout, mémoire et processus compris, pour 30 % du prix d’exécution, et le serveur garde la place de la sandbox : une reprise n’est donc jamais refusée faute de place. Votre code n’a rien à faire pour la réveiller : le prochain appel vers la sandbox la reprend d’abord, en 0,1 s environ, puis s’exécute comme si la sandbox ne s’était jamais arrêtée. Une sandbox en pause met 41 ms à reprendre sur son serveur, et une commande envoyée à l’une d’elles répond en 80 ms environ.

Ce qui fait changer une sandbox d’état

DeVersCe qui la fait passer
RUNNINGPAUSEDSon délai de pause ; PauseSandbox ; son serveur à court de mémoire, une fois qu’elle est inactive depuis une minute ; le redémarrage de la machine de son serveur (MAINTENANCE, qui ne compte rien)
PAUSEDRUNNINGTout appel au runtime, une connexion SSH ou une requête vers un port (WAKE) ; ResumeSandbox
RUNNING ou PAUSEDSTOPPEDSon délai d’arrêt ; StopSandbox ; son serveur à court de disque (pour une sandbox en pause) ; un espace de travail sans rien pour payer (UNPAID) ; un plantage de sa VM ou de son serveur (CRASH)
STOPPEDRUNNINGResumeSandbox ; un appel, une connexion SSH ou une requête vers un port seulement avec wake_when_stopped, et jamais après un CRASH
Tout étatDELETEDDeleteSandbox ; son délai de suppression ; la perte de son serveur, pour une sandbox sans copie en stockage objet

Chaque changement a une raison, state_reason, et des mots pour les personnes, state_message. Cycle de vie et inactivité dit ce qui compte comme activité et comment régler les délais.

Ce qui réveille une sandbox

Tout appel de SandboxRuntimeService, une connexion SSH ou une requête vers l’un de ses ports reprend d’abord une sandbox PAUSED, sur son propre serveur. Une sandbox STOPPED ne se réveille ainsi que si son cycle de vie dit wake_when_stopped. Sinon :

  • un appel au runtime répond FAILED_PRECONDITION avec le détail Stopped ;
  • une requête vers un port répond HTTP 503, « stopped: resume it » ;
  • seul ResumeSandbox la démarre.

Une sandbox arrêtée par un CRASH ne redémarre que par ResumeSandbox. Pendant que le disque d’une sandbox arrêtée est rapatrié depuis le stockage objet, les appels vers elle répondent UNAVAILABLE avec Restoring, et ResumeSandbox attend jusqu’à 45 s, puis dit où en est le rapatriement (Sandbox.restore).

Où vivent vos données

QuoiPauseArrêtDuplicationTemplateSuppression
MémoireGardéePerdueCopiéeNon enregistréeDisparue
Processus en coursGardésTerminésCopiés, en marcheNon enregistrésDisparus
Fichiers et images DockerGardésGardésCopiésEnregistrésDisparus
Conversations d’agentsGardéesGardéesCopiéesNon enregistréesDisparues

Le disque d’une sandbox arrêtée est copié vers le stockage objet dans l’UE une minute après son arrêt, en morceaux chiffrés avec une clé propre à cette sandbox ; la mémoire n’y est jamais copiée. Son serveur garde sa propre copie tant qu’il a de la place. Un volume, c’est autre chose : il vit sur le disque d’un seul serveur et n’est copié nulle part ; gardez donc aussi ailleurs ce qui doit survivre à la perte d’un serveur.

Déplacements et serveurs perdus

Une sandbox STOPPED avec une copie à jour et sans volume démarre sur un autre serveur quand le sien n’a pas de place pour elle, et ses adresses la suivent : l’url de la connexion, les URL de ses ports et sa ssh_command. Une sandbox PAUSED ne se déplace jamais : elle reprend sur le serveur qui détient sa mémoire.

Si un serveur est perdu, chacune de ses sandboxes qui a une copie devient STOPPED à partir de sa dernière copie et démarre sur un autre serveur à son prochain ResumeSandbox. Une sandbox sans copie est supprimée, de même que les volumes de ce serveur.

Questions

Une sandbox est-elle un conteneur ?

Non. Chaque sandbox est une microVM Firecracker avec son propre noyau Linux, et vous y êtes root. Vous pouvez faire tourner des conteneurs Docker dans une sandbox.

Que deviennent mes processus quand une sandbox se met en pause ?

Ils s’arrêtent là où ils en sont et gardent leur mémoire, leurs fichiers ouverts et leur état. Le prochain appel, la prochaine connexion SSH ou requête vers un port les reprend en 0,1 s environ, comme si de rien n’était.

Une sandbox en pause peut-elle ne pas se réveiller faute de place ?

Non. Son serveur garde sa place tant qu’elle est en pause : une reprise n’est donc jamais refusée faute de place. Une sandbox arrêtée, si : ResumeSandbox peut alors la démarrer sur un autre serveur.

Où sont mes fichiers quand une sandbox est arrêtée ?

Sur son disque, copié vers le stockage objet dans l’UE, chiffré avec une clé propre à cette sandbox, et sur son serveur tant qu’il y a de la place. Ils reviennent tels quels à la reprise.

Un template garde-t-il les processus en cours ?

Non. Un template n’enregistre que le disque : fichiers, paquets et images Docker. Une sandbox créée à partir de lui démarre à neuf, sans aucun processus ni aucune conversation d’agent de celle dont il a été enregistré. Pour copier une sandbox active, dupliquez-la.

Essayez Pethost Agent Sandboxes

Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.

Démarrer l’essai gratuit