Connection Profiles

Connection profiles allow you to save frequently used agent connections for quick access.

What are Connection Profiles?

Instead of typing the full WebSocket URL every time:

socktop ws://production-server.example.com:3000

You can save it as a profile and use:

socktop -P production

Profile Configuration File

Profiles are stored in ~/.config/socktop/profiles.json (or $XDG_CONFIG_HOME/socktop/profiles.json).

Basic Profile Format

{
  "profiles": {
    "production": {
      "url": "ws://production-server:3000/ws"
    },
    "dev": {
      "url": "ws://dev-server:3000/ws"
    },
    "rpi": {
      "url": "ws://192.168.1.100:3000/ws"
    }
  },
  "version": 0
}

Profile with Authentication

{
  "profiles": {
    "secure-server": {
      "url": "wss://secure.example.com:3000/ws?token=your-secret-token-here"
    }
  },
  "version": 0
}

Note: Tokens are passed as query parameters in the URL.

Profile with TLS Configuration

{
  "profiles": {
    "tls-server": {
      "url": "wss://tls-server.example.com:8443/ws",
      "tls_ca": "/path/to/cert.pem"
    }
  },
  "version": 0
}

Profile with All Options

{
  "profiles": {
    "full-config": {
      "url": "wss://example.com:8443/ws?token=secret-token",
      "tls_ca": "/etc/socktop/cert.pem",
      "metrics_interval_ms": 750,
      "processes_interval_ms": 3000
    }
  },
  "version": 0
}

Note: Custom intervals are optional. Values below 100ms (metrics) or 200ms (processes) are clamped.

Creating Profiles

Method 1: Manual Creation

Create or edit the profiles file:

mkdir -p ~/.config/socktop
nano ~/.config/socktop/profiles.json

Add your profiles:

{
  "profiles": {
    "homelab": {
      "url": "ws://192.168.1.50:3000/ws"
    },
    "cloud-server": {
      "url": "wss://cloud.example.com:8443/ws?token=abc123xyz",
      "tls_ca": "/home/user/.config/socktop/cloud-cert.pem"
    }
  },
  "version": 0
}

Method 2: Automatic Profile Creation

When you specify a new --profile/-P name with a URL (and optional --tls-ca), it’s saved automatically:

# First connection creates and saves the profile
socktop --profile prod ws://prod-host:3000/ws

# With TLS pinning
socktop --profile prod-tls --tls-ca /path/to/cert.pem wss://prod-host:8443/ws

# With custom intervals
socktop --profile fast --metrics-interval-ms 250 --processes-interval-ms 1000 ws://host:3000/ws

To overwrite an existing profile without prompt, use --save:

socktop --profile prod --save ws://new-host:3000/ws

Using Profiles

Basic Usage

# Use a saved profile
socktop -P production
socktop --profile homelab