cosmotop is a system monitoring tool distributed as a single executable for multiple platforms. A fork of btop++ and built with Cosmopolitan Libc.

Installation

Download cosmotop from GitHub releases. Place it anywhere and run!

Homebrew

The Homebrew tap bjia56/tap supports installing the latest cosmotop from GitHub releases on both MacOS and Linux.

brew tap bjia56/tap
brew install cosmotop

Docker

A Docker image is available for Linux x86_64 and aarch64 hosts.

docker run -it --rm --net=host --pid=host ghcr.io/bjia56/cosmotop:latest

Windows setup notes

On Windows, rename cosmotop to either cosmotop.cmd or cosmotop.bat before running. This allows Windows to execute the file as a batch script, which can then properly self-extract and execute the embedded executable.

Desktop application

A desktop GUI application is available on Linux, MacOS, and Windows. Pre-built versions are available in the GitHub releases, which contain cosmotop embedded inside the desktop executable. It is highly recommended to use the Homebrew tap install method on MacOS to bypass the Gatekeeper security warning for the pre-built MacOS app.

Usage and features

Usage: cosmotop [OPTIONS]

Options:
  -h,  --help          show this help message and exit
  -v,  --version       show version info and exit
  -lc, --low-color     disable truecolor, converts 24-bit colors to 256-color
  -t,  --tty_on        force (ON) tty mode, max 16 colors and tty friendly graph symbols
  +t,  --tty_off       force (OFF) tty mode
  -p,  --preset <id>   start with preset, integer value between 0-9
  -u,  --update <ms>   set the program update rate in milliseconds
  -o,  --option        override a configuration option in KEY=VALUE format, can use multiple times
       --show-defaults print default configuration values to stdout
       --show-themes   list all available themes
       --licenses      display licenses of open-source software used in cosmotop
       --debug         start in DEBUG mode: shows microsecond timer for information collect
                       and screen draw functions and sets loglevel to DEBUG
       --mcp           start MCP server mode: exposes system information tools via MCP protocol

GPU monitoring

Monitoring of GPUs is supported on Linux, MacOS, Windows.

• Windows: LibreHardwareMonitor is included with cosmotop and automatically used to fetch GPU information.
• Linux: Intel, AMD, and NVIDIA GPUs are supported, provided the appropriate driver is installed, and the following:
  • Intel: Root privileges are required to access metrics directly. Alternatively, run intel-gpu-exporter in a privileged Docker container, then use the Prometheus configuration options below.
  • AMD: rocm_smi_lib is statically linked and should work out of the box.
  • NVIDIA: libnvidia-ml.so must be available.
• MacOS: Utilization monitoring of the GPU is supported on Apple Silicon. Sudo is not required.

NPU monitoring

Monitoring of NPUs is supported on Linux and MacOS.

• Linux: Utilization monitoring of Intel and Rockchip NPUs is supported on Linux, provided the following:
  • Intel: The path /sys/devices/pci0000:00/0000:00:0b.0 must be readable.
  • Rockchip: The path /sys/kernel/debug/rknpu must be readable.
• MacOS: Utilization monitoring of the Apple Neural Engine is supported on Apple Silicon. Sudo is not required.

GPU and NPU monitoring via Prometheus

cosmotop supports polling an HTTP Prometheus endpoint to read GPU and NPU metrics data. The prometheus_endpoint configuration key should be set to the HTTP endpoint which publishes the metrics.

Some options for exporters and their recommended cosmotop configuration values:

• Linux: intel-gpu-exporter

  prometheus_mapping = "gpu_utilization_percent:igpu_engines_busy_max,gpu_frequency:igpu_frequency_actual,gpu_power_usage:igpu_power_gpu"
  prometheus_settings = "gpu_frequency_unit:mhz,gpu_power_unit:w"
  

• MacOS: macmon-prometheus-exporter

  prometheus_mapping = "gpu_utilization_percent:mac_gpu_usage_percent,gpu_frequency:mac_gpu_frequency_mhz,gpu_power_usage:mac_gpu_power_watts,gpu_temperature:mac_gpu_temperature_celsius,npu_utilization_percent:mac_ane_usage_percent"
  prometheus_settings = "gpu_frequency_unit:mhz,gpu_power_unit:w,gpu_temperature_unit:c"
  

Currently, Prometheus monitoring is only enabled on Linux and MacOS.

Container monitoring

Monitoring of running OCI containers is suppored on Linux, Windows, and MacOS using Docker-compatible APIs. On Linux and MacOS, the standard locations of /run/docker.sock and /var/run/docker.sock are used by default, but can be overriden with the DOCKER_HOST variable to point to an HTTP endpoint or a different socket (e.g. /var/run/podman/podman.sock for Podman containers). Access to the socket must be over plaintext (i.e. no TLS).

When using tools like linuxserver/socket-proxy to secure the Docker API, read-only access to the /version and /containers endpoints is required for monitoring to be enabled.

Configuration

The configuration file for cosmotop is stored at ~/.config/cosmotop/cosmotop.conf, populated with defaults the first time the program runs.

Themes

A number of themes are available within cosmotop. Place custom themes at ~/.config/cosmotop/themes.

MCP mode

Model Context Protocol (MCP) mode is enabled with the --mcp flag and starts cosmotop as a MCP server using the STDIO transport and protocol version 2024-11-05. Normal graphical metrics reporting is disabled during this mode. Tools exposed by cosmotop:

• get_process_info
• get_cpu_info
• get_memory_info
• get_network_info
• get_disk_info
• get_gpu_info (not available if no GPUs are detected)
• get_npu_info (not available if no NPUs are detected)
• get_container_info (not available if no container engines are detected)
• get_system_info

Supported platforms

cosmotop supports the following operating systems and architectures:

Operating system	Hardware architecture
Linux 2.6.18+	x86_64, i386, aarch64, powerpc64le, s390x, riscv64, loongarch64
Windows 10+	x86_64
MacOS 13+	x86_64, aarch64
MacOS 10.4+	powerpc
FreeBSD 13+	x86_64, aarch64
NetBSD 10.0+	x86_64, aarch64
OpenBSD 7.7+	x86_64, aarch64
DragonFlyBSD 6.4+	x86_64
MidnightBSD 3.2.3+	x86_64
Solaris 11.4+	x86_64
Haiku R1/beta5+	x86_64

Core platforms (Linux x86_64/aarch64, MacOS, Windows) are self-contained and require no additional tooling. Other platforms require that the host PATH contains either curl, wget, or python3 to download required plugin components (see below).

How it works

cosmotop uses Cosmopolitan Libc and the Actually Portable Executable (APE) and Chimp file formats to create a single executable capable of running on multiple operating systems and architectures. This multiplatform executable contains code to draw the terminal UI and handle generic systems metrics, like processes, memory, disk, etc. At runtime, the APE executable is extracted out to disk before execution. On Windows, the APE runs natively. On UNIX, a small loader binary is additionally extracted to run the APE executable.

Collecting real data from the underlying system is done by helper plugins, which are built for each target platform using host-native compilers and libraries. On core platforms (see above), plugins are bundled into cosmotop and extracted out onto the host under the path ~/.cosmotop. On other platforms, plugins are downloaded from GitHub releases from the same release tag as cosmotop and placed under ~/.cosmotop, and are optionally re-bundled into the executable. Plugins are used at runtime to gather system metrics that are then displayed by the primary multiplatform executable process in the terminal.

For platforms not supported natively by Cosmopolitan Libc, cosmotop uses the Blink lightweight virtual machine to run the x86_64 version of cosmotop. Data collection is still done by host-native plugin executables.

Building from source

cosmotop is built with CMake. Both the multiplatform host executable and platform-native plugins can be built with the CMakeLists.txt at the root of this repository, but they must be built with separate CMake invocations due to the usage of different compilers.

Building the multiplatform "host" executable

Download the cosmocc toolchain (cosmocc-X.Y.Z.zip) from the Cosmopolitan GitHub releases and extract it somewhere on your filesystem. Add the bin directory to PATH to ensure the compilers can be found. For best results, compile this part on Linux.

On Linux, it may be needed to modify binfmt_misc to run the cosmocc toolchain.

export CC=cosmocc
export CXX=cosmoc++
cmake -B build-host -DTARGET=host
cmake --build build
# or: cmake --build build --parallel

This should produce a cosmotop.com binary.

Building platform-native "plugin" binaries

Platform-native plugins are built as executables on all supported platforms except Windows, which builds as a DLL. To tell CMake to build plugins, use -DTARGET=plugin.

cmake -B build-plugin -DTARGET=plugin
cmake --build build
# or: cmake --build build --parallel

This should produce a cosmotop-plugin.exe (or cosmotop-plugin.dll on Windows). Rename it to cosmotop-<kernel>-<arch>.[exe|dll] matching the target platform, for example:

cosmotop-linux-x86_64.exe
cosmotop-linux-aarch64.exe
cosmotop-macos-x86_64.exe
cosmotop-macos-aarch64.exe
cosmotop-windows-x86_64.dll
cosmotop-freebsd-x86_64.exe
cosmotop-freebsd-aarch64.exe
cosmotop-dragonflybsd-x86_64.exe
cosmotop-netbsd-x86_64.exe
cosmotop-netbsd-aarch64.exe
cosmotop-openbsd-x86_64.exe
cosmotop-openbsd-aarch64.exe
cosmotop-haiku-x86_64.exe

Bundling everything together

The plugin binaries can be added to cosmotop.com with zip, for example:

zip cosmotop.com cosmotop-linux-x86_64.exe

Themes can also be bundled:

zip -r cosmotop.com themes/

Optionally, rename cosmotop.com to cosmotop.exe.

Optional: Producing a Chimp executable

Download chimplink from the Chimp GitHub releases and add it to your PATH.

Build Blink VMs for any platforms not natively supported by Cosmopolitan Libc. Prebuilts for a variety of platforms are available from Blinkverse GitHub releases.

Use chimplink to bundle cosmotop.exe with your selection of loaders, for example:

cosmo_bin=$(dirname $(which cosmocc))
chimplink cosmotop.exe cosmotop some_string_here \
  ${cosmo_bin}/ape-x86_64.elf \
  ${cosmo_bin}/ape-aarch64.elf \
  --os Linux blink-linux-* \
  --os NetBSD blink-netbsd-* \
  --os OpenBSD blink-openbsd-*

For optimal Chimp startup performance, instead of using cosmotop.com after the host build above, use apelink to produce a version that has a special embedded string:

cosmo_bin=$(dirname $(which cosmocc))
apelink \
  -S "V=some_string_here" \
  -l ${cosmo_bin}/ape-x86_64.elf \
  -M ${cosmo_bin}/ape-m1.c \
  -o cosmotop.com \
  build/cosmotop.com.dbg \
  build/cosmotop.aarch64.elf

The final Chimp executable will check if the string matches before overwriting the extracted file on disk. A good choice for this string is a git SHA for uniqueness.

Licensing

Unless otherwise stated, the code in this repository is licensed under Apache-2.0.

For the most up to date list of licenses included in cosmotop release builds, run cosmotop.exe --licenses.