A lightweight network monitoring agent that reports metrics to the NetWatcher platform.
- MTR Checks - Traceroute analysis using NTrace-core
- Ping Tests - ICMP latency monitoring with pro-bing
- Traffic Simulation - Synthetic traffic using rPerf
- System Information - Host metrics and status
- Network Information - Interface and connectivity data
- Speedtests - Bandwidth testing (coming soon)
- Auto-Updates - Automatic version updates from GitHub releases
- Platforms: Linux, macOS, Windows
- Permissions: Root/Administrator (required for ICMP and raw sockets)
- NetWatcher Controller: Running instance of netwatcher-oss
# Download and run the installer curl -fsSL https://raw.githubusercontent.com/netwatcherio/agent/master/install.sh | sudo bash -s -- \ --workspace YOUR_WORKSPACE_ID \ --id YOUR_AGENT_ID \ --pin YOUR_AGENT_PIN# Download the installer Invoke-WebRequest -Uri "https://raw.githubusercontent.com/netwatcherio/agent/master/install.ps1" -OutFile "install.ps1" # Run the installer .\install.ps1 -Workspace YOUR_WORKSPACE_ID -Id YOUR_AGENT_ID -Pin "YOUR_AGENT_PIN"For self-hosted NetWatcher instances:
# Linux/macOS curl -fsSL https://raw.githubusercontent.com/netwatcherio/agent/master/install.sh | sudo bash -s -- \ --host your-controller.example.com \ --ssl true \ --workspace 1 \ --id 42 \ --pin 123456789# Windows .\install.ps1 -Host "your-controller.example.com" -SSL $true -Workspace 1 -Id 42 -Pin "123456789"The agent stores its configuration in config.conf:
| Parameter | Description |
|---|---|
CONTROLLER_HOST | Controller hostname (e.g., api.netwatcher.io) |
CONTROLLER_SSL | Use HTTPS/WSS (true or false) |
WORKSPACE_ID | Workspace ID |
AGENT_ID | Agent ID |
AGENT_PIN | Initial authentication PIN |
| Platform | Path |
|---|---|
| Linux/macOS | /opt/netwatcher-agent/config.conf |
| Windows | C:\Program Files\NetWatcher-Agent\config.conf |
sudo systemctl status netwatcher-agent # Check status sudo systemctl restart netwatcher-agent # Restart sudo journalctl -u netwatcher-agent -f # View logsGet-Service -Name NetWatcherAgent # Check status Restart-Service -Name NetWatcherAgent # Restart Get-EventLog -LogName Application -Source NetWatcherAgent -Newest 20 # View logs# Linux/macOS sudo ./install.sh --uninstall # Windows .\install.ps1 -UninstallIf the agent's auto-update fails (e.g., read-only /tmp, network issues), use the install script to manually update:
# Linux/macOS - Update binary only (preserves config/service) sudo ./install.sh --update # Update to a specific version sudo ./install.sh --update --version v20260114-abc123 # Windows .\install.ps1 -Update .\install.ps1 -Update -Version "v20260114-abc123"If the install script isn't available, manually replace the binary:
# 1. Stop the service sudo systemctl stop netwatcher-agent # 2. Download the latest release # Visit: https://github.com/netwatcherio/agent/releases/latest # Download the appropriate file for your platform (e.g., linux-amd64.zip) # 3. Extract and replace cd /opt/netwatcher-agent unzip ~/Downloads/netwatcher-*.zip -d /tmp/nw-update cp /tmp/nw-update/netwatcher-agent ./netwatcher-agent chmod +x ./netwatcher-agent # 4. Verify and restart ./netwatcher-agent --version sudo systemctl start netwatcher-agent| Issue | Solution |
|---|---|
| Auto-update fails with "read-only file system" | Updated agents create .tmp folder locally instead of using /tmp. Update manually with --update flag. |
| Service fails to start after update | Check logs: journalctl -u netwatcher-agent -n 50. Rollback if needed by restoring .backup file. |
| Agent not connecting to controller | Verify config.conf settings, check firewall, ensure controller is reachable. |
| "Unauthorized" errors | Re-bootstrap with correct PIN or generate new agent credentials in the dashboard. |
# Linux - Follow logs live sudo journalctl -u netwatcher-agent -f # Linux - Last 100 lines sudo journalctl -u netwatcher-agent -n 100 # Windows Get-EventLog -LogName Application -Source NetWatcherAgent -Newest 50git clone https://github.com/netwatcherio/agent cd agent go build -o netwatcher-agent