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

General Usage

Starting socktop

Demo Mode

Try socktop without any setup:

# Launch demo mode
socktop --demo

Starts a temporary local agent on port 3231, connects to it, and monitors your local system. The agent stops when you quit (you’ll see “Stopped demo agent on port 3231”). Demo mode needs the socktop_agent binary on your PATH; if it’s missing, socktop explains how to install it.

Interactive Mode

Run socktop with no arguments to see an interactive profile menu (if you have saved profiles):

Select profile:
  1. prod
  2. dev-server
  3. demo
Enter number (or blank to abort):

Select a number to connect, or choose demo (always available). Press Enter on blank to abort.

Monitor a Remote System

Connect to a remote agent by specifying the WebSocket URL (note the /ws path):

socktop ws://hostname:3000/ws
socktop ws://192.168.1.100:3000/ws
socktop --tls-ca /path/to/cert.pem wss://secure-host:8443/ws  # With TLS

Using Connection Profiles

For frequently monitored systems, use profiles:

# Use a saved profile
socktop -P production-server
socktop --profile rpi-cluster-01

Running socktop with no arguments lists your saved profiles interactively. See Connection Profiles.

Finding Processes

Press / to enter filter mode:

Filter: pyth_

This shows only processes matching “pyth” (fuzzy, case-insensitive). Press Esc to cancel or Enter to apply; c clears an applied filter.

Select a process with ↑/↓ and press Enter to open the details view (command line, working directory, per-thread CPU, journal entries, and more).

Killing a Process

With a process selected in the list (or from inside Process Details), press t to terminate it. A confirmation dialog offers two actions, btop-style:

  • Terminate - sends SIGTERM, letting the process shut down cleanly
  • Force kill - sends SIGKILL

Things to know:

  • Local agents only. The signal is sent by the socktop client itself, with its own privileges — it is never sent over the wire. When you’re connected to a remote agent, the option doesn’t appear, and an agent can never be instructed to kill anything remotely.
  • Your privileges apply. You can only kill processes your user could kill from the shell.
  • PID-reuse guard. If the PID has been recycled to a different process between confirmation and signal time, nothing is sent.
  • Killed rows leave the list once the process actually exits.
  • Requires agent and client 1.60 or newer together on the machine where you use it — older agents keep reporting dead processes, so killed rows would linger on screen.

Compact Layout

On small terminal windows, socktop automatically switches to a compact layout: the Disks pane is dropped, Memory/Swap sit side by side, and GPU collapses to a single line — keeping the CPU graph and per-core bars visible. Pass --compact to pin this layout regardless of window size.

Command Line Options

socktop [--tls-ca CERT_PEM|-t CERT_PEM] [--verify-hostname] [--profile NAME|-P NAME]
        [--save] [--demo] [--compact] [--metrics-interval-ms N]
        [--processes-interval-ms N] [ws://HOST:PORT/ws]

See Configuration for the full option reference, and Keyboard and Mouse Controls for all key bindings.

Examples

# Connect with custom intervals
socktop --metrics-interval-ms 750 --processes-interval-ms 3000 ws://server:3000/ws

# Connect with an authentication token (query parameter, quoted)
socktop "ws://server:3000/ws?token=mySecretToken"

# Connect with TLS, pinning the agent's certificate
socktop --tls-ca /path/to/cert.pem wss://server:8443/ws

# Connect with TLS and strict hostname verification
socktop --tls-ca /path/to/cert.pem --verify-hostname wss://server:8443/ws

# Pin the compact layout
socktop --compact -P rpi-cluster-01