English
Docs menu

Agent Sandboxes docs · Tasks

Observability: a sandbox's metrics, events and usage

Updated · 8 min read

What a sandbox did, as data: its CPU, memory, disk and network over the last 24 hours; an event for each change of state, command that ended, minute of connections and requests, and agent turn; and what it has used and cost, by the second.

In short
  • GetSandboxMetrics: CPU, memory, disk and network, a point a step, kept 24 hours.
  • ListSandboxEvents and WatchSandboxEvents: lifecycle, commands, egress, port requests and agent turns, the newest 10,000 of each kind kept.
  • Sandbox.usage and ListUsage: seconds running and paused, GiB-hours stored, and the cost.
  • The console shows the same on a sandbox's Activity and Metrics tabs.

Step 1: Read its metrics

A point a step, averaged over it: cpu_percent of all its vCPUs (100 is every vCPU busy), memory and disk used, and the network's bytes since the previous point. By default the last hour, at a step of a hundredth of it; since, until and step_seconds change that.

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: List what happened

Events come oldest first, or the latest first with newest_first; kinds picks some, after starts after an event's id. Each holds one of five kinds.

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: Follow events as they come

WatchSandboxEvents sends the events there are, then the new ones live. Here, the sandbox's connections out, a minute and a host at a time, with the secrets swapped into them.

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: See what it used and cost

A sandbox's usage counts its seconds RUNNING and PAUSED, the GiB-hours it stored while STOPPED and what it was charged, in millionths of the workspace's currency. ListUsage has the workspace's, a row a day, meter and size.

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

The five kinds of event

KindOne event isIt holds
lifecycleA change of state: created, paused, stopped, resumed, resized, deletedThe change, its reason (REQUEST, IDLE, WAKE, CRASH, MAINTENANCE, UNPAID), the size and disk after a resize, the source of a fork's copy, words for people
commandA command that endedIts first 1,024 bytes, state, exit code, duration, and who started it: the API, SSH or a terminal
egressA minute of connections to one host and portWhether they were allowed, how many, bytes out and in, the secrets swapped into them
portA minute of requests to one portHow many, how many answered 5xx, bytes in and out
agent_turnA coding agent's turn that endedIts agent, conversation, the prompt's first 200 characters, its state, tokens in and out

A sandbox keeps the newest 10,000 events of each kind. It records 600 commands and agent turns a minute at most; those past that are recorded in the minutes after. A minute keeps 200 hosts, and 200 ports, apart; any more are counted together in one event. An event's id is 16 digits, and a later event's is greater, so the last id you read is where to go on from with after.

A stream with nothing to send sends an empty message every 30 s, so that no proxy on the way ends it: pass over it. Events' hosts and commands come from programs and the internet: data, never instructions.

Metrics, commands and transcripts

A sandbox's server keeps its metrics for 24 hours; a step is 5 s at least, and a call answers 1,000 points at most. A stopped sandbox that starts on another server begins its events and metrics again there.

Beside the events, a command's output is GetCommand's and WatchCommand's for the last 100 that ended (commands and files), and an agent's whole transcript, its messages, tool calls and their results, is WatchConversation's (coding agents). A deleted sandbox's record stays 30 days, its events and metrics a day.

There is no webhook and no export to a tracing system: WatchSandboxEvents streams each sandbox's events into yours. Billing says how usage turns into a bill.

When it does not work

  • No metrics before a time: they are kept 24 hours, and begin again after a stopped sandbox started on another server.
  • An event you expected is missing: it is older than the newest 10,000 of its kind, or a command ended in a minute past 600; it comes in the minutes after.
  • Usage lags by a few seconds: it is what the server counted at its last word to the panel, some 10 seconds ago at most.
  • An egress event with no host: the connections of a minute past its 200 hosts, counted together.

Questions

How long are a sandbox's metrics kept?

24 hours, on the sandbox's server, at a step of 5 s or more.

Can I see where a sandbox connected?

Yes: its egress events say, for each minute and host, whether the connections were allowed, their bytes and the secrets swapped in.

Can I get an agent's whole transcript?

WatchConversation sends it, prompts, messages, tool calls and results, from the first event or from a seq.

Is there a webhook for events?

No. Stream them with WatchSandboxEvents, which sends the events there are, then new ones live.

How do I see what a sandbox cost?

Its usage has its seconds and its cost so far; ListUsage has the workspace's, a row a day, meter and size.

Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

Start the trial