# Quick Start

## Installation Methods

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

## Option 1: APT Installation (Recommended for Debian/Ubuntu)

Debian/Ubuntu installation:

```bash
# 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

# Update the package list
sudo apt update

# 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:

```bash
# 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:

```bash
# 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

```bash
# 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:
   ```bash
   # Via systemd (APT install)
   sudo systemctl start socktop-agent
   
   # Or manually
   socktop_agent
   ```
3. **Connect from your client**:
   ```bash
   socktop ws://remote-hostname:3000/ws
   ```

Save frequently used connections as profiles. See [Connection Profiles](../usage/connection-profiles.md).
