---
title: "Templates : des sandboxes prêtes à travailler dès le démarrage | Pethost Agent Sandboxes"
description: "Enregistrez le disque d’une sandbox comme template, avec vos paquets et vos images Docker, et démarrez-en de nouvelles sur tout serveur en 0,2 s environ."
---

[Documentation Agent Sandboxes](https://pethost.dev/fr/docs/sandboxes/) · Tâches

# Templates : des sandboxes prêtes à travailler dès le démarrage

Mis à jour le 22 novembre 2026 · 7 min de lecture

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.

**En bref**

- **`CreateTemplate`** enregistre 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.
- **`CreateSandbox`** avec `"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](https://pethost.dev/fr/docs/sandboxes/commands-and-files/)). 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.

Python

```
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
```

TypeScript

```
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);
```

Go

```
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)
```

Rust

```
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);
```

CLI

```
$ 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
```

MCP

```
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.

Python

```
preview = sandboxes.create_sandbox("my-app")
print(preview.sandbox_id, preview.template)  # 8j37xshusqwdz8cs my-app@1
```

TypeScript

```
const preview = await sandboxes.createSandbox({ template: "my-app" });
console.log(preview.sandboxId, preview.template);
```

Go

```
preview, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "my-app"})
if err != nil {
	log.Fatal(err)
}
fmt.Println(preview.SandboxID, preview.Template)
```

Rust

```
let preview = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "my-app".into(), ..Default::default() })
    .await?;
println!("{} {}", preview.sandbox_id, preview.template);
```

CLI

```
$ 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
```

MCP

```
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](https://pethost.dev/fr/docs/sandboxes/forks/). 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_EXHAUSTED` avec `LimitReached`, `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_message` dit pourquoi, par exemple une version dont les propres octets dépassaient la place restante. Libérez de la place, puis enregistrez de nouveau.
- **`INVALID_ARGUMENT` qui nomme une taille :** la taille est plus petite que le `min_size` de 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.

[PrécédentComputer use : Chrome sur un bureau dans une sandbox](https://pethost.dev/fr/docs/sandboxes/computer-use/) [SuivantSecrets et trafic sortant : des clés qu’une sandbox ne détient jamais](https://pethost.dev/fr/docs/sandboxes/secrets-and-egress/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/fr/templates/)
- [À propos](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/fr/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Conditions](https://pethost.dev/terms/)
- [Confidentialité](https://pethost.dev/privacy/)
- [Remboursements](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bases de données

- [Postgres](https://pethost.dev/fr/postgres/)
- [Valkey](https://pethost.dev/fr/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/fr/sandboxes/)
- [Tarifs](https://pethost.dev/fr/sandboxes/#pricing)
- [Docs](https://pethost.dev/fr/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparatifs

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/fr/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/fr/blog/coolify-cloud-vs-dokploy-cloud/)
- [Tarifs Railway vs Render vs Fly.io](https://pethost.dev/fr/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hébergement Docker Compose managé](https://pethost.dev/fr/blog/managed-docker-compose-hosting/)

Alternatives

- [Alternatives à Railway](https://pethost.dev/fr/blog/railway-alternatives/)
- [Alternatives à Heroku](https://pethost.dev/fr/blog/heroku-alternatives/)
- [Alternatives à Dokploy](https://pethost.dev/fr/blog/dokploy-alternatives/)
- [Alternatives à Coolify](https://pethost.dev/fr/blog/coolify-alternatives/)
- [Alternatives à Render](https://pethost.dev/fr/blog/render-alternatives/)
- [Alternatives à Sliplane](https://pethost.dev/fr/blog/sliplane-alternatives/)
