Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

ltop (localist top) is a terminal monitor for a single machine. It answers three questions btop, nethogs and iftop each answer only in part:

  1. Where does the traffic go? — who talks to whom, on which interface, at what rate, with true per-connection and per-process byte accounting (TCP and UDP).
  2. What are the processes doing? — who eats bandwidth and disk right now, and who did over the whole session, including processes that already exited.
  3. What does the LAN look like? — which devices are on the local network, which is the gateway, and what traffic flows to each of them.

How it works

Six boxes, one job each (NET, LAN, DISK I/O, DISKS, CONNS, PROCS), rendered with ratatui in a btop-style braille-chart aesthetic. The main program runs unprivileged — no root, no setuid, no daemon. On Linux an optional privileged helper (ltop-bpf, a tiny eBPF collector) unlocks per-process and per-connection byte accounting for TCP and UDP; without it everything else keeps working. On macOS the same six boxes read Apple-native sources (nettop, libproc, IOKit, the route socket). Every display surface is backed by one machine-readable data plane: ltop --json emits a schema-v1 snapshot, ltop watch records it headlessly, and ltop report sums a window of it — which is what makes ltop usable by AI agents (~97 % fewer tokens than polling, see AI agents).

Highlights

  • True per-connection accounting — every TCP connection shows live B/s and cumulative totals; UDP connections are eBPF-metered and get the same columns. Closed connections linger as 5-second tombstones so short bursts stay readable.
  • Per-process totals that survive restarts — PROCS accumulates network (TCP+UDP) and disk I/O per process for the whole session; exited processes stay grayed out with their captured command line and can be relaunched with one key.
  • LAN neighbours with traffic — passive ARP plus a periodic UDP-knock sweep finds same-subnet devices (IP, MAC, mDNS hostname, interface); each neighbour carries its live connection count, rate and accumulated bytes, and enter pins it and filters CONNS to that peer.
  • Headless watch + report — record a time window to crash-safe JSONL, then get exact window sums, peak rates and active time per process/connection as a table or ~2 KB of JSON.
  • 72 embedded btop themes — any btop theme works as-is; on Omarchy the palette can follow the desktop theme, optionally re-coloring a running ltop (--follow-theme). UI in English or Chinese (lang = zh).
  • Three layouts, one keystroke apart — Tab cycles classic / wide / tall; boxes toggle with 1–6; z zooms the focused box full-screen.

Where to go next

  • Quick start — install and the keys that matter, in two minutes.
  • Installation — all channels, platform requirements and the eBPF helper deployment.
  • The TUI — the full surface: boxes, layouts, key bindings.
  • AI agents — the JSON snapshot, watch + report, and the bundled agent skill.

Status

ltop is MIT-licensed, developed daily on Omarchy (Arch Linux), and verified per release in QEMU/KVM across five Linux distributions plus on macOS hardware — see Compatibility. Distribution channels: Homebrew, crates.io, and GitHub Releases tarballs (x86_64 + aarch64); an AUR ltop-bin package is ready and pending the AUR reopening registration.

Quick start

1. Install (one line)

brew install uMaj35ty/ltop/ltop     # macOS & Linux — prebuilt binaries

or, with a Rust toolchain:

cargo install ltop                  # compiles from source (crates.io)

or grab a tarball from GitHub Releases (x86_64 / aarch64, Linux and macOS). All channels are covered in Installation.

2. Run it

ltop

No configuration, no root. You land on the classic layout: charts on the left (NET up top, DISK I/O below), tables on the right (LAN, CONNS, PROCS, DISKS).

3. The keys that matter

Everything is reachable from these ten; the footer always shows the current context, and m → help has the full table (also in The TUI).

KeyDoes
Tabcycle layout: classic → wide → tall
1–6toggle a box (1 net, 2 lan, 3 disk i/o, 4 disks, 5 conns, 6 procs)
/search processes/connections by name substring
p / c / lsingle-focus PROCS / CONNS / LAN (one lights up, the rest dim)
↑↓ + enterselect a row → detail panel (full command line, per-connection breakdown, uptime)
enter on a LAN rowpin the neighbour and filter CONNS to that peer — “show me everything talking to this device”
f / oCONNS: cycle filter (all/lan/tcp/udp) / sort (proc-grouped, sum, name, rate)
rPROCS: cycle sort (net-sum, net-rate, disk-sum, disk-rate, name)
zzoom the focused box full-screen (esc restores)
mmenu: themes, settings, graphs, help
spacepause/resume sampling (bytes missed while paused are back-filled)
qquit

4. Optional: per-process/per-connection byte accounting (Linux)

Without this, ltop still works — CONNS shows TCP live rates and PROCS shows network totals from socket sampling; what is missing is exact UDP per-process accounting and per-connection totals. One command enables it:

sudo cp target/release/ltop-bpf /usr/local/bin/      # from a release tarball or source build
sudo cp deploy/ltop-bpf.service /etc/systemd/system/
sudo systemctl enable --now ltop-bpf

A Homebrew install ships the same binaries; deploy the helper from the same release the TUI came from (see eBPF accounting and the upgrade note).

5. Optional: the AI workflow

The one command to remember:

ltop watch --duration 10m --proc chrome   # record headlessly (no root, crash-safe);
                                         # prints the output path
ltop report <that path> --json            # report takes a single file

report prints exact window sums and peaks instead of sampled guesses — a 10-minute window costs ~1k tokens as JSON vs ~40k polled via --json. See AI agents.

6. Make it yours

  • Theme: m → theme cycles the 72 embedded btop themes; on Omarchy the omarchy entry follows the desktop. --theme <file> loads any btop theme file; --follow-theme re-colors a running ltop when the desktop theme changes. Details in Themes.
  • Language: lang = zh in ~/.config/ltop/config.conf switches all human output (TUI and CLI) to Chinese; JSON keys stay English.
  • Settings panel: m → settings writes ~/.config/ltop/config.conf (tick rate, log retention, sweep interval, sort defaults, …). See The data plane.

Installation

ltop ships as two binaries:

  • ltop — the TUI and the whole CLI surface (--json, watch, report, …). Runs unprivileged.
  • ltop-bpf — the optional privileged eBPF collector (Linux only). Not needed for ltop to be useful; see eBPF accounting.

Platforms: Linux and macOS on x86_64 and aarch64. Prebuilt Linux binaries target glibc 2.35+ (Ubuntu 22.04 LTS baseline); static musl builds are not provided.

Homebrew (macOS & Linux)

Prebuilt binaries via the project tap:

brew install uMaj35ty/ltop/ltop

Upgrades come from the same formula (brew upgrade ltop). The formula no longer ships the retired loli symlink; brew upgrade cleans it up automatically.

crates.io

cargo install ltop

Compiles from source with the stable Rust toolchain; installs both binaries to ~/.cargo/bin. Notes:

  • No clang needed. The eBPF object is normally built at compile time with the system clang — but when clang (or the bpf target) is unavailable the build succeeds with an empty object embedded: the TUI runs normally and only UDP per-process accounting is silently absent. ltop-bpf refuses to start with a clear message in that case.
  • To build the eBPF collector from source you need a clang with the bpf target (Arch’s default clang has it).

GitHub Releases

Tarballs for x86_64 and aarch64, Linux and macOS, per release. They contain both binaries and the systemd unit. Binaries are unsigned — on macOS, drop the quarantine attribute first:

xattr -c ltop-*-darwin.tar.gz

Linux layout after unpacking:

sudo cp ltop /usr/local/bin/
sudo cp ltop-bpf /usr/local/bin/          # optional, Linux only
sudo cp ltop-bpf.service /etc/systemd/system/
sudo systemctl enable --now ltop-bpf      # optional

AUR

ltop-bin — the package is built and waiting; publication is pending the AUR reopening account registration. This page will change when it lands.

Deploying / upgrading the eBPF helper

Re-deploy the helper together with the TUI — a stale ltop-bpf keeps writing its snapshot to the old path and per-process accounting silently zeroes:

sudo cp target/release/ltop-bpf /usr/local/bin/
sudo systemctl restart ltop-bpf

Verify

ltop --version          # TUI/CLI version
ltop --json | head -c 300    # a schema-v1 snapshot; "meta.udp_helper": true
                        # means the eBPF helper is live (Linux)
sudo ltop-bpf --once    # collector smoke test: sample once, print, exit

Building from source

git clone https://github.com/uMaj35ty/ltop
cd ltop
cargo build --release

# China mirror (same history and tags, Chinese-first README):
git clone https://atomgit.com/uMaj35ty/ltop
# artifacts in target/release/: ltop, ltop-bpf (Linux)

Requirements: Rust stable; on Linux, clang with the bpf target for the eBPF object (see above for what happens without it). The eBPF probes carry per-arch pt_regs register mappings for x86_64 and aarch64; no nightly toolchain is involved.

Tested per release in QEMU/KVM (open-box binaries, kprobe attach, systemd unit, silent degrade without the helper) — the matrix lives in Compatibility.

The TUI

Six boxes, one job each. Tab cycles three layouts — classic (charts left, tables right), wide (charts across the top, tables below), tall (one column) — and boxes toggle with 1–6, collapsing cleanly when hidden. z zooms the focused box full-screen; esc restores. space freezes the frame; bytes transferred while paused are back-filled on resume, so pausing never loses accounting.

The six boxes

1 — NET

Per-NIC real-time throughput as braille area charts (rx/tx with separate gradients), plus link state, speed, duplex, MTU and addresses. Cumulative traffic shows twice: since ltop started (resettable) and since the interface came up. n switches the chart mode; the NIC cycles with a click on the header.

2 — LAN

Same-subnet devices discovered automatically (how: LAN discovery): IP, MAC, mDNS hostname, interface; gateways marked. Each neighbour shows its live connection count, current rate and accumulated bytes — the numbers link into CONNS, so “how much is going to that box” is one glance, and one enter pins the neighbour and filters CONNS to that peer.

3 / 4 — DISK I/O and DISKS

Read/write rate charts (deduplicated across stacked devices — nvme0n1 and its dm-0(root) child are one sample, not two) beside the device list: capacity bars and live per-device rates, the fs type as a dim tail after each name. On macOS the list shows mounted volumes only: VMs and simulators attach their virtual disks as host-visible synthesized devices — often a dozen or more per machine — and the host cannot see anything about their internal capacity or usage, so those rows would be pure noise. On Linux a VM’s disks never appear as host block devices (they are plain files in a filesystem), so the device tree reflects real hardware and stays the full physical tree — disk → partition → dm with unmounted rows, where LUKS/LVM layering stays readable. d expands the mount list and aims the arrow/jump keys at the disks list; i switches the chart mode. An overflowing list gets a btop-style scrollbar in its right edge — click the track to page, drag the thumb to scroll, no focus needed (the wheel already worked this way).

5 — CONNS

Every socket on the system. TCP connections show true per-connection B/s and totals; UDP “connections” are eBPF-metered (Linux, via the eBPF helper) and get the same columns. Rows carry protocol tags (tcp/udp, lan for local-peers), and closed connections linger as grayed tombstone rows for 5 seconds (tombstone_ttl_ms configurable) so a finished transfer is still readable. f cycles the filter (all → lan → tcp → udp), o cycles sorts — including proc grouping, which folds same-name processes into an expandable group head (▸ firefox ×17 with the group Σ; enter on the head collapses/expands, search hits auto-expand).

6 — PROCS

Per-process session totals for network (TCP+UDP — short-lived connections are never missed by sampling, because eBPF counts bytes at the syscall) and disk I/O, plus live rates. Exited processes stay grayed out with their captured command line; s relaunches one, or enter opens the detail panel for a copy of the exact command. r cycles sorts (net-sum → net-rate → disk-sum → disk-rate → name). Exited ledgers are evicted after 30 minutes by default (proc_exit_retention_min, 0 = keep forever).

Focus, selection, detail

  • p / c / l single-focus PROCS / CONNS / LAN: the chosen box fills the screen’s attention (the others dim to stubs). esc clears.
  • Arrow-key selection follows its process/connection/neighbour across re-sorts and group collapse — the row you watch stays the row you watch.
  • enter on a conns/procs row opens the detail panel: processes show state, uptime, full captured command line, exe/cwd, RSS and a UDP breakdown; connections show protocol, owner, lifetime, totals and rates. Inside the panel: space/t pin-tracks the row (tracked rows stay on top), k kills, s relaunches, ↑↓ moves a field cursor and y copies the selected value to the clipboard via OSC 52 (works over SSH, no X11 dependency).
  • enter on a LAN row pins the neighbour (red highlight, stays on top) and filters CONNS to that peer; repeat to unpin, esc/f clear.

/ searches by name substring across processes and connections (Tab switches the target box, enter applies, esc clears). Matches also drive sorts — a filtered PROCS view is still sorted by your chosen mode.

Kill-guard rails

k kills the selected process (or closes the socket). Killing other users’ processes requires allow_global_kill = true in the config; the default denies it.

Monitoring log

L (or start with --log) records per-process ledgers to ~/.local/state/ltop/ltop-log-<ts>.jsonl at log_interval_ms (default 60 s), sharing the same schema-v1 snapshot format as watch; retention (log_retention_days, default 7) purges old files at startup. Replay and export: --replay [--csv OUT]. Details in The data plane.

Full key bindings

KeyAction
q / Ctrl-Cquit
spacepause/resume sampling (back-fill on resume)
/search (Tab switches box, enter applies, esc clears)
mmenu: themes / settings / reset / graphs / help / quit
Escclear focus & selection; close panels
1–6toggle boxes: net, lan, disk i/o, disks, conns, procs
Tablayout classic → wide → tall
p / c / lsingle-focus procs / conns / lan
rprocs sort cycle
f / oconns filter cycle / sort cycle
enter, ←→ on a group headcollapse / expand process group
dexpand/collapse disk mount tree; arrow/jump keys then target the disks list
elan sort: ip → hostname → mac → iface
n / inet / disk chart mode
↑↓ PgUp PgDn / wheelmove selection; PgUp/PgDn page by visible height; wheel scrolls the list under the cursor; click selects
disks scrollbarclick the track to page, drag the thumb to scroll — works without focus
enter on a lan rowpin neighbour + filter CONNS to that peer
enter on a conns/procs rowdetail panel (track t/space, kill k, relaunch s, copy y)
zzoom the focused box full-screen
Home/End/g/Gjump to first/last row
Ltoggle the monitoring log
sLAN sweep on/off (main screen; in detail panels s relaunches)
+/-refresh interval ±250 ms

Settings worth knowing (all in m → settings, persisted to ~/.config/ltop/config.conf): refresh tick_ms (default 2000), tombstone TTL, the recording toggle (same as the L key), log interval/retention, sweep interval, default sort/filter modes, theme, lang, proc_expand_default (groups expanded by default), proc_exit_retention_min, allow_global_kill (exposes the k key; default off), allow_global_log (exposes the L record hotkey; default off).

Themes

ltop reads btop-compatible theme files: any btop theme works as-is, and you can write your own — including a two-line file that fixes just the colours you cannot read on your terminal.

Where themes live

  • Built-in: 72 themes — 41 from the btop project’s official collection and 31 from Omarchy’s bundled themes — selectable from the theme menu (m → theme) or --theme <name> on the command line (see Acknowledgements).
  • Omarchy: if ~/.local/state/omarchy/current/theme/btop.theme exists, the menu also offers omarchy — selecting it follows the desktop theme and live-reloads when the desktop theme changes.
  • --follow-theme: picked up at startup is the snapshot; adding --follow-theme also re-colors a running ltop when the desktop theme changes. Off by default (it polls the theme file; opt in when you want the demo from the GIF above).
  • Custom: put a .theme file in ~/.config/ltop/themes/, or load any file directly:
ltop --theme ~/my-colors.theme

A theme loaded with --theme is pinned — it does not follow omarchy.

File format

Key–value pairs, one per line; # lines are comments. Colours accept #RRGGBB, short #RGB, a two-digit grayscale shorthand (#80 = mid grey), and — for main_bg only — an empty value meaning “terminal default” (transparent background, important for terminal-transparency users):

theme[main_fg] = "#c0caf5"
theme[inactive_fg] = "#565f89"

Acknowledgements

The built-in theme library stands on the work of others, and this project is grateful for it:

  • btop (aristocratos/btop) by Aristocratos — ltop’s theme file format is btop’s, and 41 of the embedded themes are converted from btop’s official collection. Thank you to Aristocratos and to every theme author in that collection.
  • Omarchy (dhh/omarchy) by DHH — 31 embedded themes come from Omarchy’s bundled collection. Thank you to DHH and the creators of those themes.

Any theme written for btop or Omarchy keeps working here — their work remains theirs, embedded with credit.

Variable reference

KeyControls
main_bgpopup/dialog background; leave empty for terminal default
main_fgbody text — table cells, detail values, help descriptions
inactive_fgdimmed text — labels, hints, secondary info, timestamps
hi_fghighlights: box borders, keybindings, group titles, badges
titlepopup/box titles
graph_textaccent: process names, UDP badge, emphasis
net_boxNET box border
proc_boxLAN box border (btop key name kept for compatibility)
mem_boxDISK box border (btop key name kept for compatibility)
download_start/mid/enddownload gradient: charts, rx rates, ESTAB badge
upload_start/mid/endupload gradient: charts, tx rates
used_start/mid/enddisk usage colours
temp_start/mid/endalert gradient

Gradients must define all three stops (start/mid/end); a gradient missing any stop is ignored and the built-in default stays.

Minimal example

Only override what you cannot read — everything else falls back to the currently selected built-in theme:

theme[main_fg] = "#e0e0e0"
theme[inactive_fg] = "#909090"

Save as ~/.config/ltop/themes/readable.theme, then pick readable from the theme menu.

Full example

The easiest full theme is copying a built-in btop theme and editing:

cp /usr/share/btop/themes/dracula.theme ~/.config/ltop/themes/my.theme

For reference, the shape of a complete file (Dracula palette):

theme[main_bg] = "#282a36"
theme[main_fg] = "#f8f8f2"
theme[title] = "#bd93f9"
theme[hi_fg] = "#8be9fd"
theme[inactive_fg] = "#6272a4"
theme[graph_text] = "#ff79c6"
theme[net_box] = "#bd93f9"
theme[proc_box] = "#ff79c6"
theme[mem_box] = "#8be9fd"
theme[download_start] = "#8be9fd"
theme[download_mid] = "#8be9fd"
theme[download_end] = "#57c7ff"
theme[upload_start] = "#ff79c6"
theme[upload_mid] = "#ff79c6"
theme[upload_end] = "#bd93f9"
theme[used_start] = "#50fa7b"
theme[used_mid] = "#f1fa8c"
theme[used_end] = "#ff5555"
theme[temp_start] = "#50fa7b"
theme[temp_mid] = "#f1fa8c"
theme[temp_end] = "#ff5555"

Known limitation

The LAN box’s MAC column is hidden on macOS regardless of theme — the system sanitizes it for non-Apple-signed binaries. See Compatibility.

LAN discovery

The LAN box answers “what is on my network” without a root, without nmap, and without leaving the TUI. Discovery is two mechanisms:

  1. Passive — the kernel’s neighbour (ARP/NDP) table is read on every refresh, so any device the machine has spoken to appears immediately, with whatever freshness the kernel still holds.
  2. Active UDP-knock sweep — a background thread walks the local subnet (derived from the interface address + prefix) and sends small UDP packets to candidate addresses. The packets themselves usually go unanswered, but the attempt forces the kernel to resolve each address via ARP, which makes the kernel report the neighbour — ltop never needs raw sockets or root. The sweep cadence is sweep_interval_s (default 60 s) and can be turned off (sweep = false) for quiet networks.

The two sources merge per (interface, IP). Hostnames resolve through a best-effort chain — mDNS reverse lookup → NetBIOS node status → reverse DNS — gateways are flagged, and macOS’s neighbour-table sanitization is worked around by probing kernel cache entries through the route socket — see Compatibility → macOS for what is and is not visible there. Real MAC addresses come from ltop lan-setup, a per-user launchd agent that rotates arp/ifconfig snapshots through Apple platform binaries (no root, no entitlements) — without it MACs show —.

What each neighbour shows

ColumnMeaning
IP / hostnameresolved address, mDNS name when available
MAChardware address (— on macOS unless ltop lan-setup is installed)
ifacewhich local NIC the neighbour is reachable through
Σ connslive connection count from CONNS to this peer
ratecurrent rx+tx to this peer
Σ bytesaccumulated bytes to this peer since ltop started

The traffic columns are the point: the LAN box and CONNS share the connection ledger, so each neighbour carries its own live slice of the traffic.

Interactions

  • e cycles the LAN sort (ip → hostname → mac → iface).
  • s toggles the background sweep on/off for the current session.
  • ↑↓ selects; the selection follows the neighbour across re-sorts and sweeps (a device that briefly vanishes from ARP does not lose your place).
  • enter pins the neighbour — it stays at the top with a red highlight — and simultaneously filters CONNS to that peer. This is the fast path for “what exactly is this device doing”: select it, press enter, read the per-connection breakdown. Press enter again to unpin; esc/f also clear the filter.
  • l single-focuses the LAN box; z zooms it full-screen (useful on dense subnets).

Boundaries by design

  • The subnet is derived from your own interface; ltop does not scan beyond the connected prefixes.
  • Devices that block ARP entirely (some firewalled hosts) appear only if the kernel has a cached entry from other traffic.
  • The sweep is UDP-to-nothing: no TCP connects, no port probing, no raw packets — it looks like ordinary (failed) delivery attempts to the OS.

eBPF accounting

Why it exists

Two hard limits in the usual sources:

  • netlink//proc offers no per-socket byte counters for UDP. TCP shows byte queues, UDP shows nothing usable per socket.
  • Per-socket TCP sampling loses short-lived connections. Anything that completes within one sampling tick is invisible — which is exactly the traffic you often want to catch (DNS, small requests, chatty helpers).

ltop-bpf solves both by counting bytes where they happen: kprobes on the send/recv syscalls (v4 and v6) accumulate payload bytes per pid and per socket inode in kernel maps. Both ledgers feed the same UI, so PROCS gets per-process totals that cannot miss short-lived connections, and CONNS can attribute bytes to individual UDP “connections” like it already does for TCP.

Architecture

ltop-bpf (root, systemd)                 ltop (unprivileged TUI)
  kprobes send/recv v4+v6                  reads /run/ltop/udp.json
  pid ledger ─┐                            every tick, diffs the snapshot
              ├─ /run/ltop/udp.json  ──►   (saturating per-instance diff)
  inode ledger┘   rewritten every second   merges deltas into its ledgers

The privileged collector and the unprivileged UI communicate through one world-readable snapshot file that is rewritten every second. The TUI never needs privileges, and the helper never needs to know about terminals.

Deploying

sudo cp ltop-bpf /usr/local/bin/
sudo cp ltop-bpf.service /etc/systemd/system/
sudo systemctl enable --now ltop-bpf
  • Smoke test: sudo ltop-bpf --once samples once, prints, exits; sudo bash scripts/udp-smoke.sh generates accountable UDP traffic and verifies the snapshot end-to-end; python3 scripts/snap-diff.py prints per-pid raw deltas.
  • Upgrades: re-deploy the helper together with the TUI (see the FAQ for why).
  • Building from source needs a clang with the bpf target; prebuilt tarballs carry a compiled-in object.

Keeping the data clean

Guard rails keep kernel counters honest over a long-running session:

  1. LRU maps with self-eviction. The pid and socket maps are BPF_MAP_TYPE_LRU_HASH (16 384 entries each): idle pids and closed sockets evict themselves, so a busy multi-thousand-process box cannot exhaust the maps.
  2. Per-instance identity + saturating diff. Every helper instance (guarded by a flock single-instance lock) stamps its snapshots with a unique id; the TUI re-baselines whenever the id changes and diffs with saturating arithmetic — pid/socket reuse or a daemon restart with a stale file can never produce negative or garbage deltas.
  3. CO-RE, no per-kernel builds. The single struct-coupled part (walking sk to the socket inode) uses CO-RE relocations resolved against the kernel BTF at load time. Kernels without BTF still work (Ubuntu 22.04’s baseline is verified) — field offsets simply resolve at load.

Probes detach automatically on exit — a crashed collector never leaves kprobes behind — and register reads pass a 16 MiB value gate so a wild len cannot poison the ledgers.

What the numbers mean

The eBPF ledgers count payload bytes seen at the syscall. The NET box counts interface bytes (driver-level, every packet). The two scopes differ by design — headers, retransmits, and LAN chatter the process never sent through a syscall all live only in the interface numbers — so PROCS totals being 10–40 % below the NET box is the expected shape, not a bug. See the FAQ entry for the exact breakdown.

When the helper is absent

ltop runs unprivileged by default and never requires the helper: without it the UDP per-process columns are simply absent (TCP still works from socket sampling) and meta.udp_helper reads false in --json. On macOS there is no eBPF and no helper at all — see Compatibility → macOS for the Apple-native accounting and its documented differences.

The data plane

Every display surface in ltop is backed by one serialized snapshot — schema v1, versioned with the binary so scripts and agents can rely on it. The same structs serialize into all of these:

SurfaceCommandShape
one-shot snapshotltop --jsonsingle JSON object (~8k tokens unfiltered)
field referenceltop --schemaversioned machine-readable field list
monitoring logL / --logJSONL, one snapshot per log_interval_ms (default 60 s)
headless captureltop watchJSONL, one snapshot per --interval (default 5 s)
window summaryltop reporthuman table, or one ~2 KB JSON object with --json
ltop --json      # structured snapshot (takes ~1.2 s: two sampling rounds
                 # so rate fields are populated)
ltop --schema    # the authoritative field list — versioned with the binary,
                 # never drifts from it

The snapshot covers five domains: meta (version, os, arch, udp_helper flag), net (per-interface rates and cumulative counters), procs (per-process network + disk accounting with UDP breakdown), conns (per-connection sockets), disk (capacity/throughput), and lan (neighbours). Semantics worth knowing are marked right in the output — e.g. macOS MAC sanitization (real values once ltop lan-setup is installed).

Monitoring log (TUI)

L in the TUI, or start with --log, records snapshots to ~/.local/state/ltop/ltop-log-<ts>.jsonl:

  • log_interval_ms (default 60 000) sets the cadence; log_tracked_only = true records only tracked processes.
  • log_retention_days (default 7) purges old files at startup and when toggled.

Headless watch

ltop watch --duration 10m --proc chrome   # full syntax in `ltop watch --help`
  • Stops on --duration (10s/5m/2h), a --stop sentinel file (consumed on sight), or SIGINT — which is graceful: the last snapshot lands in the file.
  • Output defaults to ~/.local/state/ltop/ltop-session-<ts>.jsonl, separate from the TUI monitoring log and exempt from its retention purge; its own --retention (default 7 days, 0 = keep forever) prunes at start.
  • Line-by-line appends are crash-safe; no root required.
  • --proc <name> focus mode records only matching processes and their connections — tracked by name, so a restart that changes the pid keeps the timeline continuous.
  • Write volume scales with the interval (1 s ≈ 8 KB/line ≈ 28 MB/h; the 5 s default is ~5–6 MB/h). --retention is the cleanup story.

Report

ltop report <file.jsonl> [--json]

Reads a watch capture or a TUI monitoring log (same schema) and produces the window summary: per-process window sums (window differencing across pid restarts), peak rates, active time, last alive/exited state; per-connection sums/peaks/lifetimes keyed by inode (vanished connections keep their last known totals); NIC-scope global totals and the peak interval.

Filters: --top N (default 5, by traffic), --proc (substring, or glob when it contains *), --fields net,udp,disk,conns, and --json for the machine-readable form. The AI workflow built on this lives in AI agents.

Legacy and debugging

  • ltop --dump — one human-readable sampling round to stdout (debugging; prefer --json for parsing, the dump truncates and misaligns values).
  • ltop --replay [--csv OUT] [--top N] — rebuilds session deltas from legacy session-* logs (v1, procs-only) and exports CSV. Current-format files belong to report; old ones are rejected with a pointer here.

Configuration

~/.config/ltop/config.conf is plain key = value, written by the in-app settings panel (m → settings) and safe to hand-edit (applies on restart):

KeyDefaultMeaning
langenUI/messages language; zh switches all human output to Chinese (JSON keys stay English)
layoutclassicstart layout (classic/wide/tall)
tick_ms1000refresh interval
graph_net / graph_diskhybrid / centereddefault chart style
boxesall onvisible boxes
log_interval_ms60000monitoring log cadence
log_retention_days7monitoring log purge age
log_tracked_onlyfalselog only tracked processes
sweep / sweep_interval_strue / 60LAN UDP-knock sweep on/off and cadence
tombstone_ttl_ms5000how long closed connections linger in CONNS
themeomarchytheme name (see Themes)
theme_live_followfalsere-color a running ltop on Omarchy theme change (same as --follow-theme)
proc_expand_defaultfalseCONNS process groups start expanded
proc_exit_retention_min30evict exited-process ledgers after N minutes (0 = forever)
conn_filter / conn_sort / proc_sort / lan_sortall / proc / net-sum / ipdefault list modes
allow_global_killfalseallow killing other users’ processes
net_graph_coupledfalsecoupled NET chart scaling: when one direction dwarfs the other, the small side renders at its true fraction of the chart height instead of auto-scaling to full height
net_graph_scale_ratio5trigger threshold for the above, in×(2–20); ratios below it keep normal auto-scaling

AI agents

ltop treats “the machine’s network/disk/LAN state” as data, not as screen scraping: one schema-versioned JSON snapshot feeds the TUI, the CLI, the logs, and the headless tools. This page is the working reference for using ltop from an agent; the same content ships as a ready-made agent skill in the repo at docs/skills/ltop-observe/SKILL.md (diagnostic recipes included).

One-shot questions: --json

ltop --json | jq '<query>'     # snapshot; ~1.2 s (two sampling rounds populate rates)
ltop --schema                  # versioned field reference, drifts never

A single filtered snapshot costs ~1.7k tokens — vs ~22k for the traditional shell-command combination (ss/lsof/df/arp output to parse) and ~8k unfiltered. For one-shot questions this is the right tool.

Strict CLI surface: unknown subcommands and typos (ltop repor) exit 1 with a clear message — nothing falls into the interactive TUI by accident, and JSON keys are always English regardless of lang.

Time windows: watch + report

For “watch this for 10 minutes, then report”, do not poll --json (~40k tokens per 10 minutes at 5 s cadence). Record once, summarize once:

ltop watch --duration 10m --proc chrome    # headless, crash-safe, no root
ltop report <path watch printed> --json    # report takes a single file

report --json returns ~2 KB with exact numbers — window sums (last snapshot cumulative − first, segmented across pid restarts), peak rates, active time — instead of sampled guesses. Measured on a live desktop: ~97 % fewer tokens than polling for the same information.

{"schema":1,"file":"…","host":"…",
 "window":{"start":…,"end":…,"snapshots":N,"interval_s":S},
 "totals":{"scope":"nic","nic_rx":…,"nic_tx":…,"peak_ts":…,"peak_rx_bps":…,"peak_tx_bps":…},
 "procs":[{"name":"chrome","net_recv":…,"net_sent":…,"peak_rx_bps":…,"peak_tx_bps":…,
           "udp_recv":…,"udp_sent":…,"peak_udp_bps":…,"disk_read":…,"disk_written":…,
           "peak_disk_bps":…,"active_s":…,"alive":true}],
 "conns":[{"remote":"1.2.3.4:443","proto":"tcp","recv":…,"sent":…,"peak_rx_bps":…,
           "peak_tx_bps":…,"duration_s":…,"state":"ESTAB","process":"chrome"}]}

--top N (default 5), --proc (substring or * glob) and --fields net,udp,disk,conns trim the output further.

Division of labor with jq

watch output and TUI monitoring logs are plain JSONL — anything report does not aggregate is a jq one-liner away (the files share the schema, and report reads both). report for window math, jq for arbitrary slices, --json for the current instant.

Reading the snapshot — the parts that get misread

  • meta.udp_helper: true means the Linux eBPF helper is live and UDP per-process accounting is complete; when false (or on macOS) UDP numbers are partial.
  • conns[].process is null for sockets owned by other users (Linux). Do not claim those connections are unrelated to any process — they are just not attributable to your uid.
  • procs[].disk_* covers only processes owned by the current user.
  • net.interfaces[].session_rx/tx = since ltop started (resettable); alive_rx/tx = since the interface came up.
  • Process totals are payload bytes; interface totals are NIC bytes — a 10–40 % gap is by design (why).

Recipes (from the bundled skill)

  • Network slow? sort net.interfaces[] by rx_bps+tx_bps; check operstate/speed_mbps; then the top conns[] on the busy interface — conns[].process names the eater (your user only).
  • Disk busy? disk.devices[] for throughput vs capacity, then procs[] sorted by disk rates for the writer.
  • LAN inventory? lan.neighbours[] — gateways flagged, mDNS hostnames, tracked marks pinned devices.
  • “Watch chrome for 10 minutes and report traffic” — the watch+report pair above, with --proc chrome on both commands.

Outlook

A ltop mcp subcommand (hand-written stdio JSON-RPC wrapping --json, watch+report and — later — multi-host fleet aggregation) is on the 0.3 roadmap; the JSON surfaces above are its intended substrate and are stable in schema v1 today.

Compatibility

Requirements

Rust stable for source builds; Linux or macOS on x86_64 / aarch64. Prebuilt Linux binaries baseline glibc 2.35 (Ubuntu 22.04 LTS). The eBPF accounting is Linux-only and needs a clang with the bpf target at build time; at runtime it needs nothing special — no BTF is required, no nightly toolchain, no kernel headers.

Tested environments

Release tarballs are verified per distribution in QEMU/KVM: open-box binary, eBPF probe attach (incl. kprobe), systemd unit, and the silent degrade path without the helper. ltop is developed daily on Omarchy (Arch), which doubles as the reference desktop.

EnvironmentKerneleBPF accountingNotes
Arch Linux (rolling)7.2.7✓ fullalso the dev machine (Omarchy desktop)
Ubuntu 24.04 LTS6.8✓ fullglibc 2.39
Ubuntu 22.04 LTS5.15✓ fullworks without BTF; glibc 2.35 baseline
Ubuntu 24.04 LTS (aarch64)6.8✓ fullQEMU aarch64; Pi-class hardware expected to match
Debian 136.12✓ fullglibc 2.41
Fedora 44 (Workstation live)6.19✓ fullSELinux enforcing: zero denials
macOS 27 (Apple Silicon, MacBook Air)darwin 27n/a (nettop path)verified on hardware; see macOS

Specialty kernels that trim kprobes/BTF (e.g. Ubuntu’s -kvm cloud kernel) are the one known trap: use the generic kernel there. That is a kernel flavour limitation, not an ltop limitation.

SELinux

Fedora (enforcing) runs both binaries and the systemd unit with zero denials — the helper attaches kprobes through the standard bpf syscall path and writes only its world-readable snapshot to /run/ltop/.

macOS

macOS has no eBPF; the same six boxes read Apple-native sources:

  • PROCS and CONNS poll nettop (per-process rows and per-socket flows, TCP and UDP in one spawn); CONNS attribution scans the caller’s own sockets via libproc — other users’ connections show as n/a.
  • DISK reads IOKit IOMedia statistics plus per-process rusage.
  • LAN parses arp -an and the default route — with a workaround for the platform’s neighbour-table sanitization (below).
  • ltop-bpf does not exist on macOS.

Documented differences from the Linux path:

  • Socket counters are cumulative per live socket, sampled: a transfer that completes within one sampling tick is not counted. (The eBPF path counts at the syscall and misses nothing.)
  • The system hides parts of the local network from binaries that are not signed by Apple — independent of the Local Network privacy toggle: the neighbour table enumerates empty, single-entry route queries answer with the MAC sanitized to the interface’s synthetic address, and getifaddrs byte counters read frozen (all cross-checked in the same second against Apple-signed tools). macOS 27 went further: even Apple-signed arp shelled out from an app comes back empty, and getifaddrs reports every interface MAC as 02:00:00:00:00:00 (access is now gated on the undocumented com.apple.developer.networking.topology-observation entitlement, by responsible-process attribution × platform signature). ltop routes around what it can: the NET box counts via netstat -ib, the LAN box rebuilds its neighbour list by probing the kernel cache entry-by-entry over the route socket, and ltop lan-setup installs a per-user launchd agent that rotates arp/ifconfig snapshots through Apple platform binaries — real MACs in the LAN and NET boxes, no root, no entitlements. Without it, MAC addresses show as —.
  • Bare-terminal framebuffer fonts may miss braille glyphs; rendering over SSH or in a proper terminal emulator shows them all.

Release channels recap

Installation has the details: Homebrew (macOS & Linux), crates.io (source), GitHub Releases tarballs (x86_64/aarch64), AUR ltop-bin pending registration reopening.

Known limitations

  • Connections of other users can only be attributed to the uid level (/proc/<pid>/fd is unreadable for them on Linux; n/a via libproc on macOS).
  • WiFi NICs expose no link speed from the kernel; the field stays empty.
  • CONNS TCP totals include the connection’s whole history (kernel semantics) — see the FAQ.
  • After an ltop-bpf restart the eBPF counters start from zero; the UI re-baselines automatically via snapshot instance IDs.
  • Config files: unknown keys and comments survive saves (0.2.10+), but a known key carrying a value this build doesn’t recognise (e.g. a sort name introduced by a newer version) falls back to the default and is rewritten on the next save.
  • On macOS only live sockets are counted (nettop semantics): a transfer completing within one sampling tick is missed.

Compared to other tools

ltop doesn’t try to replace btop or nethogs. It covers the slice they leave open: who talks to whom on this machine and this LAN, per process and per connection, with a machine-readable data plane.

btop — use both

btop owns the system overview: CPU, memory, sensors, every process. ltop borrows its visual language (braille charts, box grid, even the theme format) but only watches network, disk I/O and the LAN — and watches those deeper: per-process session totals that survive restarts, per-connection bytes for TCP and UDP, LAN neighbours with per-peer traffic, headless capture for later analysis.

The author runs btop and ltop side by side every day — btop for the system, ltop for the traffic — and recommends exactly that setup. Any btop theme you already use works in ltop as-is.

nethogs — per process, live only

nethogs prints a per-process bytes-per-second list (needs root for most of it) and forgets everything between refreshes. ltop keeps session ledgers: exited processes stay on screen with their totals, TCP and UDP are attributed exactly via eBPF, and you also get per-connection rows, disk I/O and the LAN dimension. If a live list is all you need and you have root, nethogs is smaller; the rest is ltop territory.

iftop — per pair, one interface

iftop shows bandwidth between address pairs on one interface. ltop’s CONNS box covers the same view with totals and rates per connection, adds the owner process, and links each LAN neighbour to its connections. iftop’s remaining advantage: it is preinstalled in more places.

The shell pipeline (ss / lsof / arp / df)

The comparison that matters for scripts and agents: five output formats to parse, root needed for half the answers, no per-socket UDP bytes anywhere, and no memory of the last hour. ltop --json answers in one schema-stable snapshot (~1.7k tokens filtered), and watch + report turn “what happened” into two commands with exact numbers — see AI agents.

FAQ

The rx and tx charts have the same shape

Not a bug — two effects stacking. Each chart scales to its own window peak (btop-style, so small movements stay readable), and during a download your uplink is almost entirely TCP ACKs, whose rate tracks the downlink’s packet rate one-to-one. The tx/rx ratio you’ll see is ~1/30 — exactly the expected ACK share (one ACK per ~2 segments, ~66 bytes per ~2900 bytes of data); the graph then blows that tiny waveform up to full height, so the two curves look like siblings. When the two directions differ this much, read the header numbers, switch the graph mode to Block (m → graphs), or turn on coupled scaling so the small side renders at its true fraction of the chart height: m → graphs → c (persist with net_graph_coupled = true; the trigger ratio is net_graph_scale_ratio, default 5×).

PROCS totals are lower than the NET box

By design, on every platform. The NET box counts interface bytes (driver level: every packet, including headers, retransmits and background chatter). PROCS counts payload bytes attributed to processes (eBPF at the syscall on Linux; live-socket accounting on macOS), and only for your own processes on some platforms. The gap is the sum of everything that is interface traffic but not your processes’ payload. See eBPF accounting → What the numbers mean.

CONNS totals include traffic from before ltop started

Also by design, and TCP-only: a TCP connection’s Σ comes from the kernel’s per-socket counters, which cover the connection’s whole life — including time before ltop launched. UDP Σ is session-accumulated by ltop from the moment the helper is live. That difference (plus headers) is part of why CONNS and PROCS totals don’t match each other either; traffic through a proxy is attributed to the proxy process.

Per-process accounting zeroed after an upgrade

A stale ltop-bpf keeps writing its snapshot to the old path while the new TUI diffs against a different file — the symptom is per-process numbers silently reading zero. Fix: always re-deploy the helper with the TUI:

sudo cp ltop-bpf /usr/local/bin/          # from the same release as the TUI
sudo systemctl restart ltop-bpf

UDP columns are missing / partial

On Linux this means the eBPF helper is not running — check meta.udp_helper in ltop --json and deploy it (no root needed for the TUI itself; TCP columns keep working from socket sampling without the helper). On macOS UDP per-process numbers come from sampled live sockets and transfers that complete within one tick are not counted — a documented platform difference, not a bug.

conns[].process is null for some connections

Those sockets belong to other users (Linux): attribution scans your own uid’s sockets. “null” means “not attributable to you”, not “unrelated to any process”.

CONNS has a group named “n/a” (uid:4294967295 in older versions)

macOS counterpart of the above: the unprivileged TUI can only attribute sockets of your own user (libproc, same semantics as reading your own /proc/<pid>/fd on Linux). Connections belonging to other users, system daemons or the kernel are visible as traffic but not attributable to a process, so they group under n/a — 0.2.12 and later; older builds printed the raw uid:4294967295 sentinel, which is the same bucket. This is a permission boundary, not missing data. To see the owners resolved, run sudo ltop once (root can enumerate every process and the group empties out); only do so if you are comfortable running a monitor as root.

One-shot --json takes ~1.2 s

Two sampling rounds run back-to-back so every rate field is populated from a real delta. For scripting, that latency buys you rates instead of counters-only; --dump skips it but truncates values — parse --json.

watch filled my disk

Write volume scales with --interval: 1 s ≈ 8 KB/line ≈ 28 MB/h; the 5 s default is ~5–6 MB/h. Captures default to --retention 7 days (purged at the next watch start; 0 keeps forever). Long-term recording is the monitoring log’s job (L / --log), which defaults to 60 s granularity and 7-day retention.

The loli command is gone

Retired in 0.2.4 — it was a leftover from the original localist top naming, and tarballs/brew/AUR no longer ship it. Make your own alias if you liked it (help follows the invoked name):

ln -s "$(command -v ltop)" ~/.local/bin/loli

AUR package?

ltop-bin is built and waiting for the AUR to reopen account registration. Until then: Homebrew, crates.io or GitHub Releases.

Missing braille glyphs (boxes render as ? or blank)

Your terminal font lacks Unicode braille. Use a proper terminal emulator fonts-and-all, or render over SSH — bare framebuffer consoles may miss the glyphs. On macOS this affects the built-in Terminal’s framebuffer rendering in particular.

Old kernels / cloud images

glibc 2.35+ and a kernel with kprobes are the runtime floor for the eBPF helper; the TUI itself runs on anything the binary links against. Ubuntu’s -kvm cloud kernel trims kprobes — use the generic kernel. Ubuntu 22.04’s 5.15 works without BTF (CO-RE resolves at load time).

Does ltop phone home?

No telemetry, ever. The only outbound activity is the LAN sweep: small UDP packets to your own subnet (default every 60 s, sweep = false to disable) that make the kernel resolve neighbours via ARP — no port probing, no raw sockets, no traffic beyond your connected prefixes.

How do I get the report as JSON for my agent/script?

ltop report <file.jsonl> --json

… and read AI agents — including why polling --json in a loop wastes ~40k tokens per 10 minutes versus ~1k for a report.

Security

This page describes what ltop touches on your system and network, what it refuses to do, and how the untrusted inputs it reads are handled. The operational policy (supported versions, how to report a vulnerability) is the repository’s SECURITY.md.

Privileges

  • The TUI runs unprivileged. Every data source is readable by any process: /proc, getifaddrs, PF_ROUTE/netlink dumps, ephemeral UDP sockets. Kill/relaunch actions are bounded by the kernel to your own uid.
  • ltop-bpf is the only privileged component and it is optional. It runs as a systemd service with CAP_BPF + CAP_PERFMON only (plus CAP_SYS_RESOURCE on kernels < 5.11), writes a single snapshot file under /run/ltop, holds no listening sockets and makes no network connections. The shipped unit applies a sandbox: NoNewPrivileges, ProtectSystem=strict (only /run/ltop writable), ProtectHome, PrivateTmp, kernel-interface protections and a capability bounding set without CAP_SYS_ADMIN.

Your data on disk

DataLocationMode
Monitoring log (L / --log)~/.local/state/ltop/0600
Watch capture~/.local/state/ltop/0600
Config~/.config/ltop/config.conf0644 (preferences only)
eBPF snapshot/run/ltop/udp.json0644, root-owned — world-readable by design

Session logs and captures hold connection endpoints, process names and hostnames, so they are created 0600 regardless of umask. The eBPF snapshot is world-readable because the unprivileged TUI reads it; on a shared host this means every local user can see per-process byte totals — factor that in before deploying the helper on multi-user machines.

ltop has no telemetry: no update checks, no analytics, nothing leaves your machine except the LAN probes below.

Network behavior

The LAN box actively queries your local network:

  • per-neighbour unicast mDNS, NetBIOS node-status and reverse DNS lookups (hostname resolution);
  • a configurable UDP “knock” sweep — one empty datagram to discard port 9 per subnet host, at most 1022 hosts per round, default every 60 s, toggleable in settings.

Everything is scoped to your LAN. Replies are untrusted input and handled accordingly: DNS/NBNS transaction IDs are randomized per query and validated together with the source address, all parsers are bounds-checked pure Rust, untrusted strings are sanitized before they reach any terminal output, and the eBPF snapshot reader caps file size.

Reporting a vulnerability

Please use GitHub Private Vulnerability Reporting on the repository (never a public issue for anything exploitable). See SECURITY.md for the full policy.

Contributing

Issues and PRs are welcome. This page collects the project’s working conventions so a first PR looks like the tenth one.

Setup

  • Rust (stable, current), plus clang with the BPF target on Linux — the eBPF object is compiled from bpf/net_bpf.c by build.rs at build time. macOS needs Xcode’s toolchain only.
  • cargo test must pass and cargo clippy --all-targets -- -D warnings must be clean — zero warnings is a hard gate, enforced by CI on Linux x86_64, Linux aarch64 and macOS.

Conventions that CI and review will hold you to

  • Platform-gated code. macOS-only FFI declarations and functions are #[cfg(target_os = "macos")] — ungated extern declarations pull link errors into the Linux build, and Linux clippy cannot see macOS-only lints, so platform-specific changes are verified on the matching target (CI’s test-macos/test-aarch64 jobs exist for exactly this).
  • Offset-style constants need receipts. Structure offsets (kinfo_proc, socket_fdinfo, rusage_info_v2, …) are pinned against the SDK header and verified on real hardware; note the source in a comment, and double-check the header rather than trusting second-hand values.
  • Untrusted input is sanitized. Strings from the LAN (mDNS/NBNS hostnames), local processes, config and external JSONL files never reach a terminal raw: the TUI goes through ratatui (control characters dropped), CLI output goes through sanitize_text. New output paths must do the same.
  • Tests are fixtures, not mocks of each other. Watch has end-to-end tests that consume real ltop watch output; replay ships both current- and legacy-format fixtures; UI tests assert on rendered buffers. When you fix a bug, pin it: a test that fails against the old code (mutation check) is part of the fix.
  • Bilingual UI. User-facing strings go through the tr dictionary in src/config.rs — add the English and Chinese entries together. Box titles and technical tokens stay English by design.
  • Docs follow code. User-visible changes update the mdBook (both languages), the README when the pitch changes, and CHANGELOG.md in the established style.

Pull requests

  • Branch from master; keep PRs focused (one behavior per PR).
  • The commit message convention is a dense summary line describing the what and the why (see git log).
  • CI must be green (test + clippy on all three CI targets). The maintainer handles releases: tag → signed tarballs → Homebrew tap → crates.io → docs site.

Security-sensitive changes

If your change touches the LAN parsers, the eBPF helper, file permissions or anything in Security, call it out in the PR description. The audit baseline lives in the repository’s history (0.2.9); keep the property you’re preserving stated explicitly — e.g. “LAN-supplied strings never reach a terminal unfiltered”.

Acknowledgements

ltop’s look borrows — with gratitude and credit — from two projects and the artists behind them:

  • btop (aristocratos/btop) by Aristocratos: the theme format is btop-compatible, and 41 of the built-in themes come from btop’s official collection;
  • Omarchy (dhh/omarchy) by DHH: 31 of the built-in themes come from its bundled collection.

Thank you to Aristocratos, DHH and the creators of every one of those themes — see Themes → Acknowledgements.