aaran/pinglume
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
Pinglume — Rust network health monitoring with a central controller and lightweight agents.
8 commits 1 branch 0 tags 534 KiB
  • Rust 83.8%
  • CSS 14.4%
  • Dockerfile 0.7%
  • Shell 0.6%
  • Python 0.5%
Find a file
Exact
AaranCloud db2fa5894f Remove private deployment defaults and use operator configuration
2026-10-05 11:52:57 +01:00
crates Refine monitoring charts and paired speed readouts 2026-10-03 15:10:18 +01:00
deploy Separate deployment modes and add guided agent enrollment 2026-10-02 17:06:17 +01:00
docs Remove private deployment defaults and use operator configuration 2026-10-05 11:52:57 +01:00
.dockerignore Separate deployment modes and add guided agent enrollment 2026-10-02 17:06:17 +01:00
.gitattributes Build Pinglume Rust monitoring controller, agent and dashboard 2026-10-02 15:40:18 +01:00
.gitignore Remove private deployment defaults and use operator configuration 2026-10-05 11:52:57 +01:00
Cargo.lock Build Pinglume Rust monitoring controller, agent and dashboard 2026-10-02 15:40:18 +01:00
Cargo.toml Build Pinglume Rust monitoring controller, agent and dashboard 2026-10-02 15:40:18 +01:00
PRIVACY.md Remove private deployment defaults and use operator configuration 2026-10-05 11:52:57 +01:00
README.md Remove private deployment defaults and use operator configuration 2026-10-05 11:52:57 +01:00
rust-toolchain.toml Build Pinglume Rust monitoring controller, agent and dashboard 2026-10-02 15:40:18 +01:00

README.md

Pinglume

A self-hosted network health monitor written in Rust. Track latency, jitter, failed probes and outages across your own networks, then run a bounded throughput check when you need one.

Source repository: aaran/pinglume.

How it fits together

Self-hosted: run the controller and agent together for standalone use, or manage agents at several sites from your own controller. Cloud mode: run a central service and install headless agents from its dashboard. Agents continue collecting into a bounded local queue when the controller cannot be reached. See deployment modes for the differences and remaining hosted-service work.

  • Rust/Axum controller with SQLite storage and a Rust-rendered Maud web interface. No Node build or custom browser JavaScript.
  • Rust agent with IPv4/IPv6 ICMP, TCP connection, DNS lookup and HTTP(S) response probes.
  • Per-target latency and failure measurements, persisted configuration, and retryable batch delivery.
  • Authenticated manual or scheduled jobs for bounded download/upload measurements. Schedules are off until enabled.
  • Optional per-agent Speedtest.net and iperf3 jobs, endpoint rotation, schedules and paginated result history. See speed test setup for external tools and provider terms.
  • External speed results appear directly on Overview and Measurements, with provider/server context, latest-run status and paginated history alongside continuous probes.
  • Local accounts and workspace-scoped agent enrollment. Each agent has its own revocable token.
  • Guided installation with expiring, single-use enrollment codes, downloadable Linux amd64 and Docker agents, and recoverable CLI enrollment. Fleet names and locations can be edited without replacing credentials.
  • Target summaries with protocol/scope filters, paginated individual results, and chart point details on hover or keyboard focus.
  • Personal profiles and saved time-range, pagination and refresh preferences. Workspace owners can set enrollment defaults, incident thresholds and member access.

This is an initial implementation. The feature map separates the current core from planned capabilities. It is not an Orb client, and Pinglume's health summaries are not Orb scores.

Run it

Start with the deployment guide. It covers:

  1. Building the controller and agent from the locked Rust workspace.
  2. Bootstrapping the first owner with a password file.
  3. Signing in and enrolling an agent through the web interface.
  4. Running either systemd services or Docker Compose profiles.

Enrollment is explicit. Starting the controller does not automatically enroll a local agent. Open Install agent, create a short-lived code, then follow the commands on the target machine; the CLI saves its protected configuration. Advanced manual configuration remains available in self-hosted mode.

The Docker builder pins Rust 1.99.0, released on 1 October 2026. Runtime images and systemd services run without root; only the agent receives the raw-socket capability needed for ICMP.

Read measurements correctly

  • ICMP loss is different from a DNS lookup, TCP connection or HTTP request failing. The target type stays attached to every sample.
  • P95 over a few probe attempts is a small-sample statistic, not a full traffic latency distribution.
  • A missing IPv6 route or raw-socket permission can fail a target without proving the entire internet connection is down.
  • Native controller-path throughput measures the path between the agent and its controller. A standalone controller on the same host measures a local path; it does not establish broadband speed. Optional Speedtest.net and iperf3 jobs use their separately selected endpoints.
  • Native controller jobs transfer at most 256 MiB per direction. External provider jobs use time limits instead and can consume much more data. None guarantees maximum multi-gigabit line rate; the agent's NIC, CPU and route still matter.

Use valid HTTPS when credentials or measurements leave the local host. This project does not install a certificate authority, open router ports, or discover your gateway automatically.

Documentation

There is no general redistribution license declared for this private project. Dependency licenses remain with their respective authors.