Agent Sandboxes docs · Tasks
Observability: a sandbox's metrics, events and usage
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.
GetSandboxMetrics: CPU, memory, disk and network, a point a step, kept 24 hours.ListSandboxEventsandWatchSandboxEvents: lifecycle, commands, egress, port requests and agent turns, the newest 10,000 of each kind kept.Sandbox.usageandListUsage: 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.
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: 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.
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: 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.
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: 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.
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
The five kinds of event
| Kind | One event is | It holds |
|---|---|---|
lifecycle | A change of state: created, paused, stopped, resumed, resized, deleted | The 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 |
command | A command that ended | Its first 1,024 bytes, state, exit code, duration, and who started it: the API, SSH or a terminal |
egress | A minute of connections to one host and port | Whether they were allowed, how many, bytes out and in, the secrets swapped into them |
port | A minute of requests to one port | How many, how many answered 5xx, bytes in and out |
agent_turn | A coding agent's turn that ended | Its 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.