Documentación de Agent Sandboxes · Conceptos
Ciclo de vida de un sandbox: pausa, detención e inactividad
Un sandbox que dejas tranquilo se pausa tras 5 minutos y se detiene tras 30, y nunca se elimina salvo que lo pidas. Lo deciden tres temporizadores sobre un mismo reloj de inactividad, y cada uno se puede cambiar o desactivar. Esta página dice qué cuenta como actividad, qué hace cada temporizador y qué valores convienen a un agente, a los usuarios de una app, a una previsualización y a un trabajo por lotes.
- Inactivo significa sin llamadas, streams, enlaces, sesiones SSH, peticiones a puertos, turnos de agente ni comandos
keep_awake. Un proceso en segundo plano no cuenta por sí solo: se pausa con el sandbox y sigue donde estaba. - Tres temporizadores:
pause_after_idle_seconds(300),stop_after_idle_seconds(1800) ydelete_after_idle_seconds(desactivado). Cada uno se desactiva con 0. - El trabajo largo al que nadie llama, como un build o una suite de tests, se ejecuta con
keep_awake, para que el sandbox no se pause a mitad. - Un sandbox detenido vuelve a iniciarse con
ResumeSandbox, o con la siguiente llamada cuandowake_when_stoppedestá activado. next_stateynext_state_timede un sandbox dicen qué hará después su ciclo de vida, y cuándo.
Qué cuenta como actividad
Un sandbox está inactivo mientras no pasa nada en él. Cada una de estas cosas lo mantiene despierto, y reinicia su reloj de inactividad cuando termina:
- una llamada a la API del runtime (un comando, un archivo, el escritorio, un agente), o uno de sus streams que sigue abierto;
- un enlace abierto: una terminal o una vista en tiempo real del escritorio en un navegador;
- una sesión SSH;
- una petición a uno de sus puertos;
- el turno de un agente que aún está en curso;
- un comando iniciado con
keep_awake, hasta que termina.
Lo que no cuenta es un proceso que se ejecuta en segundo plano por su cuenta: un servidor de desarrollo, un trabajo iniciado con nohup, un watcher. Cuando el sandbox se pausa, ese proceso se congela donde está, y sigue desde ahí cuando el sandbox despierta. Un servidor no necesita nada más: una petición a su puerto despierta el sandbox.
La línea de tiempo por defecto
- 0 minLa última actividad: está en ejecución.
- 5 minPAUSED: memoria y procesos conservados en su servidor, al 30 % del precio.
- 30 minSTOPPED: su disco conservado, sus procesos terminados, 0,03 US$ por GiB al mes.
- NuncaLo eliminas solo tú, o su temporizador de eliminación.
Los tres temporizadores
El lifecycle de un sandbox tiene tres temporizadores, cada uno un número de segundos sobre el mismo reloj de inactividad, cada uno desactivado con 0:
| Campo | Por defecto | Qué pasa |
|---|---|---|
pause_after_idle_seconds | 300 | Un sandbox RUNNING pasa a PAUSED. |
stop_after_idle_seconds | 1800 | Un sandbox RUNNING o PAUSED pasa a STOPPED. |
delete_after_idle_seconds | 0, nunca | Un sandbox en cualquier estado se elimina. |
Cuando el temporizador de detención no llega más tarde que el de pausa, un sandbox RUNNING inactivo se detiene sin pausarse. Con los dos desactivados, un sandbox se ejecuta hasta que lo pausas, lo detienes o lo eliminas.
Configura el ciclo de vida al crear un sandbox, o más tarde con UpdateSandbox. El ciclo de vida es un grupo de ajustes: un grupo que envías reemplaza el grupo entero del sandbox, y un temporizador que omites toma su valor por defecto. Así que envía cada temporizador que quieras fijar. Cada respuesta trae los ajustes vigentes con sus valores por defecto rellenados, así que lo que lees es lo que envías de vuelta.
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)
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);
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)
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);
pethost sandbox new --pause-after 5m --stop-after 24h
CreateSandbox {"settings": {"lifecycle": {"pause_after_idle_seconds": 300, "stop_after_idle_seconds": 86400}}}
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}}}'
Trabajo largo: keep_awake
Un build, una suite de tests o un entrenamiento pueden tardar minutos sin ninguna llamada al sandbox, y el temporizador de pausa lo pausaría a mitad del trabajo. Inicia ese comando con keep_awake: mientras se ejecuta, el sandbox no se pausa por inactividad, y cuenta como RUNNING. Dale también timeout_seconds, para que un comando que se cuelga no mantenga el sandbox despierto para siempre.
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)
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);
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
})
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?;
pethost sandbox run k7f3q2xy0a1b2c3d -d --keep-awake --timeout 30m -- 'npm ci && npm test'
La vida de un sandbox no tiene tope: uno que se mantiene despierto se ejecuta, y se factura, hasta que su comando termina o lo detienes.
Despertar un sandbox detenido: wake_when_stopped
Por defecto, un sandbox STOPPED solo despierta con ResumeSandbox. Una llamada al runtime responde FAILED_PRECONDITION con Stopped, y una petición a uno de sus puertos responde HTTP 503, “stopped: resume it”.
Con wake_when_stopped activado, un sandbox detenido despierta con una llamada, un inicio de sesión SSH o una petición a un puerto, como uno en pausa: unos 0,2 s mientras su disco está en su servidor, más cuando el disco vuelve desde almacenamiento de objetos, unos 10 s por GiB de sus propios datos. Conviene a un proyecto que despierta de vez en cuando, como el endpoint de un webhook o un sandbox al que tu app llama sin reanudarlo antes.
Lo paga el presupuesto, no el dinero: las vCPU de un sandbox así cuentan para tu plan también mientras está detenido, para que siempre tenga sitio para despertar. Activarlo en un sandbox detenido se rechaza cuando al espacio de trabajo no le quedan vCPU, y desactivarlo las libera. Un sandbox detenido por un CRASH nunca despierta así.
Limpiar solo: delete_after_idle_seconds
Un sandbox detenido solo cuesta sus bytes guardados, pero los cuesta cada mes. Para los sandboxes a los que no volverás, configura delete_after_idle_seconds: tras ese tiempo inactivo, en cualquier estado, el sandbox se elimina, con su memoria y su disco. Sus volúmenes se quedan. Su registro se conserva 30 días, y sus eventos y métricas un día. Tu programa también puede llamar a DeleteSandbox cuando termine, que es lo más seguro.
Cuando un sandbox se pausa o se detiene antes de tiempo
Un sandbox puede pausarse o detenerse antes de lo que dicen sus temporizadores, cuando a su servidor le falta espacio:
- Poca memoria: un sandbox RUNNING inactivo durante 1 minuto o más se pausa antes de tiempo. Su
state_messagedice “paused early: its server's memory ran short”. - Poco disco: el servidor detiene los sandboxes PAUSED que llevan más tiempo inactivos, “stopped early: its server's disk ran short”, y mientras tanto una pausa se convierte en una detención, “stopped instead of paused”.
- Sin disco: el servidor detiene el sandbox RUNNING cuyo disco más creció, con el motivo CRASH, “its server ran out of disk space”. Su disco se conserva.
Un sandbox que no está inactivo nunca se pausa antes de tiempo por memoria.
Qué pasa después: next_state y los motivos
GetSandbox responde con next_state y next_state_time: lo que el ciclo de vida hará después con el sandbox si antes no pasa nada, PAUSED, STOPPED o DELETED, y cuándo. No aparecen mientras algo mantiene el sandbox despierto, ni cuando ningún temporizador está activo en su estado.
Cada cambio de estado tiene un state_reason, y los eventos del sandbox muestran los mismos motivos:
| Motivo | Qué significa |
|---|---|
REQUEST | Lo pidió una llamada. |
IDLE | Un temporizador, o su servidor con poca memoria o poco disco. |
WAKE | Lo reanudó una llamada, un inicio de sesión SSH o una petición a un puerto. |
CRASH | Su VM o su servidor falló, o no se inició. Solo ResumeSandbox lo vuelve a iniciar. |
MAINTENANCE | La máquina de su servidor se reinició: en pausa antes, sin facturar, y de nuevo en ejecución después. |
UNPAID | Nada paga el espacio de trabajo: facturación. |
Valores por caso de uso
Son recomendaciones, hechas a partir de las reglas de arriba. Los temporizadores van en segundos, como los toma la API.
| Caso de uso | Pausa | Detención | Eliminación | wake_when_stopped | keep_awake |
|---|---|---|---|---|---|
| La sesión de un agente, como Claude Code en la nube | 300, el valor por defecto | 0, o 86400 | 0 | No | En builds largos |
| Un sandbox por usuario de tu app de IA | De 60 a 300 | 1800, el valor por defecto | 604800 | Si tu app llama sin ResumeSandbox | No |
| Una previsualización que duerme | 120 | 0 | 2592000 | No | No |
| Un trabajo por lotes o una eval | 0 | 60 | 600, o DeleteSandbox al final | No | En el comando del trabajo |
El sandbox de un agente conserva sus procesos cuando nunca se detiene, y un día en pausa cuesta el 30 % de uno en ejecución. Una previsualización sin temporizador de detención despierta con una visita en unos 0,2 s con su servidor de desarrollo donde estaba. Facturación calcula cuánto cuesta cada uno.
Cuando no funciona
- Se pausó durante un build largo. Nada lo llamó, y un build es un proceso en segundo plano. Ejecuta el build con
keep_awake. - Una llamada responde FAILED_PRECONDITION con Stopped. El sandbox está STOPPED. Llama a
ResumeSandbox, o activawake_when_stopped. - Un puerto responde 503, “stopped: resume it”. Lo mismo, visto desde un navegador o curl.
- Una llamada responde UNAVAILABLE con Restoring. Su disco está volviendo desde almacenamiento de objetos, a unos 10 s por GiB. Espera, o vuelve a llamar a
ResumeSandboxpara seguirlo. - Se pausó antes que su temporizador. A su servidor le faltó memoria:
state_messagelo dice. Despierta como siempre con la siguiente llamada.
Preguntas
¿Un proceso en segundo plano mantiene despierto un sandbox?
No. Solo lo hacen las llamadas, los streams y enlaces abiertos, las sesiones SSH, las peticiones a puertos, los turnos de agente en curso y los comandos iniciados con keep_awake. Un proceso en segundo plano se pausa con el sandbox y sigue cuando despierta.
¿Cómo evito que un sandbox se detenga nunca?
Pon stop_after_idle_seconds a 0. Seguirá pausándose cuando esté inactivo, lo que conserva sus procesos, y despertará con la siguiente llamada.
¿Cómo mantengo un sandbox en ejecución todo el tiempo?
Pon pause_after_idle_seconds y stop_after_idle_seconds a 0, y se ejecutará hasta que lo pauses, lo detengas o lo elimines, a su precio en ejecución.
¿Un sandbox detenido despierta cuando lo llamo?
Solo con wake_when_stopped activado, y entonces sus vCPU cuentan para tu plan mientras está detenido. Si no, lo inicia ResumeSandbox.
¿Los sandboxes inactivos se eliminan solos?
No por defecto. Configura delete_after_idle_seconds, o llama a DeleteSandbox cuando termines.
Prueba Pethost Agent Sandboxes
Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.