self-hosted · MIT · websites, servers and OpenWrt routers
Websites, servers and OpenWrt routers in one self-hosted dashboard. Agents report out over HTTPS, so no monitored machine needs an open port, and a value nobody measured stays a dash, never a made-up zero.
The project's own instance, through our Cloudflare Worker
Waiting for the first answer…
Polled every minute; the worker caches answers for up to 5 minutes.
OpenWrt · Turris OS
One POSIX shell script, started by cron every minute. No resident daemon, no bash, no Python. It reads what the router already knows through ubus, /proc and /sys and sends it out over HTTPS.
Which sockets carry a link, at what negotiated speed, what each port and the device on the other end could do, and how many devices the bridge has learnt behind each one.
Enter the speed in your contract and the dashboard compares it with what the WAN link and the router’s own ports can carry, so a slow line and a router bottleneck look different.
Band, channel width, clients and signal per radio, and how busy the channel is from counters the driver already keeps. No scan of the air around you is started.
With a Huawei HiLink modem as the backup line, the agent reads its signal (RSRP, SINR, RSSI) and registration, so you know it works before you need it.
Router disks are read with smartctl at most once an hour, so a sleeping disk is not woken every minute.
Six actions (restart WAN, WireGuard or a service, reconnect PPPoE, renew DHCP, reboot) run only when enabled in the router’s own config, only with a valid HMAC signature, and never twice for one request.
Per-port device counts are sent, not identifiers. Hostnames and device IPs stay on the box too, unless you opt in to a named device list.
Agent 0.1.9 in the project’s busybox e2e harness, not on a physical router. On your router the agent reports the CPU time of its previous run, so the dashboard shows the real cost.How it is measured
What it watches
Each card says how far it is built. “Partial” and “Planned” mean exactly that.
HTTP(S) checks with an optional keyword in the page, TLS certificate expiry and TCP port checks. Minecraft, TeamSpeak and Discord servers too.
Agents for Linux (Bash or Python), Windows (PowerShell) and Docker: CPU, memory, disks and network, plus SMART on Linux.
Switch ports, WAN, Wi-Fi radios, LTE backup, SMART disks and opt-in signed remote actions, from one shell script.
Cron jobs and backups report in on their own. A Cloudflare Worker outside your server notices when the collector itself stops.
A public status page with incidents, planned maintenance, e-mail subscribers, SVG badges and an RSS feed.
E-mail, SMS (Twilio), WhatsApp (CallMeBot), Discord, Slack, Telegram, Pushover and PagerDuty, and a Prometheus exporter.
Two-factor sign-in (TOTP), OAuth with GitHub, Google, Discord or GitLab, and two roles: admin and user.
Checks run from your server. Add your own probe nodes (a PHP script for another host, or a Cloudflare Worker for websites) to confirm from elsewhere.
No native app yet. The dashboard at /app works in a phone browser.
Live proof
Both panels below talk to our Cloudflare Worker right now. When a request fails you see a dash or an error, never a stand-in number.
The nodes the public status API of bloodkings.eu returns.
Enter a public http(s) address. The worker requests it once and returns the HTTP status and the total round trip it measured. Redirects are reported, not followed; private and local addresses are refused.
No request sent yet. Nothing below is filled in until the worker answers.
Only the total time until the response arrived is measured, from wherever the worker runs at that moment. A worker cannot time DNS, TCP and TLS separately, so no such breakdown is shown.
How it works
PHP 8.2+ (the project’s CI runs 8.4) with MySQL or MariaDB, and cron running cron.php every minute. Shared hosting is enough; the server needs no container. The release ZIP carries the built /app dashboard, so only a build from source needs Node.js.
bloodkings-monitoring.zip from the latest release. Upload status/ and app/ to your hosting.
Create a database and its user in your hosting panel. Nothing to import.
Open /app/setup: it writes config.php, creates the tables and the first account.
Add the line the installer shows. It turns green at the first run.
Measured install time: 1 min (from the release ZIP to the first collector run on a clean PHP 8.2 and MySQL server, following this guide; uploading over FTP and clicking through your hosting panel come on top)
All seven steps on the download page →Add the machine in your app (Infrastructure → Add New Monitor) and run the commands it prints with your address and key, or register many machines with one token. The agent sends its report out over HTTPS; nothing on the machine listens for connections.
Connect the alert channels you use (Discord, Slack and Telegram can also be set per monitor), then share the public status page with incidents and maintenance notes.
Install an agent
Replace https://YOUR-DOMAIN with the address of your own server and YOUR_AGENT_KEY with the key of the monitor. Your app prints the same commands with both filled in.
Easiest from your own app: Infrastructure → Add New Monitor → OpenWrt Router or VPS Agent, then save. The dialog prints these steps with your address and the monitor’s key filled in. Below, https://YOUR-DOMAIN and YOUR_AGENT_KEY stand in for them.
A Bash agent. It reads the server address and its key from agent.cfg next to the script and reports over HTTPS; cron runs it every 5 minutes.
Install
Download the agent
mkdir -p /opt/bk-agent && wget -O /opt/bk-agent/agent.sh https://YOUR-DOMAIN/status/agent.sh && chmod +x /opt/bk-agent/agent.shCreate the config with the server address and key
cat > /opt/bk-agent/agent.cfg <<'EOF'
API_URL="https://YOUR-DOMAIN/status/agent_api.php"
AGENT_KEY="YOUR_AGENT_KEY"
AUTO_UPDATE="1"
EOFThe file must sit in the same folder as the script.
Run the agent by hand and check its output
/opt/bk-agent/agent.sh --verboseAdd the agent to cron, every five minutes
( crontab -l 2>/dev/null || true; echo '*/5 * * * * /opt/bk-agent/agent.sh >/dev/null 2>&1' ) | crontab -( crontab -l 2>/dev/null | grep -v /opt/bk-agent/agent.sh || true ) | crontab -
rm -rf /opt/bk-agentThen delete the agent’s monitor in the dashboard so its key stops working.
A POSIX sh script for OpenWrt and Turris OS, no bash or Python. It reads the server address and its key from agent_openwrt.cfg next to the script; cron starts it every minute and it exits after each run.
Install
Download the agent
wget -O /usr/bin/agent_openwrt.sh https://YOUR-DOMAIN/status/agent_openwrt.sh && chmod +x /usr/bin/agent_openwrt.shIf wget cannot do HTTPS, use uclient-fetch with the same arguments.
Create the config with the server address and key
cat > /usr/bin/agent_openwrt.cfg <<'EOF'
API_URL="https://YOUR-DOMAIN/status/agent_api.php"
AGENT_KEY="YOUR_AGENT_KEY"
AUTO_UPDATE="1"
EOFThe file must sit in the same folder as the script.
Run the agent by hand and check its output
/usr/bin/agent_openwrt.sh --verboseThe first run does not know the CPU load yet; the agent measures it on the next run.
Add the agent to cron, once a minute
mkdir -p "${HOME:-/root}/.cache/crontab" && ( crontab -l 2>/dev/null | grep -v agent_openwrt.sh || true; echo '* * * * * /usr/bin/agent_openwrt.sh >/dev/null 2>&1' ) | crontab -Check that the agent is scheduled and reporting
crontab -l | grep agent_openwrt.sh && sleep 70 && logread | grep -i agent | tail -5The first line must print the schedule entry. Within a minute the monitor in the app stops reporting a silent agent.
Optional: Wi-Fi 6E support of the clients
opkg update && opkg install hostapd-utilsWithout this package the agent cannot tell which clients support 6 GHz.
( crontab -l 2>/dev/null | grep -v agent_openwrt.sh || true ) | crontab -
rm -f /usr/bin/agent_openwrt.sh /usr/bin/agent_openwrt.sh.* /usr/bin/agent_openwrt.cfg /usr/bin/agent_openwrt.loglines-off
rm -rf /var/run/status-agent-openwrt /tmp/status-agent-openwrt*Then delete the agent’s monitor in the dashboard so its key stops working.
A PowerShell agent. It has no register command: put the agent key from the dashboard into agent.cfg, and the Task Scheduler runs it every 5 minutes.
Install
Download the agent
New-Item -ItemType Directory -Force C:\bloodkings | Out-Null; Invoke-WebRequest -Uri "https://YOUR-DOMAIN/status/agent.ps1" -OutFile C:\bloodkings\agent.ps1Create the config with the server address and key
Set-Content -Path C:\bloodkings\agent.cfg -Value @('API_URL="https://YOUR-DOMAIN/status/agent_api.php"', 'AGENT_KEY="YOUR_AGENT_KEY"', 'AUTO_UPDATE="1"')The file must sit in the same folder as the script.
Run the agent by hand and check its output
powershell.exe -ExecutionPolicy Bypass -File C:\bloodkings\agent.ps1 -VerboseSchedule a run every five minutes (PowerShell as administrator)
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument '-ExecutionPolicy Bypass -File "C:\bloodkings\agent.ps1"'
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes 5) -RepetitionDuration (New-TimeSpan -Days 3650)
Register-ScheduledTask -TaskName "BloodKingsAgent" -Action $action -Trigger $trigger -User "SYSTEM" -RunLevel HighestUnregister-ScheduledTask -TaskName "BloodKingsAgent" -Confirm:$false
Remove-Item -Recurse -Force C:\bloodkingsThen delete the agent’s monitor in the dashboard so its key stops working.
The Python agent in a python:3-alpine container. Fill in the agent key from the dashboard.
Install
Download the agent
mkdir -p /opt/bk-agent && cd /opt/bk-agent && wget -O agent.py https://YOUR-DOMAIN/status/agent.py && wget -O docker-compose.agent.yml https://YOUR-DOMAIN/status/docker-compose.agent.ymlFill the server address and key into docker-compose.agent.yml
sed -i 's|STATUS_API_URL: .*|STATUS_API_URL: "https://YOUR-DOMAIN/status/agent_api.php"|; s|STATUS_AGENT_KEY: .*|STATUS_AGENT_KEY: "YOUR_AGENT_KEY"|' docker-compose.agent.ymlStart the container
docker compose -f docker-compose.agent.yml up -dCheck the container output
docker compose -f docker-compose.agent.yml logs -fcd /opt/bk-agent && docker compose -f docker-compose.agent.yml down
rm -rf /opt/bk-agentThen delete the agent’s monitor in the dashboard so its key stops working.
The same Bash agent as on Linux.
Install
Download the agent
mkdir -p /opt/bk-agent && wget -O /opt/bk-agent/agent.sh https://YOUR-DOMAIN/status/agent.sh && chmod +x /opt/bk-agent/agent.shCreate the config with the server address and key
cat > /opt/bk-agent/agent.cfg <<'EOF'
API_URL="https://YOUR-DOMAIN/status/agent_api.php"
AGENT_KEY="YOUR_AGENT_KEY"
AUTO_UPDATE="1"
EOFThe file must sit in the same folder as the script.
Run the agent by hand and check its output
/opt/bk-agent/agent.sh --verboseAdd the agent to cron, every five minutes
( crontab -l 2>/dev/null || true; echo '*/5 * * * * /opt/bk-agent/agent.sh >/dev/null 2>&1' ) | crontab -( crontab -l 2>/dev/null | grep -v /opt/bk-agent/agent.sh || true ) | crontab -
rm -rf /opt/bk-agentThen delete the agent’s monitor in the dashboard so its key stops working.
Registering many machines with one token, and what to check when an agent does not show up: on the download page →
Honest scope
FAQ
Yes. It is MIT-licensed, there is no paid tier and no account with us. You run it on your own host.
A web host with PHP 8.2 or newer, MySQL or MariaDB, and cron to run cron.php every minute. Shared hosting works; the server needs no Docker. The release ZIP already carries the built /app dashboard; only a build from source needs Node.js.
No. Agents only make outbound HTTPS requests to your server. Remote actions, if you enable them, arrive in the answer to the agent’s own request.
It is started by cron once a minute and exits; nothing stays resident. In the project’s busybox test harness agent 0.1.9 makes about 182 forks per warm run. On your router it reports the CPU time of its previous run, so you see the real cost.
Only to the server you point the agents at. MAC addresses, hostnames and device IPs stay on the router; per-port counts are sent instead, unless you opt in to a named device list. This website loads nothing from third parties.
A dash means nobody measured it: the sensor or package is missing, the first sample is still warming up, or the data is stale. A zero would be a measurement, so the app never prints one it did not take.
Yes. The router agent is developed against a Turris Omnia, and the installer adds its cron line through crontab, which Turris OS (cronie) honours.
Yes. Website, TCP port and heartbeat checks need no agent at all, and there are agents for Linux, Windows and Docker.
Why it exists
It started with a Turris Omnia at home: the WAN on an SFP module, an LTE modem as the backup line and an mSATA disk. A plain uptime check could say whether the house was online, but not why it was slow or whether the backup would work.
So the agent learnt to read the router itself, and one rule stuck: if it was not measured, show a dash. The same rule runs through the dashboard, the status page and this website.