metax-mxtop 0.1.17

An nvitop-like terminal monitor for MetaX GPUs.

metax-mxtop

metax-mxtop is an nvitop-like terminal monitor for MetaX GPUs. Install the PyPI package, then run the mxtop command.

Built upon onlylrs/metax-mxtop, with thanks to the original project for the foundation.

Color bands match nvitop: usage fields and each MEM / MBW / UTL / PWR bar are colored by their own values (memory thresholds 10/80, GPU thresholds 10/75).

Idle — light load, mostly green	Mixed — per-bar color bands	Heavy — saturation across the cluster

16-GPU host? mxtop uses an 8+8 compact layout when the terminal is wide enough, with a single-column fallback for narrower screens.

Features

• nvitop-like terminal dashboard for MetaX GPUs.
• Read-only monitoring through MXSML/Pymxsml or mx-smi.
• GPU device panel with temperature, power, utilization, memory, bus id, persistence, performance state, and driver fields when available.
• Host panel with load average, CPU, memory, swap, and aggregate GPU utilization.
• Process table with GPU, PID, user, GPU memory, GPU utilization, CPU, host memory, runtime, command, selection, scrolling, and sorting.
• ANSI-colored one-shot output and curses TUI colors aligned with the nvitop-style visual hierarchy.
• Shared filters for TUI, text, and JSON output.

The monitor is intentionally read-only. It does not run firmware update, GPU reset, persistence-mode mutation, process kill, or other destructive/admin commands.

Install

From PyPI:

pip install -U metax-mxtop

The installed command is:

mxtop

From source:

git clone https://github.com/linkedlist771/metax-mxtop.git
cd metax-mxtop
pip install -e .

MetaX backend discovery

mxtop tries backends in this order when --backend auto is used:

1. Pymxsml/MXSML, when importable and usable.
2. mx-smi, when the CLI is available.

For the mx-smi backend, the executable path is resolved in this order:

1. Explicit backend path when constructed by callers.
2. MXTOP_MXSMI_PATH environment variable.
3. /opt/mxdriver/bin/mx-smi.
4. mx-smi from PATH.

Example:

MXTOP_MXSMI_PATH=/opt/mxdriver/bin/mx-smi mxtop --backend mxsmi

Usage

Interactive dashboard:

mxtop

One-shot colored text output:

mxtop --once

Plain text output:

mxtop --once --no-color

JSON output:

mxtop --json

Common filters:

mxtop --only 0 1
mxtop --user alice bob
mxtop --pid 1234 5678
mxtop --only-compute
mxtop --only-graphics

Backend and layout options:

mxtop --backend auto
mxtop --backend pymxsml
mxtop --backend mxsmi
mxtop --interval 1.0
mxtop --monitor auto
mxtop --monitor full
mxtop --monitor compact

Useful CLI flags:

Flag	Meaning
--version	Print the runtime version.
--backend {auto,pymxsml,mxsmi}	Select telemetry backend.
--interval SECONDS	TUI refresh interval, minimum 0.25.
--once, -1	Print one text snapshot and exit.
--json	Print one JSON snapshot and exit.
--no-color	Disable ANSI colors in text output.
--monitor {auto,full,compact}	Select TUI layout mode.
--only INDEX...	Show only selected GPU indices.
--user USER...	Show only processes owned by selected users.
--pid PID...	Show only selected process IDs.
--compute, --graphics	Prefer matching process types when available.
--only-compute, --only-graphics	Require matching process types when available.
--ascii, --no-unicode	Reserve ASCII-only rendering mode.

Remote mode (cluster dashboard)

Aggregate several SSH-reachable nodes into one local web dashboard:

pip install 'metax-mxtop[remote]'        # pulls in asyncssh
mxtop --remote-mode --nodes nodeA nodeB nodeC --open
# or list hosts in a file (one per line, # comments allowed)
mxtop --remote-mode --nodes-file ~/hosts.txt --port 8080

• Host names are plain SSH aliases resolved from your ~/.ssh/config (HostName/User/Port/IdentityFile/ProxyJump all honoured), so nodes with different MetaX card configurations work without extra setup.
• Authentication uses your SSH keys / ssh-agent — the "login once" model. For password-only nodes, run ssh-copy-id first; mxtop does not store passwords.
• The dashboard polls every node concurrently (--interval, default 2s), serves on 127.0.0.1 by default (--bind to change), and streams live updates over Server-Sent Events. Unreachable nodes are shown as down instead of breaking the page.
• Each node runs the same mx-smi queries as the local backend; override the remote binary with --remote-mxsmi-path if it is not on PATH.

Interactive keys

Key	Action
q, Esc, Ctrl-C	Quit.
h, ?	Toggle help.
r	Refresh immediately.
j, k, arrow up/down	Move selected process.
PageUp, PageDown	Scroll vertically.
Arrow left/right	Scroll the command column horizontally.
,, .	Cycle process sort field.
/	Reverse current sort.
a	Auto layout.
f	Full layout.
c	Compact layout.
o then a sort key	Direct process sort when supported.

Packaging and releases

The PyPI distribution name is metax-mxtop; the Python import package and CLI command are both mxtop.

pip install metax-mxtop
mxtop --version

Release automation is tag-driven:

1. Bump pyproject.toml, src/mxtop/__init__.py, and tests/test_version.py to the new version.
2. Commit the change.
3. Create a new semver tag, for example v0.1.4.
4. Push the commit and that tag.

GitHub Actions then builds the wheelhouse, creates or updates the GitHub Release, and publishes the package to PyPI through Trusted Publishing for v* tags.

More previews

See GALLERY.md for a tile of rendered stdout across common CLI parameter combinations — colour palettes, layout modes, filters, custom intensity thresholds, multi-GPU layouts, and JSON output.

Development

Run tests and lint locally:

uv run --with pytest --with psutil pytest -q
uv run --with ruff ruff check .
uv run --with build python -m build

More background is available in INTRO.md.