English
Get started

Agent Sandboxes Every command, host and turn

See everything a sandbox did

When an agent’s run goes wrong, you want to know what happened inside its sandbox. Sandbox observability keeps the answer: metrics, a record of every command, every host reached and every agent turn, through the same API that runs them.

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 events

Commands, 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.

Read the docs

Questions

How long are sandbox metrics kept?

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

Can I send events to my monitoring?

Not by push yet: there are no webhooks or OpenTelemetry export. Follow watch_sandbox_events, or poll list_sandbox_events with the id of the last event you read.

Are an agent’s transcripts kept?

Yes, on the sandbox’s disk, for as long as the sandbox lives. A pause keeps them, and a fork carries them.

Can I see which hosts a sandbox reached?

Yes. Its egress events list each host and port a minute at a time, allowed or refused, with its connections and bytes each way.

What remains after a sandbox is deleted?

Its record, with its final usage, for 30 days; its events and metrics for a day.

Related

Give your agent a computer in 0.15 s

Start the free trial