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

Quick Start

Installation Methods

socktop can be installed via APT (Debian/Ubuntu), Cargo, or built from source.

Debian/Ubuntu installation:

# Add the repository's GPG signing key
curl -fsSL https://jasonwitty.github.io/socktop/KEY.gpg | \
    sudo gpg --dearmor -o /usr/share/keyrings/socktop-archive-keyring.gpg

# Add the APT repository
echo "deb [signed-by=/usr/share/keyrings/socktop-archive-keyring.gpg] https://jasonwitty.github.io/socktop stable main" | \
    sudo tee /etc/apt/sources.list.d/socktop.list

# Install socktop and the agent
sudo apt install socktop socktop-agent

# Enable the agent service
sudo systemctl enable --now socktop-agent

Run socktop to monitor your local system or connect to remote agents.

Option 2: Cargo Installation

Install from crates.io:

# Install GPU support libraries (required)
sudo apt install libdrm-dev libdrm-amdgpu1

# Install the TUI client
cargo install socktop

# Install the agent
cargo install socktop-agent

# Run the agent manually or set up as a service (see Agent Service Setup)
socktop_agent

Demo Mode

Test socktop without setting up an agent:

# If you have socktop installed
socktop --demo

# Or just run socktop with no arguments and select 'demo' from the interactive menu
socktop

This spins up a temporary local agent on port 3231, connects to it, and stops when you quit (Ctrl-C or q).

Usage

# Quick demo (no agent setup needed)
socktop --demo

# Monitor your local system (requires agent running)
socktop

# Or connect to a remote agent
socktop ws://hostname:3000/ws

The TUI displays system metrics in real-time.

Interactive Profile Selection

If you run socktop with no arguments, you’ll see an interactive menu:

Select profile:
  1. prod
  2. dev-server
  3. demo
Enter number (or blank to abort):
  • Choose a numbered profile to connect to a saved server
  • Select demo to launch demo mode (always available)
  • Press Enter on blank to abort

Monitoring Remote Systems

To monitor a remote system:

  1. Install the agent on the target system (using APT or Cargo)
  2. Start the agent on the remote system: 
    # Via systemd (APT install)
sudo systemctl start socktop-agent

# Or manually
socktop_agent
  3. Connect from your client: 
    socktop ws://remote-hostname:3000/ws

Save frequently used connections as profiles. See Connection Profiles.