Sandbox metrics
get_sandbox_metrics answers CPU, where 100% is every vCPU busy, memory in use, disk in use, and bytes in and out, as points averaged over a step: the last hour by default, or any range in the last 24 hours, at a step of 5 s or more, up to 1,000 points. A sandbox’s server keeps its metrics for 24 hours.
Events: what happened, as it happened
Every sandbox records what happened in it, oldest first, as a list you page through or a live stream you follow from any point:
- Lifecycle: created, paused, stopped, resumed, resized and deleted, each with its reason, such as a request, idleness, a wake or a crash; a create names its size, and a fork its source.
- Commands that ended: the first 1,024 bytes of the command, its exit code, how long it ran, and whether the API, SSH or a terminal started it.
- Egress, a minute at a time per host and port: allowed or refused, its connections, bytes each way, and the secrets swapped into its requests.
- Ports, a minute at a time: requests, how many were answered 5xx, and bytes each way.
- Agent turns: the agent, the first 200 characters of the prompt, how the turn ended, and its input and output tokens.
A sandbox keeps the newest 10,000 events of each kind, and a list or a stream can take only the kinds you ask for. It records up to 600 commands and agent turns a minute; any more are recorded in the minutes after.
from pethost.sandboxes import Sandboxes
sandboxes = Sandboxes() # reads PETHOST_TOKEN
sandbox_id = sandboxes.list_sandboxes(name="api-dev").sandboxes[0].sandbox_id
points = sandboxes.get_sandbox_metrics(sandbox_id).points # the last hour
print(max(point.cpu_percent for point in points), points[-1].memory_used_bytes)
for event in sandboxes.watch_sandbox_events(sandbox_id): # what happened so far, then live
if event.command:
print(event.time, event.command.exit_code, event.command.command)
elif event.egress and not event.egress.allowed:
print(event.time, "refused:", event.egress.host)pethost sandbox events api-dev -f # every event, then new ones as they come
pethost sandbox events api-dev --kind egress -n 50 # the last 50 egress eventsCommands, transcripts and usage
Beside the events, list_commands shows what runs now, started by the API, SSH or a terminal. get_command and watch_command give a command’s output, the last 64 KiB and then live, and the sandbox keeps the last 100 commands that ended.
watch_conversation streams a coding agent’s conversation: each prompt, message, tool call with its input and output, and the end of each turn. A conversation stays on the sandbox’s disk: a pause keeps it, a fork carries it, and a template leaves it out.
Each sandbox reports the seconds it ran and was paused, the GiB-hours it was stored and what it cost so far, and list_usage gives a row per day, meter and size, as it was charged. The web console shows a sandbox’s metrics and events on its page.
What is kept, and for how long
Metrics stay 24 hours, and events, the newest 10,000 of each kind, for as long as the sandbox lives. When a sandbox is deleted, its record stays 30 days, with its final usage, and its events and metrics a day.
What is not built yet
There are no webhooks and no OpenTelemetry export yet. To feed your own monitoring, follow the stream, or page through the list from the id of the last event you read: a later event’s id is always greater, so you never read one twice. The observability guide has every field, and the egress allow-list page says how the hosts in egress events are judged.