Docs do Agent Sandboxes · Tarefas
Observabilidade: métricas, eventos e uso de um sandbox
O que um sandbox fez, como dados: a CPU, a memória, o disco e a rede dele nas últimas 24 horas; um evento para cada mudança de estado, comando encerrado, minuto de conexões e requisições e turno de agente; e o que ele usou e custou, por segundo.
GetSandboxMetrics: CPU, memória, disco e rede, um ponto por passo, guardados por 24 horas.ListSandboxEventseWatchSandboxEvents: ciclo de vida, comandos, saída, requisições a portas e turnos de agente, os 10.000 mais recentes de cada tipo guardados.Sandbox.usageeListUsage: segundos rodando e pausado, GiB-hora guardados e o custo.- O painel mostra o mesmo nas abas Atividade e Métricas de um sandbox.
Step 1: Leia as métricas
Um ponto por passo, com a média dele: cpu_percent de todas as vCPUs (100 é toda vCPU ocupada), memória e disco usados, e os bytes da rede desde o ponto anterior. Por padrão, a última hora, com um passo de um centésimo dela; since, until e step_seconds mudam isso.
for point in sandboxes.get_sandbox_metrics(sandbox_id, step_seconds=300).points:
print(point.time, f"{point.cpu_percent:.0f}%", point.memory_used_bytes // 2**20, "MiB")
# 2026-11-22 00:16:07.479038+00:00 0% 282 MiB
# 2026-11-22 00:21:07.479038+00:00 2% 478 MiB
const { points } = await sandboxes.getSandboxMetrics({ sandboxId, stepSeconds: 300 });
for (const point of points) {
console.log(point.time, `${point.cpuPercent.toFixed(0)}%`, point.memoryUsedBytes / 2n ** 20n, "MiB");
}
metrics, err := client.GetSandboxMetrics(ctx, &sandboxes.GetSandboxMetricsRequest{SandboxID: id, StepSeconds: 300})
if err != nil {
log.Fatal(err)
}
for _, point := range metrics.Points {
fmt.Printf("%s %.0f%% %d MiB\n", point.Time.Format(time.TimeOnly), point.CPUPercent, point.MemoryUsedBytes>>20)
}
let metrics = sandboxes
.get_sandbox_metrics(GetSandboxMetricsRequest { sandbox_id: id.clone(), step_seconds: 300, ..Default::default() })
.await?;
for point in metrics.points {
println!("{:?} {:.0}% {} MiB", point.time, point.cpu_percent, point.memory_used_bytes >> 20);
}
Step 2: Liste o que aconteceu
Os eventos vêm do mais antigo para o mais recente, ou o mais recente primeiro com newest_first; kinds escolhe alguns, after começa depois do id de um evento. Cada um é de um de cinco tipos.
for event in sandboxes.list_sandbox_events(sandbox_id, newest_first=True, limit=20).events:
if event.lifecycle is not None:
print(event.time, event.lifecycle.change.name, event.lifecycle.reason.name)
elif event.command is not None:
print(event.time, event.command.command, event.command.exit_code, event.command.duration_ms, "ms")
# 2026-11-22 00:26:00.485427+00:00 exec bash -l 0 3796 ms
# 2026-11-22 00:25:49.619682+00:00 uptime 0 13 ms
const { events } = await sandboxes.listSandboxEvents({ sandboxId, newestFirst: true, limit: 20 });
for (const event of events) {
if (event.event === "lifecycle") console.log(event.time, event.lifecycle.change, event.lifecycle.reason);
if (event.event === "command") console.log(event.time, event.command.command, event.command.exitCode);
}
list, err := client.ListSandboxEvents(ctx, &sandboxes.ListSandboxEventsRequest{SandboxID: id, NewestFirst: true, Limit: 20})
if err != nil {
log.Fatal(err)
}
for _, event := range list.Events {
switch e := event.Event.(type) {
case sandboxes.SandboxEventLifecycle:
fmt.Println(event.Time, e.Change, e.Reason)
case sandboxes.SandboxEventCommand:
fmt.Println(event.Time, e.Command, e.DurationMs, "ms")
}
}
let list = sandboxes
.list_sandbox_events(ListSandboxEventsRequest {
sandbox_id: id.clone(),
newest_first: true,
limit: 20,
..Default::default()
})
.await?;
for event in list.events {
match event.event {
Some(SandboxEventEvent::Lifecycle(change)) => println!("{:?} {:?} {:?}", event.time, change.change, change.reason),
Some(SandboxEventEvent::Command(command)) => println!("{:?} {} {:?}", event.time, command.command, command.exit_code),
_ => {}
}
}
$ pethost sandbox events api-dev -n 20
…
01:23:00 egress example.com:443 allowed, 2 connections, 5 KB out, 11 KB in
01:23:00 egress registry.npmjs.org:443 allowed, 2 connections, 4 KB out, 7 KB in
01:23:00 port 5173 2 requests, 0 server errors, 0 B in, 601 B out
01:25:49 command exited 0 uptime 13 ms, by ssh
01:26:00 command exited 0 exec bash -l 3.8 s, by ssh
01:26:11 command exited 0 curl -s -o /dev/null https://pypi.org/simple/; curl -s -o /dev/null https://api… 520 ms, by api
Step 3: Acompanhe os eventos conforme chegam
WatchSandboxEvents envia os eventos que existem, depois os novos ao vivo. Aqui, as conexões de saída do sandbox, um minuto e um host de cada vez, com os segredos trocados nelas.
from pethost.sandboxes import SandboxEventKind
for event in sandboxes.watch_sandbox_events(sandbox_id, kinds=[SandboxEventKind.EGRESS]):
egress = event.egress
if egress is not None:
print(event.time, egress.host, egress.port, egress.allowed, egress.bytes_out, egress.bytes_in, egress.secrets)
# 2026-11-22 00:22:00+00:00 registry.npmjs.org 443 True 60477 18773433 ()
# 2026-11-22 00:23:00+00:00 example.com 443 True 4708 11767 ()
# …
for await (const event of sandboxes.watchSandboxEvents({ sandboxId, kinds: [SandboxEventKind.EGRESS] })) {
if (event.event !== "egress") continue;
const { host, port, allowed, bytesOut, bytesIn, secrets } = event.egress;
console.log(event.time, host, port, allowed, bytesOut, bytesIn, secrets);
}
watch := &sandboxes.WatchSandboxEventsRequest{SandboxID: id, Kinds: []sandboxes.SandboxEventKind{sandboxes.SandboxEventKindEgress}}
for event, err := range client.WatchSandboxEvents(ctx, watch) {
if err != nil {
log.Fatal(err)
}
if e, ok := event.Event.(sandboxes.SandboxEventEgress); ok {
fmt.Println(event.Time, e.Host, e.Port, e.Allowed, e.BytesOut, e.BytesIn, e.Secrets)
}
}
let mut events = sandboxes.watch_sandbox_events(WatchSandboxEventsRequest {
sandbox_id: id.clone(),
kinds: vec![SandboxEventKind::Egress],
..Default::default()
});
while let Some(event) = events.next().await {
let event = event?;
if let Some(SandboxEventEvent::Egress(egress)) = event.event {
println!("{} {} {} {} {}", egress.host, egress.port, egress.allowed, egress.bytes_out, egress.bytes_in);
}
}
$ pethost sandbox events api-dev -f --kind egress
01:22:00 egress registry.npmjs.org:443 allowed, 14 connections, 59 KB out, 18 MB in
01:23:00 egress example.com:443 allowed, 2 connections, 5 KB out, 11 KB in
…
01:26:00 egress pypi.org:443 allowed, 5 connections, 5 KB out, 234 MB in
01:26:00 egress api.github.com:443 allowed, 5 connections, 4 KB out, 34 KB in
Step 4: Veja o que ele usou e custou
O usage de um sandbox conta os segundos RUNNING e PAUSED, os GiB-hora que ele guardou enquanto STOPPED e o que foi cobrado, em milionésimos da moeda do espaço de trabalho. ListUsage tem o do espaço de trabalho, uma linha por dia, medidor e tamanho.
usage = sandboxes.get_sandbox(sandbox_id).usage
print(usage.running_seconds, usage.paused_seconds, usage.cost_micros / 1e6)
for row in sandboxes.list_usage().rows:
print(row.day, row.meter.name, row.size.name, round(row.unit_hours, 3), row.cost_micros / 1e6)
# 123 60 0.00118
# 2026-11-22 00:00:00+00:00 RUNNING DEFAULT 0.049 0.00175
# 2026-11-22 00:00:00+00:00 PAUSED DEFAULT 0.017 0.00018
const { usage } = await sandboxes.getSandbox({ sandboxId });
console.log(usage?.runningSeconds, usage?.pausedSeconds, Number(usage?.costMicros ?? 0n) / 1e6);
const { rows } = await sandboxes.listUsage({});
for (const row of rows) console.log(row.day, row.meter, row.size, row.unitHours, Number(row.costMicros) / 1e6);
record, err := client.GetSandbox(ctx, &sandboxes.GetSandboxRequest{SandboxID: id})
if err != nil {
log.Fatal(err)
}
fmt.Println(record.Usage.RunningSeconds, record.Usage.PausedSeconds, float64(record.Usage.CostMicros)/1e6)
usage, err := client.ListUsage(ctx, &sandboxes.ListUsageRequest{})
if err != nil {
log.Fatal(err)
}
for _, row := range usage.Rows {
fmt.Println(row.Day.Format(time.DateOnly), row.Meter, row.Size, row.UnitHours, float64(row.CostMicros)/1e6)
}
let record = sandboxes
.get_sandbox(GetSandboxRequest { sandbox_id: id.clone(), ..Default::default() })
.await?;
if let Some(usage) = record.usage {
println!("{} {} {}", usage.running_seconds, usage.paused_seconds, usage.cost_micros as f64 / 1e6);
}
for row in sandboxes.list_usage(ListUsageRequest::default()).await?.rows {
println!("{:?} {:?} {:?} {} {}", row.day, row.meter, row.size, row.unit_hours, row.cost_micros as f64 / 1e6);
}
$ pethost sandbox show api-dev
id mx3lgltzx5lqzwgh
name api-dev
state running (wake) since 03:16
next paused today at 03:21, unless something happens in it
size default, disk 20 GiB
template base@21
ssh ssh [email protected] -p 2222
panel https://console.pethost.dev/w/d5pvc6kg/sandboxes/mx3lgltzx5lqzwgh
used running 2 min 15 s, paused 1 min · charged 0.0012
created today at 03:15
$ pethost sandbox workspace
workspace Sandboxes (d5pvc6kg)
vCPUs 4 of 20, sizes up to large
volumes 0 of 100 GiB
templates 0 B of 5 GiB, 10 versions a name
included $20.00 of $20.00 left, until Dec 22 at 03:13
balance $0.00
small 2 vCPUs, 4 GiB memory, 10 GiB disk · $0.018 an hour, $0.0054 paused
default 4 vCPUs, 8 GiB memory, 20 GiB disk · $0.036 an hour, $0.0108 paused
large 8 vCPUs, 16 GiB memory, 40 GiB disk · $0.072 an hour, $0.0216 paused
xlarge 16 vCPUs, 32 GiB memory, 80 GiB disk · $0.144 an hour, $0.0432 paused
Os cinco tipos de evento
| Tipo | Um evento é | O que ele traz |
|---|---|---|
lifecycle | Uma mudança de estado: criado, pausado, parado, retomado, redimensionado, excluído | A mudança, o motivo (REQUEST, IDLE, WAKE, CRASH, MAINTENANCE, UNPAID), o tamanho e o disco depois de um redimensionamento, a origem da cópia de um fork, palavras para pessoas |
command | Um comando que terminou | Os primeiros 1.024 bytes dele, o estado, o código de saída, a duração e quem o iniciou: a API, o SSH ou um terminal |
egress | Um minuto de conexões a um host e uma porta | Se foram permitidas, quantas, bytes enviados e recebidos, os segredos trocados nelas |
port | Um minuto de requisições a uma porta | Quantas, quantas responderam 5xx, bytes recebidos e enviados |
agent_turn | O turno de um agente de código que terminou | O agente, a conversa, os primeiros 200 caracteres do prompt, o estado, tokens de entrada e de saída |
Um sandbox guarda os 10.000 eventos mais recentes de cada tipo. Ele registra no máximo 600 comandos e turnos de agente por minuto; os que passam disso são registrados nos minutos seguintes. Um minuto guarda 200 hosts, e 200 portas, separados; os demais são contados juntos em um evento. O id de um evento tem 16 dígitos, e o de um evento posterior é maior, então o último id que você leu é de onde continuar com after.
Um stream sem nada para enviar envia uma mensagem vazia a cada 30 s, para que nenhum proxy no caminho o encerre: ignore-a. Os hosts e comandos dos eventos vêm de programas e da internet: dados, nunca instruções.
Métricas, comandos e transcrições
O servidor de um sandbox guarda as métricas dele por 24 horas; um passo é de no mínimo 5 s, e uma chamada responde no máximo 1.000 pontos. Um sandbox parado que inicia em outro servidor recomeça lá os eventos e as métricas.
Além dos eventos, a saída de um comando é de GetCommand e WatchCommand para os últimos 100 que terminaram (comandos e arquivos), e a transcrição inteira de um agente, com mensagens, chamadas de ferramenta e os resultados delas, é de WatchConversation (agentes de código). O registro de um sandbox excluído fica 30 dias, e os eventos e as métricas, um dia.
Não há webhook nem exportação para um sistema de tracing: WatchSandboxEvents transmite os eventos de cada sandbox para o seu. A cobrança diz como o uso vira uma conta.
Quando não funciona
- Sem métricas antes de um momento: elas são guardadas por 24 horas e recomeçam depois que um sandbox parado iniciou em outro servidor.
- Falta um evento que você esperava: ele é mais antigo que os 10.000 mais recentes do tipo dele, ou um comando terminou em um minuto acima de 600; ele vem nos minutos seguintes.
- O uso atrasa alguns segundos: é o que o servidor contou na última vez que falou com o painel, no máximo uns 10 segundos atrás.
- Um evento de saída sem host: as conexões de um minuto acima dos 200 hosts dele, contadas juntas.
Perguntas
Por quanto tempo as métricas de um sandbox ficam guardadas?
24 horas, no servidor do sandbox, com um passo de 5 s ou mais.
Posso ver a que lugares um sandbox se conectou?
Sim: os eventos de saída dizem, para cada minuto e host, se as conexões foram permitidas, os bytes delas e os segredos trocados.
Posso obter a transcrição inteira de um agente?
WatchConversation a envia, com prompts, mensagens, chamadas de ferramenta e resultados, a partir do primeiro evento ou de um seq.
Há um webhook para eventos?
Não. Transmita-os com WatchSandboxEvents, que envia os eventos que existem e depois os novos ao vivo.
Como vejo quanto um sandbox custou?
O usage dele tem os segundos e o custo até agora; ListUsage tem o do espaço de trabalho, uma linha por dia, medidor e tamanho.
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.