Français
Menu de la documentation

Documentation Agent Sandboxes · Tâches

Volumes : un disque qui survit aux sandboxes

Mis à jour le · 6 min de lecture

Un volume est un disque hors de toute sandbox, monté dans l’une d’elles sur un chemin : un jeu de données que lisent de nombreuses sandboxes, un cache qui survit à chaque tâche, des fichiers qu’une sandbox supprimée doit laisser derrière elle. Il vit sur le disque d’un seul serveur, et c’est ce qu’il faut savoir avant d’y mettre quoi que ce soit.

En bref
  • CreateVolume en crée un de 1 à 1 000 GiB ; CreateSandbox en monte jusqu’à 4 à la création, chacun sur un chemin.
  • En lecture-écriture par une seule sandbox à la fois, en lecture seule par autant que vous voulez.
  • Sur un seul serveur, sans copie : une sandbox qui le monte tourne là, et si ce serveur est perdu, le volume l’est aussi.
  • Facturé sur toute sa taille, 0,20 $ par GiB et par mois, utilisée ou non.

Step 1: Créez un volume

Un volume est créé vide, sur un serveur qui a de la place, et sa racine appartient à user.

Python
volume = sandboxes.create_volume("data", size_gib=10)
print(volume.volume_id, volume.size_gib)  # ziwv1r8ean3dd9sk 10
TypeScript
const volume = await sandboxes.createVolume({ name: "data", sizeGib: 10 });
console.log(volume.volumeId, volume.sizeGib);
Go
volume, err := client.CreateVolume(ctx, &sandboxes.CreateVolumeRequest{Name: "data", SizeGib: 10})
if err != nil {
	log.Fatal(err)
}
fmt.Println(volume.VolumeID, volume.SizeGib)
Rust
let volume = sandboxes
    .create_volume(CreateVolumeRequest { name: "data".into(), size_gib: 10, ..Default::default() })
    .await?;
println!("{} {}", volume.volume_id, volume.size_gib);
CLI
$ pethost sandbox volume new data --size 10
✓ Made the volume data, 10 GiB. Mount it:  pethost sandbox new --mount o2rvhgm1dxaefoj7:/data
o2rvhgm1dxaefoj7

Step 2: Montez-le dans une sandbox

Les montages se donnent à la création, chacun un volume et un chemin absolu. La sandbox tourne sur le serveur du volume.

Python
from pethost.sandboxes import Mount

writer = sandboxes.create_sandbox("base", mounts=[Mount(volume_id=volume.volume_id, path="/data")])
sandboxes.run_command(writer.sandbox_id, command="date > /data/first-run.txt")
TypeScript
const writer = await sandboxes.createSandbox({
  template: "base",
  mounts: [{ volumeId: volume.volumeId, path: "/data" }],
});
await sandboxes.runCommand({ sandboxId: writer.sandboxId, command: "date > /data/first-run.txt" });
Go
writer, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template: "base",
	Mounts:   []sandboxes.Mount{{VolumeID: volume.VolumeID, Path: "/data"}},
})
if err != nil {
	log.Fatal(err)
}
_, err = client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: writer.SandboxID, Command: "date > /data/first-run.txt"})
Rust
let mount = Mount { volume_id: volume.volume_id.clone(), path: "/data".into(), ..Default::default() };
let writer = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "base".into(), mounts: vec![mount], ..Default::default() })
    .await?;
sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: writer.sandbox_id.clone(),
        command: "date > /data/first-run.txt".into(),
        ..Default::default()
    })
    .await?;
CLI
$ pethost sandbox new --name writer --mount o2rvhgm1dxaefoj7:/data
✓ Made sandbox writer (upc3ehxd65rjgz32): default, running, from base@17, in <1 s
upc3ehxd65rjgz32
Next:   pethost sandbox run upc3ehxd65rjgz32 -- <command>   ·   pethost sandbox shell upc3ehxd65rjgz32
$ pethost sandbox run writer -- 'date > /data/first-run.txt'
MCP
CreateSandbox {"name": "writer", "mounts": [{"volume_id": "…", "path": "/data"}]}

Step 3: Partagez-le en lecture seule, et supprimez-le à la fin

Dès qu’aucune sandbox ne le monte en lecture-écriture, autant de sandboxes que vous voulez peuvent le monter en lecture seule. Un volume reste quand les sandboxes qui l’ont monté sont supprimées, et ne disparaît que par DeleteVolume, refusé tant qu’une sandbox le monte.

Python
sandboxes.delete_sandbox(writer.sandbox_id)
reader = sandboxes.create_sandbox("base", mounts=[Mount(volume_id=volume.volume_id, path="/data", read_only=True)])
print(sandboxes.run_command(reader.sandbox_id, command="cat /data/first-run.txt").stdout)  # Sun Nov 22 00:25:33 UTC 2026
sandboxes.delete_sandbox(reader.sandbox_id)
sandboxes.delete_volume(volume.volume_id)
TypeScript
await sandboxes.deleteSandbox({ sandboxId: writer.sandboxId });
const reader = await sandboxes.createSandbox({
  template: "base",
  mounts: [{ volumeId: volume.volumeId, path: "/data", readOnly: true }],
});
console.log((await sandboxes.runCommand({ sandboxId: reader.sandboxId, command: "cat /data/first-run.txt" })).stdout);
await sandboxes.deleteSandbox({ sandboxId: reader.sandboxId });
await sandboxes.deleteVolume({ volumeId: volume.volumeId });
Go
if _, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: writer.SandboxID}); err != nil {
	log.Fatal(err)
}
reader, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template: "base",
	Mounts:   []sandboxes.Mount{{VolumeID: volume.VolumeID, Path: "/data", ReadOnly: true}},
})
if err != nil {
	log.Fatal(err)
}
read, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: reader.SandboxID, Command: "cat /data/first-run.txt"})
if err != nil {
	log.Fatal(err)
}
fmt.Print(read.Stdout)
_, err = client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: reader.SandboxID})
if err == nil {
	_, err = client.DeleteVolume(ctx, &sandboxes.DeleteVolumeRequest{VolumeID: volume.VolumeID})
}
Rust
sandboxes
    .delete_sandbox(DeleteSandboxRequest { sandbox_id: writer.sandbox_id.clone(), ..Default::default() })
    .await?;
let mount = Mount { volume_id: volume.volume_id.clone(), path: "/data".into(), read_only: true };
let reader = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "base".into(), mounts: vec![mount], ..Default::default() })
    .await?;
let read = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: reader.sandbox_id.clone(),
        command: "cat /data/first-run.txt".into(),
        ..Default::default()
    })
    .await?;
print!("{}", read.stdout);
sandboxes
    .delete_sandbox(DeleteSandboxRequest { sandbox_id: reader.sandbox_id.clone(), ..Default::default() })
    .await?;
sandboxes
    .delete_volume(DeleteVolumeRequest { volume_id: volume.volume_id.clone(), ..Default::default() })
    .await?;
CLI
$ pethost sandbox rm writer --yes
upc3ehxd65rjgz32   deleted
$ pethost sandbox new --name reader --mount o2rvhgm1dxaefoj7:/data:ro
✓ Made sandbox reader (zc44605gliwn2v1b): default, running, from base@17, in <1 s
zc44605gliwn2v1b
Next:   pethost sandbox run zc44605gliwn2v1b -- <command>   ·   pethost sandbox shell zc44605gliwn2v1b
$ pethost sandbox run reader -- cat /data/first-run.txt
Sun Nov 22 00:25:40 UTC 2026
$ pethost sandbox rm reader --yes
zc44605gliwn2v1b   deleted
$ pethost sandbox volume rm o2rvhgm1dxaefoj7 --yes
o2rvhgm1dxaefoj7

Où vit un volume

Un volume est un fichier sur le disque d’un seul serveur de sandboxes, qui contient un système de fichiers ext4, et une sandbox qui le monte tourne sur ce serveur. Il n’est copié ni vers le stockage objet ni vers un autre serveur. Cela a trois effets :

  • Si son serveur est perdu, le volume est perdu : il passe DELETED, et les sandboxes qui le montaient le perdent. N’y gardez la seule copie de rien : envoyez aussi ce qui compte vers un stockage à vous.
  • Une sandbox avec un volume reste sur son serveur. Une sandbox arrêtée sans volume peut démarrer sur un autre serveur quand le sien est plein ; une sandbox avec un volume attend de la place sur le sien, et est refusée avec NoCapacity entre-temps.
  • Une sandbox avec un volume en lecture-écriture ne peut pas être dupliquée : une seule sandbox à la fois écrit dans un volume.

Un volume partage la vitesse de disque de la sandbox qui le monte, 64 MiB/s par vCPU. Un volume plus grand que la moitié du disque d’un serveur est refusé.

Les volumes et le disque propre d’une sandbox

La plupart des travaux n’ont pas besoin de volume. Le disque propre d’une sandbox survit à ses pauses et à ses arrêts : le disque d’une sandbox arrêtée est gardé en stockage objet, et revient à sa reprise, sur n’importe quel serveur. Un template porte des fichiers vers chaque nouvelle sandbox. Un volume sert aux données qui survivent aux sandboxes qui les utilisent, ou que beaucoup lisent en même temps : un jeu de données, les poids d’un modèle, un cache partagé.

Ce qu’il coûte

Un volume compte toute sa taille, 0,20 $ par GiB et par mois, à la seconde, de sa création à sa suppression, qu’une sandbox le monte ou non. Votre offre borne ce que prennent ensemble les volumes de l’espace de travail : 100 GiB avec l’offre à 20 $, 600 GiB avec l’offre à 100 $, 10 GiB pendant l’essai gratuit. Workspace.volume_gib_used dit ce qu’ils prennent maintenant.

Quand ça ne marche pas

  • FAILED_PRECONDITION, le volume est monté par une autre sandbox : il est monté en lecture-écriture. Montez-le en lecture seule, ou supprimez ou arrêtez la sandbox qui y écrit.
  • FAILED_PRECONDITION, son journal doit peut-être être rejoué : la dernière sandbox qui y a écrit s’est terminée avant de le démonter. Montez-le une fois en lecture-écriture, puis de nouveau en lecture seule.
  • FAILED_PRECONDITION sur DeleteVolume : une sandbox le monte. Supprimez d’abord cette sandbox.
  • RESOURCE_EXHAUSTED avec LimitReached, volume_gib : les volumes de l’espace de travail dépasseraient les GiB de l’offre. Supprimez-en un, ou créez-le plus petit.
  • UNAVAILABLE avec NoCapacity à une création ou une reprise : le serveur du volume n’a pas de place pour l’instant, et une sandbox avec un volume ne peut pas aller ailleurs. Réessayez plus tard.

Questions

Un volume est-il sauvegardé ?

Non. Il vit sur le disque d’un seul serveur et n’est copié nulle part : gardez ailleurs une copie de ce qui compte.

Plusieurs sandboxes peuvent-elles partager un volume ?

En lecture seule, autant que vous voulez en même temps. En lecture-écriture, une à la fois.

Puis-je monter un volume dans une sandbox active ?

Non : les montages se donnent à la création, jusqu’à 4 par sandbox.

Un volume est-il facturé quand rien ne le monte ?

Oui, sur toute sa taille, 0,20 $ par GiB et par mois, jusqu’à ce que vous le supprimiez.

Ai-je besoin d’un volume pour garder des fichiers entre deux sessions ?

Non. Le disque propre d’une sandbox survit aux pauses et aux arrêts ; un volume sert aux données qui survivent à la sandbox.

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