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

# Live monitoring dashboard

> Real-time CPU, memory, and uptime dashboard streamed through a sandbox PTY with sparklines and in-place refresh.

A small Python program runs inside the sandbox and renders a
full-screen dashboard that refreshes every 500 ms for \~15 seconds.
CPU usage, memory, uptime, and a sparkline history are all read from
`/proc` inside the VM and painted with ANSI cursor-home + overwrite
so the screen never scrolls. Every frame streams through the PTY's
SSE pipe and your local terminal renders it in place.

## Use case

Proof that full-screen TUIs work over the declaw PTY. If a dashboard
with in-place refresh, box-drawing characters, and colour-coded bars
renders correctly, so will `htop`, `vim`, `tmux`, and any curses app.

## What you'll learn

* Uploading a script with `sbx.files.write()` and running it through the PTY
* In-place refresh via ANSI `\e[H` (cursor home) without scrolling
* Reading real `/proc/stat`, `/proc/meminfo`, `/proc/uptime` from the sandbox VM
* Sparkline rendering with Unicode block elements
* Graceful `KeyboardInterrupt` handling with `handle.kill()`

## Prerequisites

<Snippet file="snippets/env-setup.mdx" />

```bash theme={null}
pip install declaw
```

## Code walkthrough

The driver is short. It uploads a dashboard program to `/tmp`, runs
it through a PTY, and waits for it to finish:

```python theme={null}
with Sandbox.create(template="python") as sbx:
    sbx.files.write("/tmp/dashboard.py", DASHBOARD_PROGRAM)

    handle = sbx.pty.create(
        size=PtySize(cols=80, rows=24),
        on_data=lambda b: (
            sys.stdout.buffer.write(b),
            sys.stdout.buffer.flush(),
        ),
        timeout=60,
    )
    handle.send_stdin("python3 /tmp/dashboard.py && exit\n")
    result = handle.wait(timeout=30)
```

The `DASHBOARD_PROGRAM` string (embedded in the source file) does
the heavy lifting inside the VM:

1. **CPU** -- reads `/proc/stat` twice with a 500 ms gap, computes
   the delta, and derives a percentage.
2. **Memory** -- reads `MemTotal` and `MemAvailable` from
   `/proc/meminfo`.
3. **Uptime** -- reads `/proc/uptime`.
4. **Sparkline** -- maintains a rolling history list and maps each
   bucket to one of eight Unicode block characters.
5. **Refresh** -- `\e[H` (cursor home) before every frame so the
   dashboard overwrites itself in place.

## Running it

```bash theme={null}
export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="api.declaw.ai"
python cookbook/examples/pty-dashboard/main.py
```

You should see a box-drawn dashboard that updates \~30 times over
15 seconds, then exits. Press `Ctrl-C` at any point to stop early.

## Expected output

A single in-place frame looks roughly like this (colours omitted):

```
+-- declaw sandbox live dashboard -------------------------+
|  wall:  14:32:07   uptime:    6.2s   frame:   12        |
+----------------------------------------------------------+
|  CPU   [============                            ]  28.3% |
|  MEM   [=====                                   ]  12.1% |
|         62.0 MB / 512.0 MB used                          |
+-- CPU history -------------------------------------------+
|  ___..--''``--..___..--''``                               |
+----------------------------------------------------------+
```

## Full source

See `cookbook/examples/pty-dashboard/main.py` in the repo.