Español
Menú de la documentación

Documentación de Agent Sandboxes · Tareas

Observabilidad: métricas, eventos y uso de un sandbox

Actualizado · 8 min de lectura

Lo que hizo un sandbox, como datos: su CPU, su memoria, su disco y su red en las últimas 24 horas; un evento por cada cambio de estado, comando terminado, minuto de conexiones y peticiones, y turno de agente; y lo que usó y costó, por segundo.

En resumen
  • GetSandboxMetrics: CPU, memoria, disco y red, un punto por intervalo, conservados 24 horas.
  • ListSandboxEvents y WatchSandboxEvents: ciclo de vida, comandos, salida, peticiones a puertos y turnos de agente; se conservan los 10.000 más recientes de cada tipo.
  • Sandbox.usage y ListUsage: segundos en ejecución y en pausa, GiB-hora guardados, y lo que costó.
  • El panel muestra lo mismo en las pestañas Actividad y Métricas de un sandbox.

Step 1: Lee sus métricas

Un punto por intervalo, promediado en él: cpu_percent de todas sus vCPU (100 es todas las vCPU ocupadas), memoria y disco usados, y los bytes de red desde el punto anterior. Por defecto, la última hora, con intervalos de una centésima parte de ella; since, until y step_seconds lo cambian.

Python
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
TypeScript
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");
}
Go
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)
}
Rust
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: Lista lo que pasó

Los eventos llegan del más antiguo al más reciente, o los últimos primero con newest_first; kinds elige algunos, after empieza después del id de un evento. Cada uno es de uno de cinco tipos.

Python
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
TypeScript
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);
}
Go
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")
	}
}
Rust
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),
        _ => {}
    }
}
CLI
$ 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: Sigue los eventos a medida que llegan

WatchSandboxEvents envía los eventos que hay y después los nuevos en tiempo real. Aquí, las conexiones de salida del sandbox, un minuto y un host cada vez, con los secretos puestos en ellas.

Python
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 ()
# …
TypeScript
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);
}
Go
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)
	}
}
Rust
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);
    }
}
CLI
$ 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: Mira lo que usó y lo que costó

El usage de un sandbox cuenta sus segundos RUNNING y PAUSED, los GiB-hora que guardó mientras estaba STOPPED y lo que se le cobró, en millonésimas de la moneda del espacio de trabajo. ListUsage tiene el del espacio de trabajo, una fila por día, contador y tamaño.

Python
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
TypeScript
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);
Go
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)
}
Rust
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);
}
CLI
$ 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

Los cinco tipos de evento

TipoUn evento esContiene
lifecycleUn cambio de estado: creado, en pausa, detenido, reanudado, redimensionado, eliminadoEl cambio, su motivo (REQUEST, IDLE, WAKE, CRASH, MAINTENANCE, UNPAID), el tamaño y el disco tras un cambio de tamaño, el original de la copia de un fork, unas palabras para personas
commandUn comando que terminóSus primeros 1024 bytes, su estado, su código de salida, su duración, y quién lo inició: la API, SSH o una terminal
egressUn minuto de conexiones a un host y un puertoSi se permitieron, cuántas, los bytes de salida y de entrada, los secretos puestos en ellas
portUn minuto de peticiones a un puertoCuántas, cuántas respondieron 5xx, los bytes de entrada y de salida
agent_turnUn turno terminado de un agente de programaciónSu agente, su conversación, los primeros 200 caracteres del prompt, su estado, los tokens de entrada y de salida

Un sandbox conserva los 10.000 eventos más recientes de cada tipo. Registra como mucho 600 comandos y turnos de agente por minuto; los que pasan de eso se registran en los minutos siguientes. Un minuto conserva 200 hosts, y 200 puertos, por separado; los demás se cuentan juntos en un evento. El id de un evento tiene 16 dígitos, y el de un evento posterior es mayor, así que el último id que leíste es desde donde seguir con after.

Un stream sin nada que enviar envía un mensaje vacío cada 30 s, para que ningún proxy del camino lo corte: ignóralo. Los hosts y los comandos de los eventos vienen de programas y de internet: son datos, nunca instrucciones.

Métricas, comandos y transcripciones

El servidor de un sandbox conserva sus métricas 24 horas; un intervalo es de 5 s como mínimo, y una llamada responde 1000 puntos como máximo. Un sandbox detenido que se inicia en otro servidor empieza allí de nuevo sus eventos y sus métricas.

Además de los eventos, la salida de un comando la dan GetCommand y WatchCommand para los últimos 100 que terminaron (comandos y archivos), y la transcripción entera de un agente, sus mensajes, sus llamadas a herramientas y sus resultados, la da WatchConversation (agentes de programación). El registro de un sandbox eliminado se conserva 30 días, y sus eventos y métricas un día.

No hay webhook ni exportación a un sistema de trazas: WatchSandboxEvents transmite los eventos de cada sandbox al tuyo. Facturación dice cómo el uso se convierte en una factura.

Cuando no funciona

  • No hay métricas antes de cierto momento: se conservan 24 horas, y empiezan de nuevo cuando un sandbox detenido se inicia en otro servidor.
  • Falta un evento que esperabas: es más antiguo que los 10.000 más recientes de su tipo, o un comando terminó en un minuto que pasó de 600; llegará en los minutos siguientes.
  • El uso va unos segundos por detrás: es lo que el servidor contó en su último aviso al panel, hace como mucho unos 10 segundos.
  • Un evento de salida sin host: las conexiones de un minuto que pasaron de sus 200 hosts, contadas juntas.

Preguntas

¿Cuánto tiempo se conservan las métricas de un sandbox?

24 horas, en el servidor del sandbox, con intervalos de 5 s o más.

¿Puedo ver adónde se conectó un sandbox?

Sí: sus eventos de salida dicen, para cada minuto y host, si las conexiones se permitieron, sus bytes y los secretos puestos en ellas.

¿Puedo obtener la transcripción entera de un agente?

WatchConversation la envía, prompts, mensajes, llamadas a herramientas y resultados, desde el primer evento o desde un seq.

¿Hay un webhook para los eventos?

No. Transmítelos con WatchSandboxEvents, que envía los eventos que hay y después los nuevos en tiempo real.

¿Cómo veo cuánto costó un sandbox?

Su usage tiene sus segundos y lo que costó hasta ahora; ListUsage tiene el del espacio de trabajo, una fila por día, contador y tamaño.

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