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”).

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 Remote System

Connect to a remote agent by specifying the WebSocket URL:

socktop ws://hostname:3000/ws
socktop ws://192.168.1.100:3000/ws
socktop 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 -P rpi-cluster-01

# List available profiles
socktop --list-profiles

See Connection Profiles.

Keyboard and Mouse

Keyboard

• Quit: q or Esc

Mouse (Processes pane)

• Click “CPU %” to sort by CPU descending
• Click “Mem” to sort by memory descending
• Mouse wheel: scroll
• Drag scrollbar: scroll
• Arrow/PageUp/PageDown/Home/End: scroll

Filtering Processes

Press / to enter filter mode:

Filter: pyth_

This will show only processes matching “pyth” (case-insensitive). Press ESC to clear filter.

Command Line Options

Client Options

socktop [OPTIONS] [URL]

OPTIONS:
  -P, --profile <PROFILE>              Use a connection profile
  -t, --token <TOKEN>                  Authentication token
  --tls-ca <FILE>                      CA certificate for TLS verification
  --verify-hostname                    Enable strict hostname verification for TLS
  --metrics-interval-ms <MS>           Fast metrics polling interval (default: 500)
  --processes-interval-ms <MS>         Process list polling interval (default: 2000)
  --list-profiles                      List available connection profiles
  -h, --help                           Show help information
  -V, --version                        Show version information

ARGUMENTS:
  [URL]                     WebSocket URL (e.g., ws://host:3000)

Examples

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

# Connect with authentication token
socktop ws://server:3000 -t mySecretToken

# Connect with TLS and custom CA
socktop wss://server:3000 --tls-ca /path/to/ca.pem

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