Português
Menu da documentação

Docs do Agent Sandboxes · Conceitos

Ciclo de vida do sandbox: pausa automática, parada automática e ociosidade

Atualizado em · 8 min de leitura

Um sandbox que você deixa de lado pausa depois de 5 minutos e para depois de 30, e nunca é excluído a não ser que você peça. Três timers em um mesmo relógio de ociosidade decidem isso, e cada um pode ser alterado ou desativado. Esta página diz o que conta como atividade, o que cada timer faz e quais valores servem para um agente, para os usuários de um app, para um preview e para um job em lote.

Em resumo
  • Ocioso quer dizer sem chamada, stream, link, sessão SSH, requisição a uma porta, turno de agente ou comando keep_awake. Um processo em segundo plano sozinho não conta: ele pausa com o sandbox e continua de onde estava.
  • Três timers: pause_after_idle_seconds (300), stop_after_idle_seconds (1.800) e delete_after_idle_seconds (desativado). Cada um é desativado com 0.
  • Trabalho longo que ninguém chama, como um build ou uma suíte de testes, roda com keep_awake, para o sandbox não pausar no meio dele.
  • Um sandbox parado inicia de novo por ResumeSandbox, ou na próxima chamada quando wake_when_stopped está ativado.
  • next_state e next_state_time em um sandbox dizem o que o ciclo de vida faz a seguir, e quando.

O que conta como atividade

Um sandbox fica ocioso enquanto nada acontece nele. Cada um destes o mantém acordado e zera o relógio de ociosidade quando termina:

  • uma chamada da API de runtime (um comando, um arquivo, o desktop, um agente), ou um dos streams dela deixado aberto;
  • um link aberto: um terminal ou uma visão ao vivo do desktop em um navegador;
  • uma sessão SSH;
  • uma requisição a uma das portas dele;
  • um turno de agente ainda rodando;
  • um comando iniciado com keep_awake, até ele terminar.

O que não conta é um processo rodando sozinho em segundo plano: um servidor de desenvolvimento, um job iniciado com nohup, um watcher. Quando o sandbox pausa, esse processo para onde está e continua dali quando o sandbox acorda. Um servidor não precisa de mais nada: uma requisição à porta dele acorda o sandbox.

A linha do tempo padrão

  1. 0minA última atividade: ele roda.
  2. 5minPAUSED: memória e processos guardados no servidor, por 30% do preço.
  3. 30minSTOPPED: disco guardado, processos encerrados, US$ 0,03 por GiB ao mês.
  4. NuncaExcluído só por você, ou pelo timer de exclusão.
O relógio de ociosidade recomeça a cada atividade: uma chamada no minuto 4 adia a pausa para o minuto 9.

Os três timers

O lifecycle de um sandbox tem três timers, cada um em segundos no mesmo relógio de ociosidade, cada um desativado com 0:

CampoPadrãoO que acontece
pause_after_idle_seconds300Um sandbox RUNNING vira PAUSED.
stop_after_idle_seconds1.800Um sandbox RUNNING ou PAUSED vira STOPPED.
delete_after_idle_seconds0, nuncaUm sandbox em qualquer estado é excluído.

Quando o timer de parada vence antes ou junto com o de pausa, um sandbox RUNNING ocioso para sem pausar. Com os dois desativados, um sandbox roda até você pausá-lo, pará-lo ou excluí-lo.

Defina o ciclo de vida ao criar um sandbox, ou depois com UpdateSandbox. O ciclo de vida é um grupo de configurações: um grupo que você envia substitui o grupo inteiro do sandbox, e um timer que você deixa de fora volta ao padrão. Então envie todos os timers que pretende definir. Cada resposta traz as configurações em vigor com os padrões preenchidos, e o que você lê é o que você envia de volta.

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

Trabalho longo: keep_awake

Um build, uma suíte de testes ou um treinamento pode levar minutos sem nenhuma chamada ao sandbox, e o timer de pausa o pausaria no meio do trabalho. Inicie um comando assim com keep_awake: enquanto ele roda, o sandbox não pausa por ociosidade e conta como RUNNING. Dê também um timeout_seconds, para que um comando travado não mantenha o sandbox acordado para sempre.

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'

Não há limite para a vida de um sandbox: um que fica acordado roda, e é cobrado, até o comando terminar ou você pará-lo.

Acordar um sandbox parado: wake_when_stopped

Por padrão, um sandbox STOPPED só acorda por ResumeSandbox. Uma chamada de runtime a ele responde FAILED_PRECONDITION com Stopped, e uma requisição a uma das portas dele responde HTTP 503, “stopped: resume it”.

Com wake_when_stopped ativado, um sandbox parado acorda com uma chamada, um login SSH ou uma requisição a uma porta, como um pausado: cerca de 0,2 s enquanto o disco está no servidor, mais quando o disco volta do armazenamento de objetos, cerca de 10 s por GiB dos próprios dados. Serve para um projeto que acorda de vez em quando, como o endpoint de um webhook ou um sandbox que o seu app chama sem retomá-lo antes.

O custo é no orçamento, não em dinheiro: as vCPUs de um sandbox assim contam no seu plano também enquanto ele está parado, para que sempre haja espaço para ele acordar. Ativar isso em um sandbox parado é recusado quando o espaço de trabalho não tem mais vCPUs, e desativar as libera. Um sandbox parado por um CRASH nunca acorda assim.

Limpeza automática: delete_after_idle_seconds

Um sandbox parado custa só os bytes guardados, mas custa todo mês. Para sandboxes a que você não vai voltar, defina delete_after_idle_seconds: depois de ocioso por esse tempo, em qualquer estado, o sandbox é excluído, com memória e disco. Os volumes dele ficam. O registro fica 30 dias, e os eventos e as métricas, um dia. O seu programa também pode chamar DeleteSandbox quando terminar, que é o jeito mais seguro.

Quando um sandbox pausa ou para antes da hora

Um sandbox pode pausar ou parar antes do que os timers dizem, quando o servidor dele fica sem espaço:

  • Pouca memória: um sandbox RUNNING ocioso há 1 minuto ou mais é pausado antes. O state_message dele diz “paused early: its server's memory ran short”.
  • Pouco disco: o servidor para os sandboxes PAUSED ociosos há mais tempo, “stopped early: its server's disk ran short”, e enquanto isso uma pausa vira parada, “stopped instead of paused”.
  • Disco esgotado: o servidor para o sandbox RUNNING cujo disco mais cresceu, com o motivo CRASH, “its server ran out of disk space”. O disco dele é guardado.

Um sandbox que não está ocioso nunca é pausado antes da hora por falta de memória.

O que acontece a seguir: next_state e os motivos

GetSandbox responde com next_state e next_state_time: o que o ciclo de vida faz com o sandbox a seguir se nada acontecer antes, PAUSED, STOPPED ou DELETED, e quando. Eles ficam ausentes enquanto algo mantém o sandbox acordado e quando nenhum timer corre no estado dele.

Toda mudança de estado tem um state_reason, e os eventos do sandbox mostram os mesmos motivos:

MotivoO que quer dizer
REQUESTUma chamada pediu.
IDLEUm timer, ou o servidor com pouca memória ou pouco disco.
WAKEUma chamada, um login SSH ou uma requisição a uma porta o retomou.
CRASHA VM ou o servidor falhou, ou ele não iniciou. Só ResumeSandbox o inicia de novo.
MAINTENANCEA máquina do servidor reiniciou: pausado antes, sem cobrança, e rodando de novo depois.
UNPAIDNada paga pelo espaço de trabalho: cobrança.

Valores por caso de uso

São recomendações, feitas a partir das regras acima. Os timers estão em segundos, como a API os recebe.

Caso de usoPausaParadaExclusãowake_when_stoppedkeep_awake
A sessão de um agente, como o Claude Code na nuvem300, o padrão0, ou 864000NãoEm builds longos
Um sandbox por usuário do seu app de IA60 a 3001800, o padrão604800Se o seu app chama sem ResumeSandboxNão
Um preview que dorme12002592000NãoNão
Um job em lote ou um eval060600, ou DeleteSandbox no fimNãoNo comando do job

O sandbox de um agente guarda os processos quando nunca para, e um dia pausado custa 30% de um dia rodando. Um preview sem timer de parada acorda com uma visita em cerca de 0,2 s, com o servidor de desenvolvimento onde estava. A cobrança calcula quanto custa cada um.

Quando não funciona

  • Ele pausou durante um build longo. Nada o chamou, e um build é um processo em segundo plano. Rode o build com keep_awake.
  • Uma chamada responde FAILED_PRECONDITION com Stopped. O sandbox está STOPPED. Chame ResumeSandbox, ou ative wake_when_stopped.
  • Uma porta responde 503, “stopped: resume it”. O mesmo, visto de um navegador ou do curl.
  • Uma chamada responde UNAVAILABLE com Restoring. O disco está voltando do armazenamento de objetos, cerca de 10 s por GiB. Espere, ou chame ResumeSandbox de novo para acompanhar.
  • Ele pausou antes do timer. O servidor ficou com pouca memória: o state_message diz isso. Ele acorda como sempre na próxima chamada.

Perguntas

Um processo em segundo plano mantém um sandbox acordado?

Não. Só chamadas, streams e links abertos, sessões SSH, requisições a portas, turnos de agente rodando e comandos iniciados com keep_awake mantêm. Um processo em segundo plano pausa com o sandbox e continua quando ele acorda.

Como faço para um sandbox nunca parar?

Defina stop_after_idle_seconds como 0. Ele ainda pausa quando ocioso, o que guarda os processos, e acorda na próxima chamada.

Como mantenho um sandbox rodando o tempo todo?

Defina pause_after_idle_seconds e stop_after_idle_seconds como 0, e ele roda até você pausá-lo, pará-lo ou excluí-lo, pelo preço rodando.

Um sandbox parado acorda quando eu o chamo?

Só com wake_when_stopped ativado, e aí as vCPUs dele contam no seu plano enquanto ele está parado. Senão, ResumeSandbox o inicia.

Sandboxes ociosos são excluídos automaticamente?

Não por padrão. Defina delete_after_idle_seconds, ou chame DeleteSandbox quando terminar.

Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

Começar o teste grátis