Français
Menu de la documentation

Documentation Agent Sandboxes · Tâches

Dupliquer une sandbox (fork), mémoire et processus compris

Mis à jour le · 6 min de lecture

Une duplication copie une sandbox telle qu’elle est à cet instant, sa mémoire, ses processus en cours et son disque, dans de nouvelles sandboxes qui repartent de là. Un agent essaie trois correctifs à la fois depuis le même état, une évaluation lance cent graines depuis un même environnement préparé, et les copies perdantes sont supprimées.

En bref
  • ForkSandbox crée jusqu’à 100 copies en un appel, RUNNING sur le serveur de la source ; trois prennent environ 0,25 s.
  • La source continue : une source active se met en pause quelques millisecondes ; une source en pause reste en pause ; les copies d’une source arrêtée partent de son disque.
  • Chaque copie a son propre ID, son nom d’hôte, son machine-id et son aléa noyau, la taille de la source, et pas de nom.
  • Tout ou rien : chaque copie est un démarrage et compte ses vCPU ; si elles ne tiennent pas toutes, aucune n’est créée.

Step 1: Dupliquez la sandbox

Donnez aux copies un label à elles, pour les retrouver ensemble plus tard. Sans label, elles prennent ceux de la source.

Python
from pethost.sandboxes import Label

run = Label(key="run", value="seeds-7")
copies = sandboxes.fork_sandbox(sandbox_id, count=3, labels=[run]).sandboxes
print([copy.sandbox_id for copy in copies])
# ['kecrb56zb2sqfmy0', '9pd5esg1e2vguf1j', 'zawco1pzbjzgxjyy']
TypeScript
const run = { key: "run", value: "seeds-7" };
const { sandboxes: copies } = await sandboxes.forkSandbox({ sandboxId, count: 3, labels: [run] });
console.log(copies.map((copy) => copy.sandboxId));
Go
run := sandboxes.Label{Key: "run", Value: "seeds-7"}
forked, err := client.ForkSandbox(ctx, &sandboxes.ForkSandboxRequest{SandboxID: id, Count: 3, Labels: []sandboxes.Label{run}})
if err != nil {
	log.Fatal(err)
}
for _, copy := range forked.Sandboxes {
	fmt.Println(copy.SandboxID)
}
Rust
let run = Label { key: "run".into(), value: "seeds-7".into() };
let copies = sandboxes
    .fork_sandbox(ForkSandboxRequest {
        sandbox_id: id.clone(),
        count: 3,
        labels: vec![run.clone()],
        ..Default::default()
    })
    .await?
    .sandboxes;
for copy in &copies {
    println!("{}", copy.sandbox_id);
}
CLI
$ pethost sandbox fork api-dev --count 3 --label run=seeds-7
✓ Forked api-dev into 3 sandboxes in 1 s
us8wjivt4ndyu3mn
7sfjrgzwk72v3ie4
955mpq7p89sfaezv
MCP
ForkSandbox {"sandbox_id": "…", "count": 3, "labels": [{"key": "run", "value": "seeds-7"}]}

Step 2: Donnez à chaque copie son propre travail

Chaque copie répond à ses propres appels. Lancez une tâche différente dans chacune, sans l’attendre, et marquez-la keep_awake pour qu’aucune copie ne se mette en pause en plein travail.

Python
for seed, copy in enumerate(copies):
    sandboxes.run_command(
        copy.sandbox_id,
        command=f"python3 experiment.py --seed {seed} > result.txt",
        wait_seconds=0,
        keep_awake=True,
    )
TypeScript
await Promise.all(
  copies.map((copy, seed) =>
    sandboxes.runCommand({
      sandboxId: copy.sandboxId,
      command: `python3 experiment.py --seed ${seed} > result.txt`,
      waitSeconds: 0,
      keepAwake: true,
    }),
  ),
);
Go
for seed, copy := range forked.Sandboxes {
	_, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
		SandboxID:   copy.SandboxID,
		Command:     fmt.Sprintf("python3 experiment.py --seed %d > result.txt", seed),
		WaitSeconds: new(uint32(0)),
		KeepAwake:   true,
	})
	if err != nil {
		log.Fatal(err)
	}
}
Rust
for (seed, copy) in copies.iter().enumerate() {
    sandboxes
        .run_command(RunCommandRequest {
            sandbox_id: copy.sandbox_id.clone(),
            command: format!("python3 experiment.py --seed {seed} > result.txt"),
            wait_seconds: Some(0),
            keep_awake: true,
            ..Default::default()
        })
        .await?;
}

Step 3: Gardez celle qui a marché, supprimez les autres

ListSandboxes avec le label de l’exécution trouve les copies ; supprimez celles que vous ne gardez pas. Une copie que vous gardez est une sandbox comme une autre : donnez-lui un nom avec UpdateSandbox.

Python
best = copies[0].sandbox_id  # the copy whose result you keep
for copy in sandboxes.list_sandboxes(labels=[run]).sandboxes:
    if copy.sandbox_id != best:
        sandboxes.delete_sandbox(copy.sandbox_id)
TypeScript
const best = copies[0]!.sandboxId; // the copy whose result you keep
const { sandboxes: found } = await sandboxes.listSandboxes({ labels: [run] });
for (const copy of found) {
  if (copy.sandboxId !== best) await sandboxes.deleteSandbox({ sandboxId: copy.sandboxId });
}
Go
best := forked.Sandboxes[0].SandboxID // the copy whose result you keep
found, err := client.ListSandboxes(ctx, &sandboxes.ListSandboxesRequest{Labels: []sandboxes.Label{run}})
if err != nil {
	log.Fatal(err)
}
for _, copy := range found.Sandboxes {
	if copy.SandboxID != best {
		if _, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: copy.SandboxID}); err != nil {
			log.Fatal(err)
		}
	}
}
Rust
let best = copies[0].sandbox_id.clone(); // the copy whose result you keep
let found = sandboxes
    .list_sandboxes(ListSandboxesRequest { labels: vec![run], ..Default::default() })
    .await?;
for copy in found.sandboxes.iter().filter(|copy| copy.sandbox_id != best) {
    let gone = DeleteSandboxRequest { sandbox_id: copy.sandbox_id.clone(), ..Default::default() };
    sandboxes.delete_sandbox(gone).await?;
}
CLI
$ pethost sandbox ls --label run=seeds-7
ID                 NAME   STATE     SIZE      TEMPLATE   CREATED    LABELS
us8wjivt4ndyu3mn          running   default   base@17    20 s ago   run=seeds-7
955mpq7p89sfaezv          running   default   base@17    20 s ago   run=seeds-7
7sfjrgzwk72v3ie4          running   default   base@17    20 s ago   run=seeds-7
$ pethost sandbox rm us8wjivt4ndyu3mn 7sfjrgzwk72v3ie4 --yes
us8wjivt4ndyu3mn   deleted
7sfjrgzwk72v3ie4   deleted

Ce qu’a une copie

Une copie est la source telle qu’elle était au moment de la duplication : les mêmes fichiers, la même mémoire, les mêmes processus à la même instruction. Un serveur de développement continue de servir, une session Python garde ses variables, la conversation d’un agent de code est là pour être poursuivie, dans chaque copie. Les copies tournent sur le serveur de la source, à la taille de la source et avec son disque. Leurs autres paramètres sont ceux de la source, sauf si la duplication envoie un groupe à elle (settings), comme un autre trafic sortant ou un autre environnement ; une autre taille est refusée.

Chaque copie reçoit son propre ID, qui est aussi son nom d’hôte, son propre machine-id et un aléa noyau neuf : /dev/urandom diffère donc dès la première lecture. Elle n’a pas de nom : les noms sont uniques, et UpdateSandbox en donne un à une copie que vous gardez.

Réensemencez ce qui génère des nombres aléatoires

Le noyau est réensemencé dans chaque copie ; le générateur propre à un processus, non. Un générateur aléatoire ensemencé avant la duplication, le random de Python, le math/rand de Go, le Math.random de V8, celui d’OpenSSL, donne les mêmes nombres dans chaque copie jusqu’à ce qu’il soit réensemencé, et les clés créées avant la duplication sont les mêmes dans chaque copie. Ensemencez les expériences après la duplication, comme le fait la graine ci-dessus, et créez les clés après aussi.

La source, et ce que coûte une duplication

  • Une source RUNNING se met en pause quelques millisecondes, le temps de prendre sa mémoire et son disque, puis continue.
  • Une source PAUSED reste en pause, et ses copies démarrent depuis sa mémoire enregistrée.
  • Une source STOPPED n’a pas de mémoire : ses copies démarrent depuis son disque, comme un boot.

Une duplication, c’est tout ou rien. Chaque copie compte ses vCPU dans votre offre dès son démarrage, et chacune est un démarrage dans les limites par minute, par heure et par jour de l’offre. Les démarrages sont gratuits : une copie coûte ce qu’elle tourne, à la seconde, comme toute sandbox. Quand le serveur de la source n’a pas de place pour toutes les copies, l’appel est refusé avec UNAVAILABLE et NoCapacity, dont le fork_count dit combien tiendraient. Une sandbox avec un volume en lecture-écriture ne peut pas être dupliquée, puisqu’une seule sandbox à la fois écrit dans un volume.

Quand ça ne marche pas

  • UNAVAILABLE avec NoCapacity : le serveur de la source n’a pas de place pour toutes les copies. Demandez fork_count copies ou moins, ou réessayez plus tard.
  • RESOURCE_EXHAUSTED avec LimitReached, vcpus : les copies dépasseraient les vCPU de votre offre. Supprimez des sandboxes dont vous n’avez plus besoin, ou faites moins de copies.
  • LimitReached avec une limite starts_per_* : les copies dépasseraient les démarrages d’une fenêtre ; retry_time dit quand elles passeront. Une duplication de plus de copies que la limite elle-même n’a pas de retry_time : découpez-la.
  • FAILED_PRECONDITION : la sandbox monte un volume en lecture-écriture. Dupliquez-en une qui le monte en lecture seule, ou qui n’en monte aucun.
  • Chaque copie affiche les mêmes nombres aléatoires : le générateur a été ensemencé avant la duplication. Réensemencez-le dans chaque copie.

Questions

Comment cloner une sandbox active ?

ForkSandbox avec count : chaque copie a la mémoire, les processus et le disque de la source, et repart de là où en était la source.

Combien de copies une duplication peut-elle créer ?

Jusqu’à 100, toutes ou aucune, dans la limite des vCPU et des démarrages de votre offre.

Dupliquer arrête-t-il la sandbox d’origine ?

Non. Une source active se met en pause quelques millisecondes et continue.

Une duplication est-elle facturée ?

Les démarrages sont gratuits. Chaque copie est facturée à la seconde selon son état, comme toute sandbox.

Quelle différence entre une duplication et un template ?

Une duplication copie une sandbox maintenant, avec mémoire et processus, sur son serveur. Un template garde les fichiers d’une sandbox pour de nouvelles sandboxes sur n’importe quel serveur, sans mémoire ni processus.

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