---
title: "Sandbox observability: metrics and events · Pethost"
description: "See what every Pethost sandbox did: CPU, memory, disk and network for 24 hours, lifecycle events, each command, every host it reached and each agent turn."
---

[Agent Sandboxes](https://pethost.dev/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.

A sandbox’s dashboard: a CPU line, memory in use, and a stream of events: created, a command that exited 0, the hosts it reached, an agent turn with its tokens, paused.

## 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.

Python

CLI

```
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](https://pethost.dev/sandboxes/coding-agents/)’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](https://pethost.dev/docs/sandboxes/observability/) has every field, and the [egress allow-list](https://pethost.dev/sandboxes/egress-allowlist/) page says how the hosts in egress events are judged.

[Read the docs](https://pethost.dev/docs/sandboxes/observability/)

## 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

- [A sandbox’s connections pass a gate that allows pypi.org and *.github.com and refuses example.com with 403; a DNS question for a name not on the list gets REFUSED, and UDP does not leave. Egress you allow, by name List the domains, wildcards, IPs and CIDRs a sandbox may reach; its DNS answers nothing else, no UDP leaves, and a change applies at once. How it works](https://pethost.dev/sandboxes/egress-allowlist/)
- [A prompt to a coding agent in a sandbox, and its tool calls streaming back: it reads a file, edits it, runs the tests, and the turn ends done with its token count. Coding agents, installed Claude Code, Codex and OpenCode run in every sandbox at full autonomy: one call gives one a prompt, another streams each tool call it makes. How it works](https://pethost.dev/sandboxes/coding-agents/)

## Give your agent a computer in 0.15 s

[Start the free trial](https://console.pethost.dev/welcome?kind=sandboxes)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

- [Postgres](https://pethost.dev/postgres/)
- [Valkey](https://pethost.dev/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io pricing](https://pethost.dev/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Docker Compose hosting](https://pethost.dev/blog/managed-docker-compose-hosting/)

Alternatives

- [Railway alternatives](https://pethost.dev/blog/railway-alternatives/)
- [Heroku alternatives](https://pethost.dev/blog/heroku-alternatives/)
- [Dokploy alternatives](https://pethost.dev/blog/dokploy-alternatives/)
- [Coolify alternatives](https://pethost.dev/blog/coolify-alternatives/)
- [Render alternatives](https://pethost.dev/blog/render-alternatives/)
- [Sliplane alternatives](https://pethost.dev/blog/sliplane-alternatives/)
