Docs do Agent Sandboxes · Conceitos
Ciclo de vida do sandbox: pausa automática, parada automática e ociosidade
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.
- 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) edelete_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 quandowake_when_stoppedestá ativado. next_stateenext_state_timeem 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
- 0minA última atividade: ele roda.
- 5minPAUSED: memória e processos guardados no servidor, por 30% do preço.
- 30minSTOPPED: disco guardado, processos encerrados, US$ 0,03 por GiB ao mês.
- NuncaExcluído só por você, ou pelo timer de exclusão.
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:
| Campo | Padrão | O que acontece |
|---|---|---|
pause_after_idle_seconds | 300 | Um sandbox RUNNING vira PAUSED. |
stop_after_idle_seconds | 1.800 | Um sandbox RUNNING ou PAUSED vira STOPPED. |
delete_after_idle_seconds | 0, nunca | Um 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.
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}}}'
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.
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'
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_messagedele 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:
| Motivo | O que quer dizer |
|---|---|
REQUEST | Uma chamada pediu. |
IDLE | Um timer, ou o servidor com pouca memória ou pouco disco. |
WAKE | Uma chamada, um login SSH ou uma requisição a uma porta o retomou. |
CRASH | A VM ou o servidor falhou, ou ele não iniciou. Só ResumeSandbox o inicia de novo. |
MAINTENANCE | A máquina do servidor reiniciou: pausado antes, sem cobrança, e rodando de novo depois. |
UNPAID | Nada 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 uso | Pausa | Parada | Exclusão | wake_when_stopped | keep_awake |
|---|---|---|---|---|---|
| A sessão de um agente, como o Claude Code na nuvem | 300, o padrão | 0, ou 86400 | 0 | Não | Em builds longos |
| Um sandbox por usuário do seu app de IA | 60 a 300 | 1800, o padrão | 604800 | Se o seu app chama sem ResumeSandbox | Não |
| Um preview que dorme | 120 | 0 | 2592000 | Não | Não |
| Um job em lote ou um eval | 0 | 60 | 600, ou DeleteSandbox no fim | Não | No 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 ativewake_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
ResumeSandboxde novo para acompanhar. - Ele pausou antes do timer. O servidor ficou com pouca memória: o
state_messagediz 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.