Documentation Agent Sandboxes · Premiers pas
Comment marchent Pethost Agent Sandboxes
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.
- 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 :
| Taille | vCPU | Mémoire | Disque |
|---|---|---|---|
| SMALL | 2 | 4 GiB | 10 GiB |
| DEFAULT | 4 | 8 GiB | 20 GiB |
| LARGE | 8 | 16 GiB | 40 GiB |
| XLARGE | 16 | 32 GiB | 80 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’
urlde 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
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
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
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
| État | Où elle vit | Ce qu’elle garde | Comment elle se réveille |
|---|---|---|---|
| RUNNING | La mémoire de son serveur | Tout, en marche | Elle est éveillée |
| PAUSED | Le disque de son serveur | Mémoire, processus, disque | Au prochain appel, connexion SSH ou requête vers un port, en 0,1 s environ ; jamais refusé faute de place |
| STOPPED | Le stockage objet, et le disque de son serveur tant qu’il y a de la place | Son disque | Par ResumeSandbox, ou comme une sandbox en pause avec wake_when_stopped |
| DELETED | Nulle part | Son registre pendant 30 jours, ses événements et métriques pendant un jour | Jamais |
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
| De | Vers | Ce qui la fait passer |
|---|---|---|
| RUNNING | PAUSED | Son 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) |
| PAUSED | RUNNING | Tout appel au runtime, une connexion SSH ou une requête vers un port (WAKE) ; ResumeSandbox |
| RUNNING ou PAUSED | STOPPED | Son 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) |
| STOPPED | RUNNING | ResumeSandbox ; un appel, une connexion SSH ou une requête vers un port seulement avec wake_when_stopped, et jamais après un CRASH |
| Tout état | DELETED | DeleteSandbox ; 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_PRECONDITIONavec le détailStopped; - une requête vers un port répond HTTP 503, « stopped: resume it » ;
- seul
ResumeSandboxla 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
| Quoi | Pause | Arrêt | Duplication | Template | Suppression |
|---|---|---|---|---|---|
| Mémoire | Gardée | Perdue | Copiée | Non enregistrée | Disparue |
| Processus en cours | Gardés | Terminés | Copiés, en marche | Non enregistrés | Disparus |
| Fichiers et images Docker | Gardés | Gardés | Copiés | Enregistrés | Disparus |
| Conversations d’agents | Gardées | Gardées | Copiées | Non enregistrées | Disparues |
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.