> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor sandbox CPU, memory, and disk

> Read timestamped CPU, memory, and disk records for a sandbox from the SDK or the CLI, stream them continuously, and get them as machine-readable JSON.

Sandbox metrics provide timestamped CPU, memory, and disk utilization data for a sandbox. This page reads them from the SDK and from the CLI.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## Get sandbox metrics

Calling the metrics API returns a list of timestamped metric records.

> [!NOTE]
>
> Metrics are sampled every 5 seconds. Metrics do not appear immediately after sandbox creation: before the first sample, the response is empty.

In the CLI example, `<sandbox-id>` is the sandbox ID.

```python Python theme={null}
from time import sleep
from ppio_sandbox import PPIO

ppio = PPIO()
sbx = ppio.sandbox.create()
print('Created sandbox:', sbx.sandbox_id)

# Allow time for metrics collection.
sleep(10)

metrics = sbx.get_metrics()

# Alternative by ID:
# metrics = ppio.sandbox.get_metrics(sbx.sandbox_id)

print('Metrics:', metrics)

sbx.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sbx = await ppio.sandbox.create()
console.log('Created sandbox:', sbx.sandboxId)

// Allow time for metrics collection.
await new Promise((resolve) => setTimeout(resolve, 10_000))

const metrics = await sbx.getMetrics()

// Alternative by ID:
// const metrics = await ppio.sandbox.getMetrics(sbx.sandboxId)

console.log('Metrics:', metrics)

await sbx.kill()
```

```bash CLI theme={null}
# Print the metrics of a sandbox
ppio sandbox metrics <sandbox-id>

# Stream metrics continuously in real time
ppio sandbox metrics <sandbox-id> --follow

# Output machine-readable metrics
ppio sandbox metrics <sandbox-id> --format json
```

## Metric fields

Each record holds a timestamp and the resource values for that sample.

> [tab] Python
>
> **timestamp** `datetime`
>
> Timestamp of the metric entry.
>
> **cpu\_used\_pct** `float`
>
> CPU usage percentage.
>
> **cpu\_count** `int`
>
> Number of CPUs.
>
> **mem\_used** `int`
>
> Memory used, in bytes.
>
> **mem\_total** `int`
>
> Total memory, in bytes.
>
> **disk\_used** `int`
>
> Disk space used, in bytes.
>
> **disk\_total** `int`
>
> Total disk space, in bytes.

> [tab] Node.js
>
> **timestamp** `Date`
>
> Timestamp of the metric entry.
>
> **cpuUsedPct** `number`
>
> CPU usage percentage.
>
> **cpuCount** `number`
>
> Number of CPUs.
>
> **memUsed** `number`
>
> Memory used, in bytes.
>
> **memTotal** `number`
>
> Total memory, in bytes.
>
> **diskUsed** `number`
>
> Disk space used, in bytes.
>
> **diskTotal** `number`
>
> Total disk space, in bytes.


## Related topics

- [Agent Sandbox quotas and limits](https://docs.ppio.ai/sandbox/quotas.md)
- [Pause and resume a sandbox](https://docs.ppio.ai/sandbox/pause-resume.md)
- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.