Documentation Agent Sandboxes · Tâches
Templates : des sandboxes prêtes à travailler dès le démarrage
Un template, c’est ce à partir de quoi une sandbox démarre. Le nôtre, base, a les outils ; le vôtre est le disque d’une sandbox enregistré tel quel, avec les paquets que vous avez installés, votre code et ses images Docker. Une sandbox issue de lui démarre en 0,22 s environ, sans plus rien à installer.
CreateTemplateenregistre le disque et les paramètres d’une sandbox comme nouvelle version,my-app@1,my-app@2, pendant que la sandbox continue de tourner.- SAVING, puis READY en 1,5 s environ pour un petit template, et en 10 s environ par GiB de ses propres données.
CreateSandboxavec"my-app"démarre depuis sa version READY la plus récente, sur n’importe quel serveur.- Des fichiers seulement : un template ne garde ni mémoire, ni processus, ni conversations d’agents. Il n’est pas facturé ; votre offre borne sa taille.
Step 1: Préparez une sandbox
Créez une sandbox depuis base et installez-la comme devrait l’être chaque nouvelle : clonez votre code, installez ses dépendances, récupérez les images Docker qu’il fait tourner, chauffez les caches (commandes et fichiers). Ses paramètres comptent aussi : le template prend le cycle de vie, le trafic sortant, les ports publics et l’environnement de la sandbox tels qu’ils sont maintenant, et les sandboxes issues de lui démarrent avec, sauf si leur création dit autre chose.
Step 2: Enregistrez-la comme template
CreateTemplate répond en quelques millisecondes avec la nouvelle version SAVING, une fois qu’il tient le disque tel quel : la sandbox continue de tourner. Le serveur réduit ensuite la version à ce qu’elle contient et l’envoie. Attendez READY avant de démarrer depuis cette version.
import time
from pethost.sandboxes import TemplateState
version = sandboxes.create_template("my-app", sandbox_id=sandbox_id, description="Node 22 and our dependencies")
while version.state == TemplateState.SAVING:
time.sleep(1)
version = sandboxes.get_template(f"my-app@{version.version}")
print(version.name, version.version, version.state.name, version.min_size.name, version.size_bytes)
# my-app 1 READY SMALL 25447048
let version = await sandboxes.createTemplate({
name: "my-app",
sandboxId,
description: "Node 22 and our dependencies",
});
while (version.state === TemplateState.SAVING) {
await new Promise((resolve) => setTimeout(resolve, 1000));
version = await sandboxes.getTemplate({ template: `my-app@${version.version}` });
}
console.log(version.name, version.version, version.state, version.minSize, version.sizeBytes);
version, err := client.CreateTemplate(ctx, &sandboxes.CreateTemplateRequest{
Name: "my-app",
SandboxID: id,
Description: "Node 22 and our dependencies",
})
for err == nil && version.State == sandboxes.TemplateStateSaving {
time.Sleep(time.Second)
version, err = client.GetTemplate(ctx, &sandboxes.GetTemplateRequest{Template: fmt.Sprintf("my-app@%d", version.Version)})
}
if err != nil {
log.Fatal(err)
}
fmt.Println(version.Name, version.Version, version.State, version.MinSize, version.SizeBytes)
let mut version = sandboxes
.create_template(CreateTemplateRequest {
name: "my-app".into(),
sandbox_id: id.clone(),
description: "Node 22 and our dependencies".into(),
..Default::default()
})
.await?;
while matches!(version.state, TemplateState::Saving) {
tokio::time::sleep(std::time::Duration::from_secs(1)).await;
let template = format!("my-app@{}", version.version);
version = sandboxes.get_template(GetTemplateRequest { template, ..Default::default() }).await?;
}
println!("{} {} {:?} {:?} {}", version.name, version.version, version.state, version.min_size, version.size_bytes);
$ pethost sandbox template save api-dev my-app --description 'Node 22 and our dependencies'
✓ Saving my-app@2: it is ready once uploaded. See: pethost sandbox template show my-app@2
my-app@2
$ pethost sandbox template ls my-app
my-app@2 ready 68 MB 55 s ago Node 22 and our dependencies
my-app@1 ready 24 MB 1 min ago Node 22 and our dependencies
CreateTemplate {"name": "my-app", "sandbox_id": "…", "description": "Node 22 and our dependencies"}
ListTemplates {"name": "my-app"}
Step 3: Démarrez des sandboxes à partir de lui
Nommez le template dans CreateSandbox : "my-app" est sa version READY la plus récente, "my-app@2" exactement celle-là. La première sandbox d’une version sur un serveur la rapatrie, en 10 s environ par GiB ; le serveur la garde, et les suivantes démarrent en 0,22 s environ.
preview = sandboxes.create_sandbox("my-app")
print(preview.sandbox_id, preview.template) # 8j37xshusqwdz8cs my-app@1
const preview = await sandboxes.createSandbox({ template: "my-app" });
console.log(preview.sandboxId, preview.template);
preview, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "my-app"})
if err != nil {
log.Fatal(err)
}
fmt.Println(preview.SandboxID, preview.Template)
let preview = sandboxes
.create_sandbox(CreateSandboxRequest { template: "my-app".into(), ..Default::default() })
.await?;
println!("{} {}", preview.sandbox_id, preview.template);
$ pethost sandbox new --template my-app
✓ Made sandbox ofvm8by6buvd4rkd: default, running, from my-app@2, in <1 s
port 5173: https://5173-ofvm8by6buvd4rkd.sbx1.sandboxes.pethost.network
ofvm8by6buvd4rkd
Next: pethost sandbox run ofvm8by6buvd4rkd -- <command> · pethost sandbox shell ofvm8by6buvd4rkd
CreateSandbox {"template": "my-app"}
Le template de la réponse nomme la version exacte dont elle est partie, comme my-app@1.
Ce que garde un template
- Gardé : chaque fichier du disque de la sandbox, dont les paquets, votre code, les images et les conteneurs Docker ; et les paramètres de la sandbox, avec lesquels ses sandboxes démarrent sauf si leur création dit autre chose.
- Non gardé : la mémoire et les processus, si bien qu’une sandbox issue d’un template ne démarre avec rien de ce qui tournait ; l’historique des commandes et les conversations des agents de code, sans lesquels ses sandboxes démarrent.
- Neuf dans chaque sandbox : son propre ID, son nom d’hôte, son machine-id et son aléa noyau.
Pour copier une sandbox avec sa mémoire et ses processus, telle qu’elle est à cette seconde, dupliquez-la plutôt : duplications. Un template sert à de nombreuses sandboxes pendant des jours ; une duplication, à quelques copies tout de suite.
Versions et tailles
Chaque enregistrement sous un nom est sa version suivante. "my-app" désigne toujours la version READY la plus récente, la précédente pendant qu’une nouvelle s’enregistre : un enregistrement ne casse donc jamais vos créations. Un nom garde 10 versions ; une version FAILED ne prend aucune place et disparaît au bout d’un jour. Un espace de travail enregistre une version à la fois, et une sandbox garde la version dont elle est partie, même après la suppression du template.
Une version READY a un min_size : la plus petite taille dont le disque contient ce qu’elle a enregistré. Ses sandboxes prennent n’importe quelle taille à partir de celle-là. Une création avec une taille plus petite est refusée, avec le nom de celle qui convient.
Où il est gardé, et ce qu’il coûte
Une version est réduite à ce qu’elle contient, compressée, chiffrée avec sa propre clé et gardée en stockage objet dans l’UE, d’où chaque serveur peut démarrer des sandboxes. Seuls ses propres octets comptent, pas la base en dessous. Les templates ne sont pas facturés : votre offre borne ce que prennent ensemble les versions de l’espace de travail, 5 GiB avec l’offre à 20 $ et 30 GiB avec l’offre à 100 $ (Limits.template_gib ; Workspace.template_bytes est ce qu’elles prennent maintenant). DeleteTemplate supprime toutes les versions d’un nom et libère la place aussitôt ; les sandboxes créées à partir de lui continuent de tourner, de se mettre en pause et de reprendre.
Notre template : base
base est Ubuntu 24.04 avec les outils de build et git, Python 3, Node.js 22, Docker avec Compose, Claude Code, Codex et OpenCode, et un bureau avec Google Chrome. Nous le reconstruisons chaque mois, et aussitôt pour un correctif de sécurité de Chrome, du noyau ou d’un paquet. Template.base nomme la version sur laquelle démarrent les sandboxes d’un template, par une empreinte de ce qu’elle contient : une version que vous enregistrez garde la base sur laquelle sa sandbox a démarré, si bien que votre template ne change pas sous vos pieds.
Il n’y a pas de build depuis un Dockerfile : exécutez les étapes de votre Dockerfile dans une sandbox, ou docker build à l’intérieur, et enregistrez cette sandbox.
Quand ça ne marche pas
RESOURCE_EXHAUSTEDavecLimitReached,template_gib: les versions de l’espace de travail occupent la place de son offre, ou une autre version est en cours d’enregistrement. Supprimez un ancien template, ou attendez la fin de l’enregistrement.LimitReached,template_versions: le nom a 10 versions. Enregistrez sous un nouveau nom, ou supprimez le template et enregistrez de nouveau.- La version est FAILED :
failure_messagedit pourquoi, par exemple une version dont les propres octets dépassaient la place restante. Libérez de la place, puis enregistrez de nouveau. INVALID_ARGUMENTqui nomme une taille : la taille est plus petite que lemin_sizede la version. Demandez cette taille ou une plus grande.- La première sandbox d’une nouvelle version est lente : son serveur a rapatrié la version, en 10 s environ par GiB. Les suivantes y démarrent en 0,22 s environ.
Questions
Comment créer un template de sandbox personnalisé ?
Installez une sandbox comme vous voulez les nouvelles, puis appelez CreateTemplate avec un nom et son ID. Démarrez de nouvelles sandboxes avec ce nom.
Un template garde-t-il les processus en cours ?
Non : les fichiers et les paramètres seulement. Pour copier une sandbox active avec sa mémoire et ses processus, dupliquez-la.
Les templates sont-ils facturés ?
Non. Votre offre borne combien de GiB les templates de l’espace de travail occupent en stockage objet.
Puis-je construire un template depuis un Dockerfile ?
Pas directement : exécutez les étapes du Dockerfile, ou docker build, dans une sandbox, puis enregistrez la sandbox comme template.
Les images Docker survivent-elles dans un template ?
Oui. Les images et les conteneurs Docker sont sur le disque de la sandbox, que le template garde.
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.