Távlink Server Reporter

A lightweight agent that collects CPU, memory, and network metrics from a Linux server (Ubuntu/Mint) and pushes them to the Távlink telemetry ingestion API.

The service self-registers using a provisioning token — no manual device setup needed.

Reported Metrics

Metric	Slug (default)	Unit
CPU usage	cpu_usage	%
Memory usage	memory_usage	%
Network incoming	network_in	kB/s
Network outgoing	network_out	kB/s

Prerequisites

• Python 3.10+
• Ubuntu / Linux Mint (or any systemd-based Linux)
• A provisioning token created in the Távlink UI

Quick Start

# 1. Clone / copy the project
cd /opt/tavlink-server-reporter   # or wherever you place it

# 2. Create a virtual environment & install deps
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Configure
cp .env.example .env
# Set PROVISION_TOKEN (required for first run)
# Adjust URLs and interval as needed
nano .env

# 4. Run
python server_reporter.py

On the first run the service will:

1. Call POST /provisioning/register on the core API with the provisioning token
2. Receive a permanent API key and device ID
3. Store them in credentials.json (chmod 600)
4. Begin reporting metrics to the ingestion API

Subsequent runs will load the stored credentials — the provisioning token is no longer needed.

Press Ctrl+C to stop.

Configuration (.env)

Variable	Default	Description
TAVLINK_INGESTION_URL	https://prototype-ingest.tavlink.net	Ingestion server base URL
TAVLINK_CORE_URL	http://localhost:8267	Core API base URL (provisioning only)
PROVISION_TOKEN	(empty)	One-time provisioning token from Távlink UI
DEVICE_NAME	(hostname)	Human-readable device name
METRIC_CPU	cpu_usage	CPU metric slug
METRIC_MEMORY	memory_usage	Memory metric slug
METRIC_NET_IN	network_in	Network incoming metric slug
METRIC_NET_OUT	network_out	Network outgoing metric slug
INTERVAL	10	Seconds between reports

Running as a systemd Service

# Copy files to /opt (or adjust paths in the service file)
sudo cp -r . /opt/tavlink-server-reporter
sudo cp tavlink-server-reporter.service /etc/systemd/system/

# Create venv and install deps
cd /opt/tavlink-server-reporter
sudo python3 -m venv .venv
sudo .venv/bin/pip install -r requirements.txt

# Configure
sudo cp .env.example .env
sudo nano .env   # set PROVISION_TOKEN, URLs, etc.

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable tavlink-server-reporter
sudo systemctl start tavlink-server-reporter

# Check status
sudo systemctl status tavlink-server-reporter
sudo journalctl -u tavlink-server-reporter -f

Credential Storage

After successful provisioning, credentials are saved to credentials.json in the project directory (permissions 0600). This file contains the permanent API key — do not commit it to version control (it is already in .gitignore).

To re-provision (e.g. new device), delete credentials.json and set a new PROVISION_TOKEN in .env.