Español
Menú de la documentación

Documentación de Agent Sandboxes · Conceptos

Ciclo de vida de un sandbox: pausa, detención e inactividad

Actualizado · 9 min de lectura

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.

En resumen
  • 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) y delete_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 cuando wake_when_stopped está activado.
  • next_state y next_state_time de 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

  1. 0 minLa última actividad: está en ejecución.
  2. 5 minPAUSED: memoria y procesos conservados en su servidor, al 30 % del precio.
  3. 30 minSTOPPED: su disco conservado, sus procesos terminados, 0,03 US$ por GiB al mes.
  4. NuncaLo eliminas solo tú, o su temporizador de eliminación.
El reloj de inactividad vuelve a empezar con cada actividad: una llamada en el minuto 4 aplaza la pausa hasta el minuto 9.

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:

CampoPor defectoQué pasa
pause_after_idle_seconds300Un sandbox RUNNING pasa a PAUSED.
stop_after_idle_seconds1800Un sandbox RUNNING o PAUSED pasa a STOPPED.
delete_after_idle_seconds0, nuncaUn 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.

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}}}'

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.

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 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_message dice “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:

MotivoQué significa
REQUESTLo pidió una llamada.
IDLEUn temporizador, o su servidor con poca memoria o poco disco.
WAKELo reanudó una llamada, un inicio de sesión SSH o una petición a un puerto.
CRASHSu VM o su servidor falló, o no se inició. Solo ResumeSandbox lo vuelve a iniciar.
MAINTENANCELa máquina de su servidor se reinició: en pausa antes, sin facturar, y de nuevo en ejecución después.
UNPAIDNada 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 usoPausaDetenciónEliminaciónwake_when_stoppedkeep_awake
La sesión de un agente, como Claude Code en la nube300, el valor por defecto0, o 864000NoEn builds largos
Un sandbox por usuario de tu app de IADe 60 a 3001800, el valor por defecto604800Si tu app llama sin ResumeSandboxNo
Una previsualización que duerme12002592000NoNo
Un trabajo por lotes o una eval060600, o DeleteSandbox al finalNoEn 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 activa wake_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 ResumeSandbox para seguirlo.
  • Se pausó antes que su temporizador. A su servidor le faltó memoria: state_message lo 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.

Empezar la prueba gratis