Français
Menu de la documentation

Documentation Agent Sandboxes · Notions

Cycle de vie d’une sandbox : pause, arrêt et inactivité

Mis à jour le · 9 min de lecture

Une sandbox que vous laissez tranquille se met en pause au bout de 5 minutes et s’arrête au bout de 30, et elle n’est jamais supprimée sans que vous le demandiez. Trois délais sur une même horloge d’inactivité en décident, et chacun se modifie ou se désactive. Cette page dit ce qui compte comme activité, ce que fait chaque délai, et quelles valeurs conviennent à un agent, aux utilisateurs d’une application, à une prévisualisation et à un traitement par lots.

En bref
  • Inactive veut dire sans appel, flux, lien, session SSH, requête vers un port, tour d’agent ni commande keep_awake. Un processus en arrière-plan ne compte pas à lui seul : il se met en pause avec la sandbox et reprend là où il en était.
  • Trois délais : pause_after_idle_seconds (300), stop_after_idle_seconds (1 800) et delete_after_idle_seconds (désactivé). Chacun se désactive avec 0.
  • Un long travail vers lequel personne n’appelle, comme un build ou une suite de tests, tourne avec keep_awake, pour que la sandbox ne se mette pas en pause en plein travail.
  • Une sandbox arrêtée redémarre par ResumeSandbox, ou au prochain appel quand wake_when_stopped est activé.
  • next_state et next_state_time d’une sandbox disent ce que son cycle de vie fera ensuite, et quand.

Ce qui compte comme activité

Une sandbox est inactive tant qu’il ne s’y passe rien. Chacun de ces éléments la garde éveillée, et remet son horloge d’inactivité à zéro quand il prend fin :

  • un appel à l’API du runtime (une commande, un fichier, le bureau, un agent), ou l’un de ses flux resté ouvert ;
  • un lien ouvert : un terminal ou une vue en direct du bureau dans un navigateur ;
  • une session SSH ;
  • une requête vers l’un de ses ports ;
  • un tour d’agent encore en cours ;
  • une commande lancée avec keep_awake, jusqu’à ce qu’elle se termine.

Ce qui ne compte pas, c’est un processus qui tourne seul en arrière-plan : un serveur de développement, une tâche lancée avec nohup, un watcher. Quand la sandbox se met en pause, un tel processus s’arrête là où il en est, et repart de là quand la sandbox se réveille. Un serveur n’a besoin de rien de plus : une requête vers son port réveille la sandbox.

La chronologie par défaut

  1. 0 minLa dernière activité : elle tourne.
  2. 5 minPAUSED : mémoire et processus gardés sur son serveur, à 30 % du prix.
  3. 30 minSTOPPED : son disque gardé, ses processus terminés, 0,03 $ par GiB et par mois.
  4. JamaisSupprimée seulement par vous, ou par son délai de suppression.
L’horloge d’inactivité repart de zéro à chaque activité : un appel à la 4e minute repousse la pause à la 9e.

Les trois délais

Le lifecycle d’une sandbox a trois délais, chacun un nombre de secondes sur la même horloge d’inactivité, chacun désactivé avec 0 :

ChampPar défautCe qui se passe
pause_after_idle_seconds300Une sandbox RUNNING passe PAUSED.
stop_after_idle_seconds1 800Une sandbox RUNNING ou PAUSED passe STOPPED.
delete_after_idle_seconds0, jamaisUne sandbox est supprimée, quel que soit son état.

Quand le délai d’arrêt n’arrive pas après le délai de pause, une sandbox RUNNING inactive s’arrête sans passer par la pause. Avec les deux désactivés, une sandbox tourne jusqu’à ce que vous la mettiez en pause, l’arrêtiez ou la supprimiez.

Réglez le cycle de vie à la création d’une sandbox, ou plus tard avec UpdateSandbox. Le cycle de vie est un groupe de paramètres : un groupe que vous envoyez remplace tout le groupe de la sandbox, et un délai que vous omettez prend sa valeur par défaut. Envoyez donc chaque délai que vous voulez fixer. Chaque réponse porte les paramètres en vigueur, valeurs par défaut comprises : ce que vous lisez est ce que vous renvoyez.

Python
from pethost.sandboxes import Lifecycle, SandboxSettings, Sandboxes

sandboxes = Sandboxes()  # The token: PETHOST_TOKEN.

sandbox = sandboxes.create_sandbox(
    settings=SandboxSettings(
        lifecycle=Lifecycle(
            pause_after_idle_seconds=300,  # pause after 5 idle minutes
            stop_after_idle_seconds=86400,  # stop after an idle day
        ),
    ),
)
print(sandbox.sandbox_id)
TypeScript
import { Sandboxes } from "pethost/sandboxes";

const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });

const sandbox = await sandboxes.createSandbox({
  settings: {
    lifecycle: { pauseAfterIdleSeconds: 300, stopAfterIdleSeconds: 86400 },
  },
});
console.log(sandbox.sandboxId);
Go
client := sandboxes.NewClient(sandboxes.Config{Token: os.Getenv("PETHOST_TOKEN")})

sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Settings: &sandboxes.SandboxSettings{
		Lifecycle: &sandboxes.Lifecycle{
			PauseAfterIdleSeconds: new(uint32(300)),
			StopAfterIdleSeconds:  new(uint32(86400)),
		},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(sandbox.SandboxID)
Rust
use pethost::sandboxes::{types::*, Client};

let sandboxes = Client::new(&std::env::var("PETHOST_TOKEN")?);
let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        settings: Some(SandboxSettings {
            lifecycle: Some(Lifecycle {
                pause_after_idle_seconds: Some(300),
                stop_after_idle_seconds: Some(86400),
                ..Default::default()
            }),
            ..Default::default()
        }),
        ..Default::default()
    })
    .await?;
println!("{}", sandbox.sandbox_id);
CLI
pethost sandbox new --pause-after 5m --stop-after 24h
MCP
CreateSandbox {"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}
HTTP
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}'

Un long travail : keep_awake

Un build, une suite de tests ou un entraînement peut durer des minutes sans aucun appel vers la sandbox, et le délai de pause la mettrait en pause en plein travail. Lancez une telle commande avec keep_awake : tant qu’elle tourne, la sandbox ne se met pas en pause pour inactivité, et elle compte comme RUNNING. Donnez-lui aussi timeout_seconds, pour qu’une commande bloquée ne garde pas la sandbox éveillée pour toujours.

Python
command = sandboxes.run_command(
    sandbox.sandbox_id,
    command="npm ci && npm test",
    keep_awake=True,
    timeout_seconds=1800,
    wait_seconds=0,  # answer once it has started
)
print(command.command_id, command.state.name)
TypeScript
const command = await sandboxes.runCommand({
  sandboxId: sandbox.sandboxId,
  command: "npm ci && npm test",
  keepAwake: true,
  timeoutSeconds: 1800,
  waitSeconds: 0, // answer once it has started
});
console.log(command.commandId, command.state);
Go
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
	SandboxID:      sandbox.SandboxID,
	Command:        "npm ci && npm test",
	KeepAwake:      true,
	TimeoutSeconds: 1800,
	WaitSeconds:    new(uint32(0)), // answer once it has started
})
Rust
let command = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: sandbox.sandbox_id.clone(),
        command: "npm ci && npm test".into(),
        keep_awake: true,
        timeout_seconds: 1800,
        wait_seconds: Some(0), // answer once it has started
        ..Default::default()
    })
    .await?;
CLI
pethost sandbox run k7f3q2xy0a1b2c3d -d --keep-awake --timeout 30m -- 'npm ci && npm test'

La vie d’une sandbox n’a pas de plafond : une sandbox gardée éveillée tourne, et est facturée, jusqu’à ce que sa commande se termine ou que vous l’arrêtiez.

Réveiller une sandbox arrêtée : wake_when_stopped

Par défaut, une sandbox STOPPED ne se réveille que par ResumeSandbox. Un appel au runtime vers elle répond FAILED_PRECONDITION avec Stopped, et une requête vers l’un de ses ports répond HTTP 503, « stopped: resume it ».

Avec wake_when_stopped activé, une sandbox arrêtée se réveille à un appel, une connexion SSH ou une requête vers un port, comme une sandbox en pause : 0,2 s environ tant que son disque est sur son serveur, plus longtemps quand le disque revient du stockage objet, 10 s environ par GiB de ses propres données. Cela convient à un projet qui se réveille de temps en temps, comme le point d’entrée d’un webhook ou une sandbox que votre application appelle sans la reprendre d’abord.

Cela coûte du budget, pas de l’argent : les vCPU d’une telle sandbox comptent dans votre offre même quand elle est arrêtée, pour qu’elle ait toujours la place de se réveiller. L’activer pour une sandbox arrêtée est refusé quand l’espace de travail n’a plus de vCPU, et le désactiver les libère. Une sandbox arrêtée par un CRASH ne se réveille jamais ainsi.

Faire le ménage tout seul : delete_after_idle_seconds

Une sandbox arrêtée ne coûte que ses octets stockés, mais elle les coûte chaque mois. Pour les sandboxes auxquelles vous ne reviendrez pas, fixez delete_after_idle_seconds : une fois inactive aussi longtemps, dans n’importe quel état, la sandbox est supprimée, avec sa mémoire et son disque. Ses volumes restent. Son registre reste 30 jours, et ses événements et métriques un jour. Votre programme peut aussi appeler DeleteSandbox quand il a fini, ce qui est le plus sûr.

Quand une sandbox se met en pause ou s’arrête plus tôt

Une sandbox peut se mettre en pause ou s’arrêter avant ce que disent ses délais, quand son serveur manque de place :

  • Mémoire insuffisante : une sandbox RUNNING inactive depuis 1 minute ou plus est mise en pause plus tôt. Son state_message dit « paused early: its server's memory ran short ».
  • Disque insuffisant : le serveur arrête les sandboxes PAUSED inactives depuis le plus longtemps, « stopped early: its server's disk ran short », et entre-temps une pause devient un arrêt, « stopped instead of paused ».
  • Disque plein : le serveur arrête la sandbox RUNNING dont le disque a le plus grandi, avec la raison CRASH, « its server ran out of disk space ». Son disque est gardé.

Une sandbox qui n’est pas inactive n’est jamais mise en pause plus tôt pour la mémoire.

Ce qui va se passer : next_state et les raisons

GetSandbox répond avec next_state et next_state_time : ce que le cycle de vie fera ensuite à la sandbox si rien ne se passe d’ici là, PAUSED, STOPPED ou DELETED, et quand. Ils sont absents tant que quelque chose garde la sandbox éveillée, et quand aucun délai ne court dans son état.

Chaque changement d’état a une state_reason, et les événements de la sandbox montrent les mêmes raisons :

RaisonCe qu’elle veut dire
REQUESTUn appel l’a demandé.
IDLEUn délai, ou son serveur à court de mémoire ou de disque.
WAKEUn appel, une connexion SSH ou une requête vers un port l’a reprise.
CRASHSa VM ou son serveur a planté, ou elle n’a pas démarré. Seul ResumeSandbox la redémarre.
MAINTENANCELa machine de son serveur a redémarré : mise en pause avant, non facturée, et de nouveau active après.
UNPAIDRien ne paie pour l’espace de travail : facturation.

Valeurs par usage

Ce sont des recommandations, tirées des règles ci-dessus. Les délais sont en secondes, comme l’API les prend.

UsagePauseArrêtSuppressionwake_when_stoppedkeep_awake
La session d’un agent, comme Claude Code dans le cloud300, la valeur par défaut0, ou 864000NonPour les longs builds
Une sandbox par utilisateur de votre application d’IA60 à 3001800, la valeur par défaut604800Si votre application appelle sans ResumeSandboxNon
Une prévisualisation qui dort12002592000NonNon
Un traitement par lots ou une évaluation060600, ou DeleteSandbox à la finNonSur la commande du traitement

La sandbox d’un agent garde ses processus quand elle ne s’arrête jamais, et une journée en pause coûte 30 % d’une journée active. Une prévisualisation sans délai d’arrêt se réveille à une visite en 0,2 s environ, avec son serveur de développement là où il en était. La facturation calcule ce que coûte chacune.

Quand ça ne marche pas

  • Elle s’est mise en pause pendant un long build. Rien n’appelait vers elle, et un build est un processus en arrière-plan. Lancez le build avec keep_awake.
  • Un appel répond FAILED_PRECONDITION avec Stopped. La sandbox est STOPPED. Appelez ResumeSandbox, ou activez wake_when_stopped.
  • Un port répond 503, « stopped: resume it ». La même chose, vue depuis un navigateur ou curl.
  • Un appel répond UNAVAILABLE avec Restoring. Son disque revient du stockage objet, 10 s environ par GiB. Attendez, ou rappelez ResumeSandbox pour suivre l’avancement.
  • Elle s’est mise en pause avant son délai. Son serveur a manqué de mémoire : state_message le dit. Elle se réveille comme d’habitude au prochain appel.

Questions

Un processus en arrière-plan garde-t-il une sandbox éveillée ?

Non. Seuls les appels, les flux et liens ouverts, les sessions SSH, les requêtes vers les ports, les tours d’agents en cours et les commandes lancées avec keep_awake le font. Un processus en arrière-plan se met en pause avec la sandbox et continue quand elle se réveille.

Comment empêcher une sandbox de jamais s’arrêter ?

Mettez stop_after_idle_seconds à 0. Elle se met toujours en pause quand elle est inactive, ce qui garde ses processus, et se réveille au prochain appel.

Comment garder une sandbox active tout le temps ?

Mettez pause_after_idle_seconds et stop_after_idle_seconds à 0 : elle tourne jusqu’à ce que vous la mettiez en pause, l’arrêtiez ou la supprimiez, à son prix d’exécution.

Une sandbox arrêtée se réveille-t-elle quand je l’appelle ?

Seulement avec wake_when_stopped activé, et ses vCPU comptent alors dans votre offre même quand elle est arrêtée. Sinon, ResumeSandbox la démarre.

Les sandboxes inactives sont-elles supprimées automatiquement ?

Pas par défaut. Fixez delete_after_idle_seconds, ou appelez DeleteSandbox quand vous avez fini.

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