hotyue/IP-Sentinel: a Master-Agent system for VPS IP geolocation repair

What IP-Sentinel actually fixes, and who it is built for

The README states the project exists to solve VPS IPs being mislocated to mainland China or Hong Kong by databases such as Google's, a condition the project calls "送中". The stated fix is twofold: geographic signal anchoring, which ties the node to a real regional profile, and simulated local traffic, which the README describes as high-fidelity native traffic injection. The target user is someone running a fleet of VPS instances who wants the IP reputation to look like a normal residential or regional endpoint rather than a datacenter proxy.

The scope is wider than a single script. The README describes a Master-Agent distributed architecture: one Master node holds a SQLite database and a Telegram listener, while Agent nodes run a webhook daemon and a maintenance loop. That means the project is aimed at operators, not at someone who wants to run one command and forget it. If you have one VPS and no interest in a control plane, the architecture is heavier than the problem.

The Master-Agent split and the scheduling model

The repository layout confirms the split. master/ holds SQLite storage, the Telegram listener and webhook scheduling. core/ holds the edge sentinel: a webhook daemon, probes and what the README calls an atomic maintenance loop. install/ is a separate orchestration layer that handles environment detection, the interactive layer and firewall rules, and install.sh is described as a bootstrapper that calls into those modules with bash -c to avoid pipe contamination.

Scheduling is forced to UTC. The README states the whole stack takes over the underlying clock and that the fleet patrols at 20-minute intervals, 72 times a day. To avoid a thundering herd when many nodes start together, the README describes deployment-anchor staggering and randomized anti-concurrency sleep. The Master's SQLite database is set to WAL mode with a millisecond queue, which the README says is to avoid database is locked errors and Telegram 429 responses when many nodes are addressed at once.

Communication is signed. The README describes timestamp plus HMAC-SHA256 signatures with a 60-second command validity window, and unauthorized requests triggering a 403. That is a concrete design choice: it bounds replay windows but also means clock skew between Master and Agent will break command acceptance, and the README does not document a drift tolerance.

Installing IP-Sentinel and registering your first node

The README gives two modes. Mode A is a private Master plus Agents, which unlocks OTA remote upgrades. Mode B uses the official bot @OmniBeacon_bot and loses OTA, so nodes must be updated over SSH. The README warns against curl | bash and asks you to copy the full command instead.

For Mode A, deploy the Master on one VPS. The README notes it can share a machine with an Agent.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/hotyue/IP-Sentinel/main/master/install_master.sh)"

Then run the Agent installer on each machine you want to maintain, choosing the private Master during install and supplying your own bot Token and personal Chat ID.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/hotyue/IP-Sentinel/main/install.sh)"

After install, the README says your phone receives a #REGISTER# message. Forward it to your own bot to complete fleet registration. For Mode B, follow @OmniBeacon_bot, send /start, then run the same install.sh command and choose the official gateway.

Upgrades differ by mode. Private Masters get a top-menu button to upgrade the Master and a fleet-wide OTA hot reload, plus a per-node OTA option under the global radar view. Official-gateway or old nodes are updated by rerunning the same bash -c command over SSH; the README says the installer detects existing state and carries configuration forward. Uninstall is a separate script:

bash /opt/ip_sentinel/core/uninstall.sh

Firewall handling, probes and the data the project ships

The installer probes for UFW, Firewalld, iptables and ip6tables and opens or closes both IPv4 and IPv6 paths automatically, according to the README. That is convenient, but it also means an install can change host firewall state without you editing rules by hand. If your VPS has a firewall managed by a provider panel or a configuration management tool, expect the two to disagree.

The probe layer aggregates five fraud and abuse databases, including Scamalytics and AbuseIPDB, and reports proxy or VPN traits, port 25 status and streaming unlock state. The README also credits the xykt/IPQuality script for IP quality checks. Region and keyword data live under data/, with map.json as the region topology and data/regions/ split by country, state and city. A GitHub Actions pipeline regenerates fingerprints monthly and pulls regional search trends and RSS feeds daily, which is what feeds the simulated browsing behavior.

The README documents a Legacy branch for Debian 9 because the official APT sources are closed and the Python version is too old for the mainline. That branch is described as basic maintenance only, with no new features.

Where IP-Sentinel is the wrong tool

The most obvious limit is that it is not a privacy or anonymity tool. The README's own disclaimer says the project is for network research and personal VPS maintenance, and that users bear the risk of IP bans. Simulated traffic that looks like local browsing is exactly the pattern that some providers and anti-abuse systems flag, so using it on a host whose terms prohibit automated request generation is a direct conflict.

Second, the private mode requires you to hand a bot Token and Chat ID to the installer. The README does not document how those credentials are stored on disk, how they are rotated, or what happens if the bot is compromised. The HMAC signing protects command authenticity, but it does not protect a token that is already on the node.

Third, the scheduling model is rigid. The README states UTC is forced and patrols run every 20 minutes. If your workload needs the node idle at specific hours, or if your provider bills by traffic, there is no documented way to set a maintenance window. The README also does not document rollback for a failed OTA push, which matters because OTA is the headline feature of private mode.

How it differs from running IPQuality or a plain cron script

A common alternative is to run the xykt/IPQuality script manually or on a cron job. IPQuality is a checker: it queries reputation sources and prints a report, and IP-Sentinel credits it for that role. The difference in approach is that IP-Sentinel adds a persistent control plane and an active maintenance loop. IPQuality tells you the IP looks bad; IP-Sentinel tries to change the signal by generating regional traffic on a schedule and reporting through Telegram.

That distinction matters for adoption. If your only need is a periodic reputation report, a scheduled IPQuality run plus an alert is simpler and leaves no daemon on the host. If you need to correct many nodes and want one Telegram panel to see and command them, the Master-Agent design is the reason to pick IP-Sentinel. The README does not position the two as replacements, and the project depends on IPQuality for part of its own reporting.

Maintenance, licence and what an upgrade really costs

The last push to the repository was on 2026-08-26, and the most recent release listed is v4.3.5 on the same date. The repository is not archived. That is recent enough that the project is being changed, but the README does not describe a release cadence or a support window, so the practical maintenance cost is the cost of tracking a moving Master-Agent protocol.

The licence is AGPL-3.0. If you modify the code and expose it as a network service, the AGPL's source-availability condition is the part to read carefully; this article is not legal advice, and the LICENSE file in the repository is the authoritative text. For most users running the project unmodified on their own VPS, the licence mainly affects redistribution and forks. If you contribute a new region file under data/regions/ or a keyword list under data/keywords/, the README asks you to register the country, state and city in data/map.json so the installer can pick it up.

Upgrade cost splits by mode. Private Masters get one-click OTA for the Master and the fleet, which reduces work but concentrates risk in a single push with no documented rollback. Official-gateway and legacy nodes must be updated by rerunning the install command over SSH, which is more manual but easier to stage node by node.

Editorial conclusion

Adopt IP-Sentinel if you run several VPS nodes in regions where Google and fraud databases misplace your IP, and you already use Telegram daily. Do not adopt it if you cannot give up a bot token and Chat ID to a third-party bot, or if you expect a single script with no resident daemon. Before installing, verify that a Master and Agent can run on the same machine if you want the private mode, and read the AGPL-3.0 licence text before you fork the keyword or region data.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes