Documentation Agent Sandboxes · Notions
Bonnes pratiques pour Pethost Agent Sandboxes
Une poignée de choix décident de la vitesse à laquelle vos sandboxes démarrent, de ce qu’elles coûtent pendant qu’elles attendent, et de ce qu’un agent peut atteindre depuis l’une d’elles. Chaque pratique ci-dessous est une règle, le chiffre qui la justifie, et les champs qui la mettent en œuvre. La plupart sont un paramètre que vous réglez une fois.
- Vitesse : enregistrez votre installation comme template, démarrez les serveurs avec
wait_for_port, et dupliquez pour des essais en parallèle. - Coût : laissez la sandbox d’un agent se mettre en pause plutôt que s’arrêter, supprimez les sandboxes d’un lot quand elles ont fini, et commencez petit.
- Fiabilité : marquez les longues commandes
keep_awake, réessayez avecrequest_id, suivez les flux plutôt que d’interroger en boucle, et gardez les volumes pour ce qui doit survivre à une sandbox. - Sécurité : liez les clés d’API comme secrets, restreignez le trafic sortant pour le code que vous n’avez pas écrit, et traitez tout ce que renvoie une sandbox comme des données.
- Ordre : mettez des labels sur chaque sandbox, et listez-les par label.
Vitesse
Enregistrez votre installation comme template
Installer vos dépendances à chaque démarrage coûte les mêmes minutes à chaque fois. Installez-les une fois dans une sandbox, puis enregistrez son disque avec CreateTemplate : paquets, caches de build et images Docker compris. Une sandbox issue de votre template démarre en 0,22 s environ avec tout en place, sur n’importe quel serveur : la première sur chaque serveur rapatrie la version, en 10 s environ par GiB, et les suivantes démarrent depuis sa copie. Gardez les secrets hors des fichiers que vous enregistrez, puisque chaque sandbox créée à partir du template les reçoit, et créez une nouvelle version quand vos dépendances changent : my-app démarre depuis la plus récente, my-app@3 depuis celle-là.
Démarrez les serveurs avec wait_for_port
Un serveur de développement met un moment à écouter, et l’interroger de l’extérieur gaspille des appels. Lancez-le avec wait_for_port : RunCommand répond dès que quelque chose écoute sur ce port, pendant que la commande continue, si bien qu’un seul appel démarre le serveur et vous dit qu’il est prêt. Ouvrez ensuite le port en public, ou donnez à votre page un token pour lui : ports et prévisualisations.
Dupliquez pour des essais en parallèle
Quand un agent doit essayer plusieurs correctifs, ou qu’une évaluation doit lancer de nombreuses exécutions depuis un même état préparé, dupliquez la sandbox au lieu de reconstruire cet état. ForkSandbox copie mémoire, processus et disque dans 100 nouvelles sandboxes au plus, en un appel : une copie a pris environ 0,25 s. Chaque copie est un démarrage, et toutes sont créées ou aucune. Deux choses à savoir :
- Réensemencez les générateurs aléatoires dans les copies. Chaque copie a son propre aléa noyau, mais les générateurs aléatoires qui tournent déjà dans ses processus (ceux d’OpenSSL, de Python, de Node, de Go) donnent les mêmes nombres dans chaque copie jusqu’à ce qu’ils soient réensemencés.
- Un volume en lecture-écriture refuse une duplication, puisqu’une seule sandbox peut y écrire. Un volume ne se monte qu’à la création : montez-le donc avec
read_onlydans une sandbox que vous comptez dupliquer.
Coût
Laissez la sandbox d’un agent se mettre en pause, pas s’arrêter
La sandbox d’un agent attend la plupart du temps, et l’arrêter met fin à ses processus : le serveur de développement, le REPL, le navigateur qu’il avait ouvert. Gardez le délai de pause, et allongez le délai d’arrêt ou désactivez-le (stop_after_idle_seconds à 0). En pause, la sandbox coûte 30 % de son prix d’exécution et se réveille au prochain appel en 0,1 s environ, avec tout là où c’était. Une sandbox DEFAULT au travail 2 heures par jour et en pause le reste du temps coûte environ 9,42 $ par mois, contre 26,28 $ toujours active.
La session d’un agentEn pause entre les tours, jamais arrêtée
- active
- en pause
- active
- en pause
La sandbox d’un utilisateur de votre applicationEn pause, puis arrêtée au bout d’une demi-heure
- active
- en pause
- arrêtée
Une prévisualisation qui dortSe réveille à chaque visite
- en pause
- active
- en pause
- active
- en pause
Un traitement par lotsTourne, puis est supprimée
- active
- arrêtée
- supprimée
- RUNNING
- PAUSED
- STOPPED
- DELETED
Supprimez les sandboxes d’un lot quand elles ont fini
Une sandbox pour une seule tâche, une exécution de tests ou un cas d’évaluation, ne devrait plus rien coûter une fois la tâche finie. Appelez DeleteSandbox à la fin, et fixez delete_after_idle_seconds comme filet pour une tâche qui meurt avant d’y arriver. Désactivez le délai de pause et donnez-lui un délai d’arrêt court, pour que la sandbox d’une tâche inactive s’en aille vite. Une sandbox arrêtée que vous oubliez coûte 0,03 $ par GiB et par mois, chaque mois. Les démarrages sont gratuits : une sandbox neuve par tâche ne coûte donc que ses secondes, et 1 000 exécutions de 40 s en SMALL coûtent 0,20 $.
Commencez petit, et changez de taille au besoin
Une taille, ce sont ses vCPU, sa mémoire et son disque, et son prix double à chaque taille au-dessus. Commencez avec SMALL, 0,018 $ de l’heure, et surveillez GetSandboxMetrics. Quand une tâche a besoin de plus, UpdateSandbox avec une nouvelle taille redémarre une sandbox RUNNING dans une VM de cette taille, ses fichiers gardés, en 283 ms environ : ses processus prennent fin, alors changez de taille entre deux tâches. Ajoutez grow_disk pour agrandir le disque à celui de la nouvelle taille ; un disque ne rétrécit jamais, donc une sandbox agrandie ne peut pas revenir à une taille plus petite.
Fiabilité
Marquez les longues commandes keep_awake
Un build ou une suite de tests peut tourner des minutes sans aucun appel vers la sandbox, et le délai de pause la mettrait en pause en plein travail. Lancez-le avec keep_awake, et avec timeout_seconds, pour qu’une commande bloquée ne garde pas la sandbox active pour toujours. Un serveur n’a besoin ni de l’un ni de l’autre : une requête vers son port réveille la sandbox. Cycle de vie et inactivité donne les détails.
Réessayez avec request_id
Un réseau peut perdre la réponse d’un appel qui a fait son travail. Un appel qui crée quelque chose prend un request_id : un nouvel essai avec le même ID dans les 24 heures répond ce qu’a fait le premier appel, sans rien refaire. CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand et PromptAgent en prennent un. Créez-le une fois par chose que vous voulez faire, gardez-le, et renvoyez-le à chaque nouvel essai. Une réserve : une sandbox garde sur son disque les ID de ce qui tourne en elle, si bien qu’une sandbox arrêtée a pu perdre ceux de ses dernières secondes, et un nouvel essai d’une telle commande la relance.
import uuid
from pethost.sandboxes import Label, Sandboxes
sandboxes = Sandboxes() # The token: PETHOST_TOKEN.
request_id = str(uuid.uuid4()) # Keep it: a retry sends the same one.
sandbox = sandboxes.create_sandbox(
template="my-app",
labels=[Label(key="user", value="42"), Label(key="job", value="nightly-evals")],
request_id=request_id,
)
import { Sandboxes } from "pethost/sandboxes";
const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const requestId = crypto.randomUUID(); // Keep it: a retry sends the same one.
const sandbox = await sandboxes.createSandbox({
template: "my-app",
labels: [{ key: "user", value: "42" }, { key: "job", value: "nightly-evals" }],
requestId,
});
requestID := rand.Text() // crypto/rand. Keep it: a retry sends the same one.
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
Template: "my-app",
Labels: []sandboxes.Label{{Key: "user", Value: "42"}, {Key: "job", Value: "nightly-evals"}},
RequestID: requestID,
})
let request_id = uuid::Uuid::new_v4().to_string(); // Keep it: a retry sends the same one.
let sandbox = sandboxes
.create_sandbox(CreateSandboxRequest {
template: "my-app".into(),
labels: vec![
Label { key: "user".into(), value: "42".into() },
Label { key: "job".into(), value: "nightly-evals".into() },
],
request_id: request_id.clone(),
..Default::default()
})
.await?;
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
-H "Authorization: Bearer $PETHOST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}'
Suivez les flux plutôt que d’interroger en boucle
Interroger une commande ou une sandbox en boucle coûte un appel à chaque fois, et apprend quand même tard. Un appel qui attend fait l’attente pour vous : RunCommand, GetCommand, PromptAgent et GetAgentTurn attendent jusqu’à 45 s (wait_seconds) et répondent dès que le travail se termine. Pour suivre le travail au fil de l’eau, suivez son flux : WatchCommand pour la sortie d’une commande, WatchConversation pour les messages et appels d’outils d’un agent, WatchSandboxEvents pour le cycle de vie, les commandes et les connexions d’une sandbox.
N’utilisez les volumes que pour ce qui doit survivre à une sandbox
Un volume est un disque hors de toute sandbox, monté sur un chemin : jeux de données, caches partagés par de nombreuses sandboxes, fichiers d’une base de données. Il vit sur le disque d’un seul serveur et n’est copié nulle part : si ce serveur est perdu, le volume l’est aussi. Une sandbox qui en monte un ne peut pas passer sur un autre serveur, et un montage en lecture-écriture refuse les duplications. La plupart des travaux n’ont pas besoin de volume : le disque propre d’une sandbox survit aux pauses et aux arrêts, et un template porte des fichiers vers de nouvelles sandboxes. Ce qui ne doit pas être perdu, envoyez-le aussi vers un stockage à vous.
Sécurité
Liez les clés d’API comme secrets
Une clé dans une simple variable d’environnement est lisible par chaque processus de la sandbox, et par un agent qui affiche son environnement. Enregistrez-la plutôt comme secret de l’espace de travail, avec les hôtes auxquels elle est destinée (SetSecret : anthropic, api.anthropic.com), et liez-y une variable (ANTHROPIC_API_KEY, secret anthropic). La variable contient alors un marqueur, phs_…, et le proxy de sortie met la vraie clé dans les en-têtes des requêtes HTTPS vers ces hôtes seulement. Une nouvelle valeur marche aussitôt dans chaque sandbox qui la lie : secrets et trafic sortant.
Restreignez le trafic sortant pour le code que vous n’avez pas écrit
Par défaut, une sandbox peut se connecter n’importe où. Pour du code non fiable, listez où il peut aller (egress.allow) : un domaine comme pypi.org, ses sous-domaines avec *.github.com (qui exclut github.com lui-même), une IP ou un CIDR, chacun avec un port quand ce n’est ni 80 ni 443, comme github.com:22 pour git sur SSH. deny l’emporte sur allow. Le DNS de la sandbox ne répond qu’aux noms que la liste autorise, et seuls TCP et DNS sortent d’une sandbox : pas d’UDP, ni de ping. Un changement s’applique aussitôt et ferme les connexions qu’il n’autorise plus.
Traitez ce que renvoie une sandbox comme des données
La sortie des commandes, le contenu des fichiers, les messages d’un agent, les captures d’écran et les pages que charge un navigateur viennent de programmes et d’Internet. Quand un modèle les lit, ce sont des données, jamais des instructions : un README ou une page web peut contenir un texte écrit pour piloter un agent. Gardez cette limite dans vos prompts, et ne donnez pas à une sandbox qui exécute un travail non fiable plus de secrets ni un trafic sortant plus large que ce dont le travail a besoin.
Ordre
Mettez des labels sur chaque sandbox
Un label est une clé et une valeur à vous : user=42, job=nightly-evals, run=7f3a. Une sandbox en prend jusqu’à 32, et ListSandboxes liste les sandboxes qui ont tous les labels que vous nommez. Votre application trouve ainsi les sandboxes d’un utilisateur sans table à elle, une tâche de nettoyage trouve les restes d’une exécution, et la console montre à qui est chaque sandbox. Un label sert à en trouver plusieurs ; un name sert à en appeler une : unique dans l’espace de travail, jusqu’à 63 caractères parmi a-z, 0-9 et « - », et ListSandboxes avec name trouve son ID.
Questions
Faut-il arrêter ou mettre en pause une sandbox inactive ?
Mettez-la en pause quand ses processus comptent ou qu’elle va bientôt resservir : elle se réveille en 0,1 s environ là où elle en était, à 30 % du prix d’exécution. Arrêtez-la pour un long sommeil : elle ne coûte alors que ses données stockées.
Comment faire démarrer les sandboxes plus vite ?
Enregistrez votre installation comme template, pour que rien ne s’installe au démarrage : une sandbox issue de lui démarre en 0,22 s environ avec vos paquets et vos images Docker.
Comment garder les clés d’API hors d’une sandbox ?
Enregistrez chaque clé comme secret de l’espace de travail avec ses hôtes, et liez-y une variable d’environnement. La sandbox voit un marqueur, et le proxy de sortie ajoute la vraie clé aux requêtes vers ces hôtes.
Combien de sandboxes puis-je faire tourner en même temps ?
Autant que les vCPU de votre offre en tiennent, actives ou en pause : 10 SMALL avec l’offre à 20 $, 64 avec l’offre à 100 $. Les sandboxes arrêtées ne comptent pas.
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.