Skip to main content

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.

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

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

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.