Configuration
This page is the complete reference for configuring the socktop client and agent. Every option listed here exists in the current release — if an option isn’t listed, it isn’t supported.
Client Configuration
Command-Line Options
socktop [--tls-ca CERT_PEM|-t CERT_PEM] [--verify-hostname] [--profile NAME|-P NAME]
[--save] [--demo] [--compact] [--metrics-interval-ms N]
[--processes-interval-ms N] [ws://HOST:PORT/ws]
| Option | Description |
|---|---|
--tls-ca <FILE>, -t <FILE> | Pin the agent’s TLS certificate (PEM). Auto-upgrades ws:// to wss://. See TLS Configuration |
--verify-hostname | Enable strict hostname/SAN verification instead of certificate pinning |
--profile <NAME>, -P <NAME> | Use (or create) a saved connection profile |
--save | Overwrite an existing profile without the interactive prompt |
--demo | Spin up a temporary local agent and connect to it |
--compact | Pin the compact layout (normally auto-selected when the window is small) |
--metrics-interval-ms <N> | Fast metrics polling interval (default: 500, clamped to ≥ 100) |
--processes-interval-ms <N> | Process list polling interval (default: 2000, clamped to ≥ 200) |
Note: there is no --token client flag. Authentication tokens are passed in the URL as a query parameter: socktop "ws://HOST:3000/ws?token=changeme". See Authentication Token.
Configuration Files
The client stores connection profiles in:
$XDG_CONFIG_HOME/socktop/profiles.json~/.config/socktop/profiles.jsonwhenXDG_CONFIG_HOMEis not set
See Connection Profiles for the file format.
Agent Configuration
The agent is configured with a small set of command-line flags and environment variables. There is no configuration file.
Command-Line Flags
| Flag | Description |
|---|---|
--port <PORT>, -p <PORT> | Port to listen on (default: 3000, or 8443 with TLS) |
--enableSSL | Enable TLS with an auto-generated self-signed certificate |
--version, -V | Print version and exit |
The agent always binds to 0.0.0.0 (all interfaces). To restrict access, use a firewall or an authentication token.
Environment Variables
Core settings:
| Variable | Description |
|---|---|
SOCKTOP_PORT | Port to listen on (same as --port) |
SOCKTOP_ENABLE_SSL | Set to 1 to enable TLS (same as --enableSSL) |
SOCKTOP_TOKEN | Require this authentication token from clients |
SOCKTOP_AGENT_GPU | Set to 0 to disable GPU metrics collection |
SOCKTOP_AGENT_TEMP | Set to 0 to disable CPU temperature collection |
SOCKTOP_AGENT_EXTRA_SANS | Comma-separated extra IPs/DNS names to include in the auto-generated TLS certificate |
Tuning (defaults are sensible; change only if you have a reason):
| Variable | Default | Description |
|---|---|---|
SOCKTOP_WORKER_THREADS | 2 | Tokio worker threads (1–16). The agent is I/O-bound; 2 is enough for typical use |
SOCKTOP_AGENT_METRICS_TTL_MS | 250 | How long a collected metrics snapshot is served from cache |
SOCKTOP_AGENT_DISKS_TTL_MS | 1000 | Disk snapshot cache lifetime |
SOCKTOP_AGENT_PROCESSES_TTL_MS | 1500 | Process list cache lifetime (Linux) |
SOCKTOP_AGENT_NAME_CACHE_CLEANUP_THRESHOLD | 1000 | Process-name cache sweep threshold (non-Linux) |
The TTL caches mean multiple clients polling the same agent share collection work instead of multiplying it.
Configuring the systemd Service
The service unit (installed by the APT package at /etc/systemd/system/ or from docs/socktop-agent.service) sets options on the ExecStart line and via Environment= entries. To change them without editing the packaged unit, use a drop-in:
sudo systemctl edit socktop-agent
[Service]
Environment=SOCKTOP_TOKEN=changeme
Environment=SOCKTOP_AGENT_GPU=0
Then:
sudo systemctl daemon-reload
sudo systemctl restart socktop-agent
To change the port or enable TLS, override ExecStart (it must be cleared first in a drop-in):
[Service]
ExecStart=
ExecStart=/usr/bin/socktop_agent --enableSSL --port 8443
See Agent Service Setup for the full service walkthrough.