Agent Service Setup

APT Installation

If you installed via APT, the service is already configured:

sudo systemctl enable --now socktop-agent

Cargo Installation

System-wide agent setup:

# If you installed with cargo, binaries are in ~/.cargo/bin
sudo install -o root -g root -m 0755 "$HOME/.cargo/bin/socktop_agent" /usr/local/bin/socktop_agent

# Install and enable the systemd service (example unit in docs/)
sudo install -o root -g root -m 0644 docs/socktop-agent.service /etc/systemd/system/socktop-agent.service
sudo systemctl daemon-reload
sudo systemctl enable --now socktop-agent

Enable SSL

# Stop service
sudo systemctl stop socktop-agent

# Edit service to append SSL option and port
sudo nano /etc/systemd/system/socktop-agent.service

# Change ExecStart line to:
# ExecStart=/usr/local/bin/socktop_agent --enableSSL --port 8443

# Reload
sudo systemctl daemon-reload

# Restart
sudo systemctl start socktop-agent

# Check logs for certificate location
sudo journalctl -u socktop-agent -f

# Example output:
# Aug 22 22:25:26 rpi-master socktop_agent[2913998]: socktop_agent: generated self-signed TLS certificate at /var/lib/socktop/.config/socktop_agent/tls/cert.pem

Configuration

Agent configuration via command-line flags or environment variables:

Port:

• Flag: --port 8080 or -p 8080
• Positional: socktop_agent 8080
• Env: SOCKTOP_PORT=8080

TLS (self-signed):

• Enable: --enableSSL
• Default TLS port: 8443 (override with --port/-p)
• Certificate/Key location (created on first TLS run):
  • Linux (XDG): $XDG_CONFIG_HOME/socktop_agent/tls/{cert.pem,key.pem} (defaults to ~/.config)
  • The agent prints these paths on creation

Auth token (optional): SOCKTOP_TOKEN=changeme

Disable GPU metrics: SOCKTOP_AGENT_GPU=0

Disable CPU temperature: SOCKTOP_AGENT_TEMP=0

Managing the Service

Basic Commands

# Start the service
sudo systemctl start socktop-agent

# Stop the service
sudo systemctl stop socktop-agent

# Restart the service
sudo systemctl restart socktop-agent

# Reload configuration (if supported)
sudo systemctl reload socktop-agent

# View service status
sudo systemctl status socktop-agent

# Enable auto-start on boot
sudo systemctl enable socktop-agent

# Disable auto-start on boot
sudo systemctl disable socktop-agent

# Enable and start in one command
sudo systemctl enable --now socktop-agent

Logs

# Follow live logs
sudo journalctl -u socktop-agent -f

# View recent logs
sudo journalctl -u socktop-agent -n 50

Status

# Check status
sudo systemctl status socktop-agent --no-pager

# Is the service running?
sudo systemctl is-active socktop-agent

Updating

# On the server running the agent
cargo install socktop_agent --force
sudo systemctl stop socktop-agent
sudo install -o root -g root -m 0755 "$HOME/.cargo/bin/socktop_agent" /usr/local/bin/socktop_agent
# If you changed the unit file:
# sudo install -o root -g root -m 0644 docs/socktop-agent.service /etc/systemd/system/socktop-agent.service
# sudo systemctl daemon-reload
sudo systemctl start socktop-agent
sudo systemctl status socktop-agent --no-pager

Tip: If only the binary changed, restart is enough. If the unit file changed, run sudo systemctl daemon-reload.