sgtop

Linux macOS Usage Python License Contributors

A btop-style terminal dashboard for a live SGLang deployment. Not affiliated with the SGLang project — just a small, read-only tool that never touches your inference traffic.

sgtop screenshot

nvtop will tell you a GPU is at 98% utilization. It won't tell you whether your sglang server can actually take more concurrent requests, whether one data-parallel replica is sitting idle while another is drowning, or what your real time-to-first-token looks like. That's what this is for: concurrency vs. the capacity sglang actually computed at startup, KV-cache headroom per replica, and (with --enable-metrics) rolling TTFT/E2E/queue-time percentiles.

Install

pipx install sgtop

Pure standard library, no dependencies, Python ≥ 3.9. pip install --user sgtop works too if you don't have pipx.

Quick start

Point it at a running sglang instance — that's it, nothing else to run:

sgtop --host <sglang-host> --port 30000

Leave out --port entirely and it'll probe a handful of common ports for you. For the LATENCY panel (TTFT / end-to-end / queue-time / cache-hit-rate), start sglang with --enable-metrics; without it you still get concurrency, KV-cache usage, and decode throughput straight off sglang's own API. Prometheus histograms are cumulative counters, so sgtop diffs consecutive scrapes itself to give you an actual rolling 5-minute p50/p90/p99, not a number that just drifts toward whatever your first few requests looked like.

Run sgtop right on the sglang box (or ssh in and run it there) and the GPU panel fills in for free — it shells out to the local nvidia-smi, i.e. whatever's on the machine sgtop itself is running on. Watching a remote instance from somewhere without GPUs of its own just leaves that panel empty, correctly.

The optional sidecar

The one thing sglang's own API genuinely can't give you is a recent-errors line — that needs its log file, which isn't exposed over HTTP at all. For that there's sgtop-server, a small sidecar you can run on the sglang box that also tails its log:

python -m sglang.launch_server --model-path ... --enable-metrics > server.log 2>&1 &
sgtop-server --log server.log --service-port 30000 --port 30001 &
sgtop --port 30001    # or --mode proxy to skip auto-detection

It also serves a plain HTML version of the same data at http://<host>:30001/. Everything else — concurrency, KV-cache, latency — works exactly the same with or without it.

q quits. That's the whole interface.

License

MIT

Environment
- Console :: Curses
Intended Audience
- Science/Research
Operating System
- MacOS
- POSIX :: Linux
Programming Language
- Python :: 3
Topic
- System :: Monitoring

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sgtop-0.1.5.tar.gz (26.6 kB view details)

Uploaded Sep 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sgtop-0.1.5-py3-none-any.whl (28.9 kB view details)

Uploaded Sep 4, 2026 Python 3

File details

Details for the file sgtop-0.1.5.tar.gz.

File metadata

Download URL: sgtop-0.1.5.tar.gz
Upload date: Sep 4, 2026
Size: 26.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sgtop-0.1.5.tar.gz
Algorithm	Hash digest
SHA256	`65e71eb058838f93570d69ba6259fdf201bbda43523a923a490506ae35fa4d0b`
MD5	`f42646d0270607ad1abeddf9d69464b2`
BLAKE2b-256	`81f74d1a715375d6487f75417966bf6a270e2c7dba6fdee0821b50744a851fce`

See more details on using hashes here.

Provenance

The following attestation bundles were made for sgtop-0.1.5.tar.gz:

Publisher: publish.yml on HarrytheOrange/sgtop

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: sgtop-0.1.5.tar.gz
- Subject digest: 65e71eb058838f93570d69ba6259fdf201bbda43523a923a490506ae35fa4d0b
- Sigstore transparency entry: 2709039231
- Sigstore integration time: Sep 4, 2026
Source repository:
- Permalink: HarrytheOrange/sgtop@d27967f8369d184716a4d36f8fe6b92dc629a837
- Branch / Tag: refs/tags/v1.5
- Owner: https://github.com/HarrytheOrange
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@d27967f8369d184716a4d36f8fe6b92dc629a837
- Trigger Event: release