✓ Stable v0.1.0

gartop

Real-time system monitor for the gardesk desktop

gartop is a daemon-based system monitor featuring real-time graphs for CPU, memory, network, and disk I/O. It includes an interactive process list with tree view, sorting, search, and kill functionality, plus automatic container detection for Docker, Podman, and Kubernetes. Built on gartk with a Catppuccin-themed interface and per-process network socket tracking.

View on GitHub Download RPM

🎯 RPM Available

Installation

Using DNF (Recommended)

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install gartop

Building from Source

$git clone https://github.com/espadon/gardesk.git

$cd gardesk/gartop

$cargo build --release

$sudo cp target/release/gartop /usr/local/bin/

$sudo cp target/release/gartopctl /usr/local/bin/

Quick Start

$# Launch the GUI (auto-starts daemon if needed)

$gartop

$# Or start daemon separately

$gartop daemon &

$gartop gui

$# Open directly to a specific tab

$gartop --pane memory

$gartop --pane network

$# Run daemon in foreground (debugging)

$gartop daemon --foreground

Keyboard Shortcuts

Key	Action
`Tab`	Cycle to next tab (CPU → Memory → Network → Disk)
`1 / 2 / 3 / 4`	Jump to CPU / Memory / Network / Disk tab
`Up / k`	Move selection up in process list
`Down / j`	Move selection down in process list
`Page Up`	Page up in process list
`Page Down`	Page down in process list
`Home / g`	Jump to first process
`End / G`	Jump to last process
`f`	Freeze/unfreeze updates (for manual navigation)
`t`	Toggle tree view (process hierarchy)
`/ or s`	Search/filter processes by name
`k`	Kill selected process (sends SIGTERM)
`K`	Force kill selected process (sends SIGKILL)
`h / ?`	Show help overlay
`q / Escape`	Quit (or clear search)

Features

Real-time Graphs

Time-series visualization with 5-minute history. Line graphs with optional fill, configurable grid lines, legend, and auto-scaled Y-axis.

Process Management

Tree view with parent-child hierarchy, 10 sort modes, search filter, freeze mode for navigation, and kill with SIGTERM/SIGKILL.

Per-Process Network

Socket tracking via netlink INET_DIAG. TCP/UDP counts, listen/established states, and bandwidth rates per process.

Container Detection

Automatic identification of Docker, Podman, Kubernetes, and LXC containers via cgroup path parsing.

Hardware Sensors

Temperature sensors from /sys/class/hwmon. GPU utilization, VRAM, clock speed, and power usage for AMD DRM devices.

IPC Control

JSON protocol over Unix socket. gartopctl for scripted queries, garbar integration, and real-time event subscription.

Command Line Options

Option	Type	Default	Description
`gartop`	subcommand	gui	Launch GUI (starts daemon if needed)
`gartop gui`	subcommand	-	Explicitly start GUI mode
`gartop daemon`	subcommand	-	Run as background daemon
`--pane`	string	"cpu"	Initial pane: cpu, memory, network, disk
`--config`	path	~/.config/gartop/config.toml	Configuration file path
`--foreground`	flag	false	Run daemon in foreground (for debugging)

Configuration File

gartop is configured via TOML at ~/.config/gartop/config.toml. Custom path via --config flag.

# ~/.config/gartop/config.toml

[daemon]
# Data collection interval in milliseconds
sample_interval_ms = 1000

# Number of samples to keep in history
# At 1000ms = 5 minutes of history
history_size = 300

# Maximum processes to track (sorted by CPU)
max_processes = 100

[gui]
# Initial window dimensions
width = 600
height = 500

# GUI refresh rate in FPS
refresh_rate = 30

# Show legend on graphs
show_legend = true

# Font settings
font_family = "sans-serif"
font_size = 12.0

# Initial tab: cpu, memory, network, disk
# Omit to open to CPU tab
default_pane = "cpu"

[daemon] Options

Option	Type	Default	Description
`sample_interval_ms`	u64	1000	Data collection interval in milliseconds
`history_size`	usize	300	Number of samples to keep (5 min at 1Hz)
`max_processes`	usize	100	Maximum number of processes to track

[gui] Options

Option	Type	Default	Description
`width`	u32	600	Initial window width in pixels
`height`	u32	500	Initial window height in pixels
`refresh_rate`	u32	30	GUI refresh rate in FPS
`show_legend`	bool	true	Show legend on graphs
`font_family`	string	"sans-serif"	Font family for UI text
`font_size`	f64	12.0	Font size in points
`default_pane`	string?	none	Initial tab: cpu, memory, network, disk

Systemd User Service

Run gartop daemon as a user service for automatic startup:

# ~/.config/systemd/user/gartop.service
[Unit]
Description=gartop system monitor daemon
After=graphical-session.target
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/local/bin/gartop daemon
Restart=on-failure
RestartSec=3s

[Install]
WantedBy=graphical-session.target

$systemctl --user daemon-reload

$systemctl --user enable --now gartop

$systemctl --user status gartop

Overview

gartop is a system monitor designed for the gardesk desktop, providing real-time visualization of system resources. It uses a daemon/GUI split architecture where a background process continuously collects metrics and the GUI connects via IPC for visualization.

The daemon maintains ring buffers of historical data (default 300 samples = 5 minutes), while the GUI renders graphs and process lists at a configurable refresh rate. Multiple GUI windows can connect to the same daemon.

Architecture

Daemon Mode

The daemon (gartop daemon) runs as a background process, listening on a Unix socket at $XDG_RUNTIME_DIR/gartop.sock.

Accepts IPC commands from CLI clients and GUI
Independent lifecycle - persists across GUI window closures
Spawns multiple async collection tasks
Maintains DaemonState with all collectors and history buffers

GUI Mode

The GUI (gartop or gartop gui) connects to the running daemon and renders the interface:

Header bar (56px): CPU %, memory %, network/disk rates, max temp, GPU %
Tab bar (32px): CPU, Memory, Network, Disk tabs
Graph area (150px): Time-series visualization
Details section: Tab-specific stats (per-core, per-interface, etc.)
Process list (variable): Scrollable table with 22px row height

Collection Loops

The daemon runs two collection loops:

Primary Loop (sample_interval_ms, default 1s):
├─ CPU Collector → reads /proc/stat
├─ Memory Collector → reads /proc/meminfo
├─ Network Collector → reads /proc/net/dev
└─ Disk Collector → reads /proc/diskstats

Secondary Loop (2× sample_interval_ms, default 2s):
└─ Process Collector → reads /proc/[pid]/*
    ├─ Calculates CPU % from jiffy deltas
    ├─ Reads I/O stats from /proc/[pid]/io
    ├─ Correlates sockets via inode mapping
    └─ Detects containers from cgroup paths

Temperature and GPU metrics are collected on-demand when requested via IPC.

Data Collectors

Each metric type has a dedicated collector that reads from Linux kernel interfaces.

CPU Collector

Source: /proc/stat

Reads kernel CPU times (user, nice, system, idle, iowait, irq, softirq, steal) and calculates usage percentage from deltas between samples:

active = user + nice + system + irq + softirq + steal
total = active + idle + iowait
usage_percent = (active_delta / total_delta) × 100

Data tracked: usage_percent (0-100), per_core array, core_count, timestamp

Memory Collector

Source: /proc/meminfo

Uses MemAvailable (kernel 3.14+) for accurate available memory calculation:

used = total - available
swap_used = swap_total - swap_free
usage_percent = (used / total) × 100

Data tracked: total, used, free, available, swap_total, swap_used, usage_percent

Network Collector

Source: /proc/net/dev

Parses interface statistics and calculates rates from byte deltas. Automatically filters out:

lo (loopback)
veth* (Docker virtual interfaces)
docker* (Docker bridges)

Per-interface data: interface name, rx/tx_bytes, rx/tx_packets, rx/tx_rate (bytes/sec)

Disk Collector

Source: /proc/diskstats

Reads sector counts and converts to bytes (512 bytes/sector). Filters to physical disks only:

Includes: sda, sdb, nvme0n1, vda (physical devices)
Excludes: loop*, dm-*, ram* (virtual devices)
Excludes: partitions (sda1, nvme0n1p1)

Per-device data: device name, read/write_bytes, reads/writes, read/write_rate

Temperature Collector

Source: /sys/class/hwmon/

Scans all hwmon devices and reads temperature sensors:

temp*_input - Temperature in millidegrees ÷ 1000
temp*_label - Human-readable name (Core 0, Package, etc.)
temp*_crit - Critical threshold
temp*_max - High threshold

Per-sensor data: label, device, temp_celsius, critical, high

GPU Collector

Source: /sys/class/drm/

Scans DRM card* entries (not renderD*) and reads GPU metrics from sysfs/hwmon:

Model: from uevent DRIVER or product_name
Utilization: gpu_busy_percent (AMD)
VRAM: vram_used/vram_total
Clock: freq1_input or pp_dpm_sclk
Temperature: hwmon/temp1_input
Power: hwmon/power1_average (microwatts → watts)

Process Collector

Source: /proc/[pid]/

Iterates all processes and collects comprehensive per-process statistics:

CPU %: Calculated from jiffy deltas vs system total
Memory %: RSS / total_memory × 100
I/O: read/write bytes and rates from /proc/[pid]/io
Network: Socket counts and bandwidth (see Socket Collector)
State: R (running), S (sleeping), D (disk), Z (zombie), T (stopped)
Container: Detected from cgroup paths

Socket Collector

Sources: /proc/net/tcp*, /proc/net/udp*, netlink INET_DIAG

The socket collector uses a two-phase approach for per-process network stats:

Parse procfs: Read /proc/net/tcp, tcp6, udp, udp6 for socket info
Query netlink: INET_DIAG requests for bandwidth counters (rx/tx_bytes)
Inode correlation: Match socket inodes from /proc/[pid]/fd to sockets

Per-process network data: net_connections, net_tcp, net_udp, net_listen, net_established, net_rx_rate, net_tx_rate

GUI Features

Tab Views

Four main tabs, each with dedicated graph and details:

CPU: Overall usage graph + per-core breakdown + top CPU consumers
Memory: Memory usage graph (used + swap) + breakdown + top memory consumers
Network: Interface stats + RX/TX rates + top bandwidth consumers
Disk: Device stats + read/write rates + top I/O consumers

Graphs

Line graphs with optional fill under curve. Features:

Configurable grid lines (default: 4)
Legend in top-right corner (optional)
Auto-scaled Y-axis (0-100% for percentages)
X-axis represents time (history depth)
Multiple data series per graph with distinct colors

Color scheme (Catppuccin): CPU pink (#f38ba8), Memory green (#a6e3a1), Swap yellow (#f9e2af), Network teal (#94e2d5), Disk mauve (#cba6f7)

Process List

Scrollable process table with rich features:

Row height: 22px per process
Header height: 24px with column labels
Selection tracking: Follows process by PID across reorders
Grace period: 400ms after user navigation before auto-scroll
Columns: PID, Name, User, CPU %, Mem %, RES, Disk R/W, Net, Container

Tree View

Toggle with t to show process hierarchy:

Builds parent→children map using PPID
Root processes: ppid=0, ppid=1, or parent not in list
DFS traversal with indent levels
Children sorted by CPU within each parent
Visual tree lines (├── and └──)

Header Bar

56px header showing key metrics at a glance:

┌─────────────────────────────────────────────────────────┐
│ gartop    CPU 15% │ MEM 42% │ NET ↓1.2M ↑500K │ DSK ...│
└─────────────────────────────────────────────────────────┘

Also shows max temperature and GPU utilization when available.

Container Detection

gartop detects containerized processes by parsing /proc/[pid]/cgroup:

Runtime	Cgroup Pattern	Display Format
Docker	`/docker/{id}`	`docker:a1b2c3d4e5f6`
Podman	`/libpod-{id}.scope`	`podman:7f8g9h0i1j2k`
Kubernetes	`/kubepods/...`	`k8s:pod123abc`
LXC	`/lxc/{name}`	`lxc:mycontainer`

Container ID is shown in the process list when detected (first 12 characters).

Theme & Colors

gartop uses a Catppuccin Mocha-inspired color scheme:

UI Colors

Background: #1e1e2e
Panel: #313244
Header: #45475a
Text: #cdd6f4
Accent: #89b4fa

Graph Colors

CPU: #f38ba8 (pink)
Memory: #a6e3a1 (green)
Swap: #f9e2af (yellow)
Network: #94e2d5 (teal)
Disk: #cba6f7 (mauve)
Temperature: #fab387 (peach)
GPU: #89dceb (sky)

CPU Metrics

Collected from /proc/stat:

{
  "usage_percent": 45.2,
  "per_core": [20.5, 60.1, 30.3, 50.8],
  "core_count": 4,
  "timestamp": 1707000000000
}

Memory Metrics

Collected from /proc/meminfo:

{
  "total": 16000000000,
  "used": 8000000000,
  "free": 2000000000,
  "available": 6000000000,
  "swap_total": 4000000000,
  "swap_used": 500000000,
  "usage_percent": 50.0,
  "timestamp": 1707000000000
}

Network Metrics

Per-interface statistics from /proc/net/dev:

[
  {
    "interface": "eth0",
    "rx_bytes": 1000000,
    "tx_bytes": 500000,
    "rx_packets": 5000,
    "tx_packets": 2500,
    "rx_rate": 10000.0,
    "tx_rate": 5000.0,
    "timestamp": 1707000000000
  }
]

Disk Metrics

Per-device statistics from /proc/diskstats:

[
  {
    "device": "sda",
    "read_bytes": 10000000,
    "write_bytes": 5000000,
    "reads": 1000,
    "writes": 500,
    "read_rate": 100000.0,
    "write_rate": 50000.0,
    "timestamp": 1707000000000
  }
]

Temperature Metrics

From /sys/class/hwmon/:

{
  "sensors": [
    {
      "label": "Core 0",
      "device": "coretemp",
      "temp_celsius": 55.2,
      "critical": 100.0,
      "high": 80.0
    }
  ],
  "timestamp": 1707000000000
}

GPU Metrics

From /sys/class/drm/ (AMD):

{
  "devices": [
    {
      "name": "card0",
      "model": "amdgpu",
      "usage_percent": 30.5,
      "vram_used": 2000000000,
      "vram_total": 4000000000,
      "clock_mhz": 1500,
      "temp_celsius": 65.0,
      "power_watts": 150.0
    }
  ],
  "timestamp": 1707000000000
}

Process Metrics

Per-process statistics from /proc/[pid]/:

{
  "pid": 1234,
  "ppid": 1,
  "name": "firefox",
  "cmdline": "/usr/bin/firefox --new-window",
  "cpu_percent": 25.5,
  "memory_percent": 10.2,
  "rss": 1000000000,
  "vsize": 2000000000,
  "io_read_bytes": 500000000,
  "io_write_bytes": 100000000,
  "io_read_rate": 50000.0,
  "io_write_rate": 10000.0,
  "net_connections": 15,
  "net_tcp": 12,
  "net_udp": 3,
  "net_listen": 0,
  "net_established": 10,
  "net_rx_rate": 100000.0,
  "net_tx_rate": 50000.0,
  "state": "sleeping",
  "user": "user",
  "container": "docker:a1b2c3d4e5f6"
}

IPC Overview

The daemon listens on a Unix socket for JSON commands:

Location: $XDG_RUNTIME_DIR/gartop.sock or /tmp/gartop.sock
Permissions: 0600 (user-only)
Protocol: Line-delimited JSON

IPC Commands

Command	Parameters	Description
`status`	none	Get daemon status (version, uptime, sample interval)
`get_cpu`	none	Get current CPU statistics
`get_cpu_history`	count?	Get CPU usage history (optional count)
`get_memory`	none	Get current memory statistics
`get_memory_history`	count?	Get memory usage history
`get_network`	none	Get per-interface network statistics
`get_network_history`	count?	Get network history
`get_disk`	none	Get per-device disk statistics
`get_disk_history`	count?	Get disk history
`get_temperature`	none	Get all temperature sensors
`get_gpu`	none	Get GPU statistics
`get_processes`	sort_by?, limit?	Get sorted process list
`kill_process`	pid, signal?	Kill process (default: SIGTERM)
`subscribe`	events[]	Subscribe to real-time updates
`unsubscribe`	events[]	Unsubscribe from events
`reload`	none	Reload daemon configuration
`quit`	none	Stop the daemon

Process Sorting Options

Sort Field	Description
`cpu`	Sort by CPU usage (default)
`memory`	Sort by memory usage
`pid`	Sort by process ID
`name`	Sort alphabetically by name
`disk_read`	Sort by disk read rate
`disk_write`	Sort by disk write rate
`disk_total`	Sort by total disk I/O
`net_connections`	Sort by network connections
`net_tcp`	Sort by TCP connections
`net_bandwidth`	Sort by network bandwidth

gartopctl Examples

$gartopctl status

{ "version": "0.1.0", "uptime_secs": 3600, "sample_interval_ms": 1000 }

$gartopctl cpu

{ "usage_percent": 15.5, "per_core": [12.3, 18.7, 14.2, 16.8] }

$gartopctl processes --sort memory --limit 5

[ {"pid": 1234, "name": "firefox", "cpu_percent": 8.2, "memory_percent": 15.3}, ... ]

$gartopctl kill 1234

{"success": true}

$gartopctl kill 1234 --signal 9

{"success": true} # SIGKILL

Event Subscription

Subscribe to real-time metric updates:

# Subscribe command
{"command": "subscribe", "events": ["cpu_update", "memory_update"]}

# Streaming responses (one per line)
{"event": "cpu_update", "usage_percent": 45.2, ...}
{"event": "memory_update", "usage_percent": 50.0, ...}

garbar Integration

Configure garbar module clicks to open gartop:

-- ~/.config/gar/init.lua
gar.bar.modules = {
    {
        type = "cpu",
        on_click = "gartop --pane cpu",
    },
    {
        type = "memory",
        on_click = "gartop --pane memory",
    },
    {
        type = "battery",
        -- Show CPU+memory when clicking battery (power consumption)
        on_click = "gartop --pane cpu",
    },
}

GUI Shows "Not Connected"

The daemon must be running before the GUI can connect:

$# Check if daemon is running

$pgrep -a gartop

$# Check socket exists

$ls -la $XDG_RUNTIME_DIR/gartop.sock

$# Start daemon and GUI

$gartop daemon &

$gartop gui

Missing Temperature Sensors

Temperature sensors require kernel modules and lm_sensors:

$sudo dnf install lm_sensors

$sudo sensors-detect

# Answer YES to load modules

$sensors

coretemp-isa-0000 Core 0: +45.0°C (high = +80.0°C, crit = +100.0°C)

$# Check hwmon directories

$ls /sys/class/hwmon/

hwmon0 hwmon1 hwmon2

Per-Process I/O Shows Zeros

Reading /proc/[pid]/io requires elevated permissions:

$# Check permissions on io file

$ls -la /proc/self/io

-r-------- 1 user user 0 Feb 3 12:00 /proc/self/io

$# Run gartop daemon with capabilities

$sudo setcap cap_dac_read_search+ep /usr/local/bin/gartop

Alternatively, run the daemon as root (not recommended for general use).

GPU Stats Not Showing

GPU monitoring requires DRM device access:

$# Check DRM devices

$ls /sys/class/drm/

card0 card1 renderD128

$# Check GPU info file

$cat /sys/class/drm/card0/device/uevent

DRIVER=amdgpu

$# Ensure user is in video group

$groups $USER

user wheel video

Network Stats Per-Process Not Working

Per-process network stats use netlink, which may require permissions:

$# Check netlink capabilities

$sudo setcap cap_net_admin+ep /usr/local/bin/gartop

$# Or add user to netlink group (if exists)

$sudo usermod -aG netlink $USER

Debug Mode

Enable verbose logging for troubleshooting:

$# Run daemon with debug logging

$RUST_LOG=debug gartop daemon --foreground

$# Filter to specific modules

$RUST_LOG=gartop::collector=debug gartop daemon --foreground

High CPU Usage

If gartop itself uses too much CPU:

# Increase sample interval
[daemon]
sample_interval_ms = 2000  # 2 seconds instead of 1

# Reduce max processes tracked
max_processes = 50

# Lower GUI refresh rate
[gui]
refresh_rate = 15  # 15 FPS instead of 30