Authentication Token

The agent can require a shared token from connecting clients. Without the correct token, the WebSocket connection is rejected.

Access control - only clients that know the token can connect
Defense in depth - combine with TLS so the token isn’t sent in cleartext over untrusted networks

Agent: Setting the Token

The token is configured with the SOCKTOP_TOKEN environment variable. (There is no --token command-line flag.)

SOCKTOP_TOKEN=changeme socktop_agent --port 3000

Add the environment variable with a drop-in (works for both APT and manual installs):

sudo systemctl edit socktop-agent

[Service]
Environment=SOCKTOP_TOKEN=changeme

sudo systemctl daemon-reload
sudo systemctl restart socktop-agent

Alternatively, uncomment the # Environment=SOCKTOP_TOKEN=changeme line that ships in the packaged unit file.

The client passes the token as a token query parameter in the WebSocket URL. Quote the URL so your shell doesn’t interpret the ?:

socktop "ws://server:3000/ws?token=changeme"

# With TLS
socktop --tls-ca /path/to/cert.pem "wss://server:8443/ws?token=changeme"

Warning: the client’s -t flag is short for --tls-ca (a certificate path), not for the token.

Store the token as part of the profile URL (~/.config/socktop/profiles.json):

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

Then connect:

socktop -P secure-server

Note: the profiles file then contains the token in plaintext — keep its permissions restrictive.

openssl rand -base64 32

On untrusted networks, always combine the token with TLS; over plain ws:// the token is visible to anyone who can capture traffic.
Rotate the token by updating SOCKTOP_TOKEN on the agent, restarting the service, and updating client profiles.