Speed Test¶

WireBuddy includes an integrated bandwidth speed test powered by librespeed-cli for measuring your server's download and upload performance.

Overview¶

The speed test provides:

• Download speed: Multi-stream download measurement in Mbit/s
• Upload speed: Multi-stream upload measurement in Mbit/s
• RTT latency: Round-trip time to server in milliseconds
• Jitter: Network stability measurement in milliseconds
• Automatic server selection: librespeed-cli picks the nearest server by ping RTT

How It Works¶

WireBuddy executes librespeed-cli --json as a subprocess and parses the structured JSON output. The CLI handles server selection, download/upload measurement, and latency probing internally.

Progress Phases (time-based estimation): 1. Server selection (10-30%) — Selecting nearest server by ping RTT 2. Download test (30-65%) — Multi-stream download measurement 3. Upload test (65-95%) — Multi-stream upload measurement 4. Complete (100%) — Results parsed and displayed

Note: Progress percentages are time-based estimates since librespeed-cli --json provides output only after completion. The actual test phases may complete faster or slower depending on network conditions.

Default Parameters¶

Server Selection¶

librespeed-cli automatically selects the LibreSpeed server with the lowest ping RTT from its public server list. This ensures measurements reflect realistic performance from the server's location.

Configuration¶

Enabling Speed Test¶

Navigate to: Settings → General → Speed Test

Server selection is automatic — no manual configuration needed.

Scheduled Tests¶

When enabled, WireBuddy runs a speed test automatically every night:

• Window: 02:00 – 04:00 local time
• Execution model: The scheduler waits for the nightly window and then runs the test if scheduled speed tests are enabled
• No peer gating: Active WireGuard peers do not block or defer the nightly run
• Cross-process lease: Concurrent runs are prevented so manual and scheduled tests do not overlap

If the scheduler reaches the nightly window while speed tests are enabled, the run is attempted regardless of current peer activity. Failed runs are still recorded so the UI can surface the failure instead of silently retrying on the next scheduler tick.

Running a Speed Test¶

Via Web UI¶

1. Navigate to Settings → General → Speed Test
2. Click Run Now
3. Watch time-based progress via SSE streaming:
4. Progress bar moves through estimated phases
5. Final results appear when test completes
6. Results are stored and available in the history chart

Via API¶

Trigger test:

curl -X POST https://vpn.example.com/api/wireguard/speedtest/run \
  -H "Authorization: Bearer YOUR_TOKEN"

Trigger test with streaming progress (SSE):

curl -N https://vpn.example.com/api/wireguard/speedtest/run/stream \
  -H "Authorization: Bearer YOUR_TOKEN"

SSE events:

event: progress
data: {"phase": "init", "progress": 0.0, "message": "Starting librespeed-cli…"}

event: progress
data: {"phase": "testing", "progress": 0.1, "message": "Running speed test…"}

event: result
data: {"status": "ok", "server": "Nuremberg, Germany (Hetzner)", "download_mbit": 248.5, "upload_mbit": 47.8, "rtt_ms": 23.1, "jitter_ms": 1.6}

Cooldown¶

A 30-second cooldown prevents rapid consecutive tests. Attempting to run during cooldown returns HTTP 429.

History & Storage¶

Viewing History¶

Navigate to: Dashboard → Speedtest chart

The dashboard speedtest chart includes:

• Time range filter: Select from 7d, 30d, 90d, 180d, or 1y
• Node filter: View results from Master or All Nodes
• Multi-node view: When "All Nodes" is selected, each node is shown with separate download (solid line) and upload (dashed line) series

Available time ranges:

Or via API:

curl https://vpn.example.com/api/wireguard/speedtest/history?range_key=7d \
  -H "Authorization: Bearer YOUR_TOKEN"

Time ranges: 6h, 24h, 7d, 30d, 90d, 180d, y1

Data Retention¶

Configure via the storage/retention API endpoint.

Storage Management¶

Get storage stats:

curl https://vpn.example.com/api/wireguard/speedtest/storage \
  -H "Authorization: Bearer YOUR_TOKEN"

Purge all data:

curl -X DELETE https://vpn.example.com/api/wireguard/speedtest/storage \
  -H "Authorization: Bearer YOUR_TOKEN"

Troubleshooting¶

"librespeed-cli not found"¶

Ensure librespeed-cli is installed:

apt-get install librespeed-cli

Or verify the binary is in $PATH:

which librespeed-cli

Low or inconsistent results¶

• Bufferbloat: Consumer routers often have poor QoS, causing variable results
• ISP throttling: Some ISPs throttle speedtest traffic
• Container networking: If running in Docker, ensure the container has direct network access (host networking recommended)

Test fails with timeout¶

Check outbound HTTPS connectivity from the server. LibreSpeed servers use HTTPS (--secure flag).

API Reference¶