Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Gatewatch

A self-hosted PAC gateway and availability monitor for selected domains.

License: MIT Python 3.9+ Dependencies: none Platform: Linux

Why Gatewatch · How it works · Features · Quick start · Commands · Security · Русский


Why Gatewatch

A conventional health check answers one question: "Is the proxy reachable?"

It usually does not answer the question that matters: "Will the user actually see the page they expect?"

A target can return HTTP 200, transfer hundreds of kilobytes, and still display an error page, redirect, login wall, or service-unavailable notice. Meanwhile, the proxy pool reports that the upstream is healthy and the monitoring dashboard stays green.

Gatewatch checks the result the way a browser user would see it:

$ gatewatch check
service-a     STUB  stub page (not available in your country)
service-b     OK    HTTP 200, 503000 bytes
exit          OK    relay leaves through the exit (198.51.100.4)

$ echo $?
1                       # HTTP 200 was received, but the result is a failure

Gatewatch is a small self-hosted tool for a home network: one PAC file, one relay, configurable targets, and automatic recovery when the selected upstream stops working. The story behind it, and the seven reasons a green check can be wrong, is in docs/WHY-200-LIES.md.

How it works

flowchart LR
    B["Browsers on the home network<br/>PAC: selected domains only"] -->|CONNECT| R["Gatewatch relay"]
    R -->|reads on change| E[("exit.json")]
    R -->|"HTTP or SOCKS5"| X["Configured upstream<br/>your VPS or a proxy from a pool"]
    X --> T["Target websites"]
    W["Gatewatch guard<br/>systemd timer"] --> C["check"]
    W --> F["prune · harvest · switch"]
    F --> E
  • The PAC file sends only the domains you configure to the Gatewatch relay.
  • The relay forwards those requests through the current upstream.
  • guard periodically runs a health check.
  • If a target fails, Gatewatch attempts recovery: it prunes bad nodes, switches upstreams, and optionally discovers new candidates.
  • If recovery fails, Gatewatch sends one state-change notification instead of repeating the same alert every few minutes.

All other traffic on the network is unaffected.

Features

Feature What it provides
Real-result checks check inspects the response text, not only the HTTP status code and response size. A stub page returned with HTTP 200 is treated as a failure.
Route verification Compares the IP visible through the relay with the IP visible through the selected upstream. This helps detect requests that silently leave through an unexpected route.
Loud failures An unavailable upstream returns HTTP 502 instead of silently falling back. The generated PAC does not include a hidden DIRECT fallback.
Step-by-step recovery guard prunes the pool, switches the upstream, forces a switch, and discovers new candidates. It rechecks the target after each step.
Hot upstream switching The current upstream is stored in a file and reloaded by the relay without a restart. A failed switch is rolled back.
Configurable targets Define any URL and the response phrases that should be treated as failure indicators, in any language.
One PAC for the network Configure it once for browsers and devices that support PAC files.
Minimal dependencies Python standard library and curl. The codebase is intentionally small and readable.
Offline tests 39 automated tests use local fake proxies and web servers to cover tunnels, authentication, ACLs, rollback, pool pruning, and notifications.
Operational tooling check --json, hardened systemd units, a Windows helper script, and a Proxmox guest helper.

Quick start

Requirements: Linux, Python 3.9+, and curl. Run the relay on an always-on machine in your home network: a mini PC, home server, NAS, or VM.

# 1. Install
git clone https://github.com/slevittt/gatewatch && cd gatewatch
sudo python3 -m venv /opt/gatewatch
sudo /opt/gatewatch/bin/pip install .
sudo ln -s /opt/gatewatch/bin/gatewatch /usr/local/bin/gatewatch

# 2. Create configuration
sudo useradd -r -s /usr/sbin/nologin gatewatch
sudo mkdir -p /etc/gatewatch
gatewatch init | sudo tee /etc/gatewatch/gatewatch.ini >/dev/null
sudoedit /etc/gatewatch/gatewatch.ini
#   [pac]      relay = 192.168.1.10:10813      (the relay as browsers will see it)
#              hosts = example.com             (the domains to route)
#   [targets]  example = https://example.com/  (what "working" means)

# 3. Install systemd services
sudo cp contrib/systemd/gatewatch-*.service contrib/systemd/gatewatch-guard.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now gatewatch-relay gatewatch-pac gatewatch-guard.timer

# 4. Configure an upstream (run as the service user so the relay can read the file)
# A trusted VPS or private proxy is the recommended setup.
sudo -u gatewatch gatewatch -c /etc/gatewatch/gatewatch.ini switch --set socks5://user:pass@your-server.example:1080

# 5. Point browsers at the PAC file:  http://<gatewatch-host-IP>:8094/gatewatch.pac
#    Windows (PowerShell, as administrator):
#      .\contrib\windows\Set-BrowserPac.ps1 -PacUrl http://<IP>:8094/gatewatch.pac
#    Proxmox VM (from the host):
#      contrib/proxmox/set-browser-pac-via-qga.sh <vmid> http://<IP>:8094/gatewatch.pac

# 6. Verify
gatewatch -c /etc/gatewatch/gatewatch.ini check

After configuration, fully close and reopen the browser. In Chrome, open chrome://policy and confirm that a ProxySettings policy is present.

Commands

Command Purpose
gatewatch check [--json] Check configured targets through the relay. Exit codes range from 0 to 3 (meaning).
gatewatch relay Start the HTTP CONNECT relay.
gatewatch guard [--loop N] Run checks, recovery, and notifications. Usually launched by a systemd timer.
gatewatch switch [--force] [--dry-run] Select a suitable upstream, verify it through the relay, and roll back on failure.
gatewatch switch --set URL Set an upstream manually: http:// or socks5://, optionally with credentials.
gatewatch prune [--dry-run] Remove unhealthy nodes from the pool.
gatewatch harvest [--add] Discover candidate nodes from configured public sources.
gatewatch pac / gatewatch pac-serve Print or serve the PAC file.
gatewatch init Print a default configuration template.
gatewatch status Show the current upstream and pool size.

Configuration

All settings live in one INI file. See examples/gatewatch.ini.

[relay]
allow = 127.0.0.1/32, 192.168.0.0/16

[targets]
# name = URL to check
my_service = https://example.com/

[check]
# A page smaller than this is not "the real page"
min_size = 1000
# Phrases that indicate a failure page, in any language
stub_phrases = not available in your country, access restricted

[pac]
# Relay address as seen by browsers
relay = 192.168.1.10:10813
# Domains routed through the relay
hosts = example.com, assets.example.com

[guard]
notify_cmd = sh -c 'echo "$GATEWATCH_BODY" | mail -s "$GATEWATCH_SUBJECT" you@example.com'

The [targets] section replaces the built-in default. You can monitor any web service for which you know the URL and the text or pattern that indicates a failure.

Security

For reliable operation, use a trusted VPS, home server, or other infrastructure you control as the upstream.

Public proxies may be useful for experiments, but treat them as untrusted:

  • They may log traffic, throttle it, or drop it. TLS protects content, not metadata.
  • Their availability, location, and behavior are unpredictable.
  • Do not use them for account logins, payments, work data, or other sensitive traffic.

The relay is a proxy: keep it inside your network, never forward its port to the internet, and keep [relay] allow as narrow as you can. See docs/SECURITY.md.

Project status

Gatewatch is in beta.

Area Status
Automated tests HTTP/SOCKS5 tunnels, authentication, hot reload, HTTP 502/503 handling, ACLs, stub detection, upstream switching with rollback, pool pruning, notification hysteresis, and PAC generation.
End-to-end checks The relay and check command are tested against local fake upstreams and web servers, including the real CLI as a subprocess.
Real deployment The failure modes in docs/WHY-200-LIES.md (causes 1-6) were diagnosed on the author's installation, and the guest-agent technique for the browser policy worked there. Cause 7 and the stale-tunnel note are suspected, not proven.
Not yet verified This release on a clean machine against external services, the Docker files, Python 3.9 in CI, Firefox, and relay operation on macOS or Windows.

A useful first issue report includes:

gatewatch -c /etc/gatewatch/gatewatch.ini check --json

Before sharing output, remove IP addresses, hostnames, credentials, cookies, tokens, and any other private information.

Roadmap

  • JavaScript-rendered failure-page detection using a headless browser.
  • Prometheus metrics endpoint.
  • Optional relay authentication.
  • Per-target upstream groups.
  • A tested official Docker image.

FAQ

Is Gatewatch a VPN?

No. Gatewatch is a small HTTP CONNECT relay plus a PAC file for selected domains. It does not route all traffic from a device or network.

Why not use a regular VPN client?

A VPN client is usually configured per device, routes all traffic through one tunnel, and may not detect when a particular website stops returning a usable result. Gatewatch is centralized, affects only selected domains, and validates the actual result.

Why PAC instead of a browser extension?

A PAC file can be configured once for multiple browsers and devices. Browser extensions operate within a profile and can conflict with system or organization-level proxy policies.

Can I use it with other services?

Yes. Add domains to [pac] hosts, a target URL to [targets], and failure indicators to [check] stub_phrases.

Why does the checker use curl?

curl supports HTTP and SOCKS5 proxies, performs a real TLS handshake, and makes it possible to validate the path as a client would see it without running a full browser.

Responsible use

Gatewatch is a general-purpose routing, monitoring, and recovery tool. What you route through it, and through which upstream, is your decision and your responsibility.

Proxy use may be restricted by a service's terms, network policy, or local law. Ensure that your use complies with applicable rules and regulations.

Public proxies are not trusted infrastructure. Do not use them for accounts, payments, work-related data, or other sensitive traffic.

Contributing and license

See CONTRIBUTING.md.

Gatewatch is released under the MIT License. See LICENSE.

If Gatewatch saved you an evening of debugging, consider giving the project a star.

Metadata

Release files for gatewatch 0.1.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gatewatch 0.1.0b1
File Size Uploaded Provenance Actions
gatewatch-0.1.0b1.tar.gz 29.6 kB With provenance Details for gatewatch-0.1.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gatewatch 0.1.0b1
File Interpreter ABI Platform Actions
gatewatch-0.1.0b1-py3-none-any.whl Python 3 none any Details for gatewatch-0.1.0b1-py3-none-any.whl

Total release size: 54.8 kB

Release files / gatewatch-0.1.0b1.tar.gz

Download URL gatewatch-0.1.0b1.tar.gz
Size 29.6 kB
Tags Source
SHA-256 checksum
How to use checksums
13f669489794e843e22e60fc4ed8e6fd7ca7cda1634e2faf025ac37419772be2
BLAKE2b-256 checksum
How to use checksums
00767212f7d7e1756a61c1e49d4fe5b0243c25f4b713c27c1afd701ed335887e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Release files / gatewatch-0.1.0b1-py3-none-any.whl

Download URL gatewatch-0.1.0b1-py3-none-any.whl
Size 25.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb95399a8cf09ce90758bff1c423ab45917f203470ab602796714285a9938e5f
BLAKE2b-256 checksum
How to use checksums
266167b04df994bdd4dd4949536a831a3975a0b0d8ad9fd4da9a76793f4d2cdb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Security for gatewatch 0.1.0b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gatewatch-0.1.0b1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page