ProxyCat: turning short-lived proxy IPs into a fixed tunnel endpoint

The pricing gap ProxyCat was built to close

The README states the motivation directly: during penetration testing, operators often need to hide or change their IP address to get past security devices, and commercial tunnel proxies commonly cost 20 to 40 yuan per day. Short-lived IPs, by contrast, go for a few cents each, which the README puts at roughly 0.2 to 3 yuan per day on average. The mismatch is not price alone. Short-lived IPs expire in anywhere from one minute to sixty minutes, so a tool configured with one of them breaks as soon as it rotates. ProxyCat exists to sit between those two facts: it takes a supply of short-lived proxies and presents a single fixed request address that downstream tools can keep using. The intended user is someone running offensive security work who already has a source of cheap proxies and wants the convenience of a tunnel endpoint without paying tunnel prices. It is not a general-purpose anonymity service, and the README does not present it as one.

How the proxy pool sits between your tool and the upstream proxy

ProxyCat is a middleware process. It listens on one side and forwards on the other. According to the README's feature list, it can listen over HTTP or SOCKS5, so tools that only speak one of those protocols can still be pointed at it. On the outbound side it supports HTTP, HTTPS and SOCKS5 proxy servers, including username and password authentication. The rotation logic offers three modes: sequential, random, and a custom selection mode. When configured to fetch proxies dynamically, the GetIP function retrieves a usable proxy on demand, and the README notes that GetIP can also be driven through an API call. One design detail worth attention is the protection mechanism: when GetIP is in use, the first run does not immediately request a proxy. It waits until an actual request arrives, then fetches one. That avoids burning proxy quota while the service sits idle. On startup the tool checks proxy validity and drops the ones that fail, and if a proxy dies mid-run it verifies and swaps in a new one so the listener keeps answering. Configuration lives in config.ini and the README says changes are detected and applied without a restart. The repository layout matches this description: ProxyCat.py, app.py, a modules/ directory, a config/ directory, and a web/ directory for the management interface.

Installing ProxyCat with Docker and pointing a client at it

The repository ships a Dockerfile and a docker-compose.yml, which is the shortest path to a running instance. The compose file builds the image from the local Dockerfile, sets TZ to Asia/Shanghai, publishes ports 1080 and 5000, mounts ./config into /app/config, and sets the restart policy to unless-stopped.

version: '3'
services:
  proxycat:
    build: .
    environment:
      - TZ=Asia/Shanghai
    ports:
      - "1080:1080"
      - "5000:5000"
    volumes:
      - ./config:/app/config
    restart: unless-stopped
    network_mode: "bridge"

Run it from the repository root:

docker compose up -d

What you should see is the container starting and both ports bound on the host. Port 1080 is the proxy listener and port 5000 is the Web UI, based on the two published ports and the README's mention of a Web management interface. The Dockerfile itself is worth reading before you build: it is based on python:3.11, installs requirements.txt from the USTC PyPI mirror, and runs rm -f config/config.ini so that a baked-in config does not override the mounted one. That deletion is deliberate, and it means the container starts without a config file until the volume supplies one.

If you prefer to run it without Docker, the entry point is app.py and the dependency list is in requirements.txt:

pip install -r requirements.txt
python app.py

The requirements pin httpx 0.27.2 with the http2 and socks extras, Requests 2.32.3, Flask, Werkzeug, asyncio, configparser, colorama, packaging and tqdm. The httpx socks extra is what makes SOCKS5 upstream proxies possible. Before any of this is useful you need to edit config.ini with your proxy source and authentication details; the README says the file controls ports, modes and credentials, but it does not reproduce the full key list, so the Operation Manual under ProxyCat-Manual/ is the place to look for the exact field names.

Where ProxyCat is the wrong tool

The largest gap is the proxy supply itself. ProxyCat rotates proxies; it does not produce them. The README's development plan lists a crawler-based proxy pool as an unchecked item, which means today the tool expects you to bring your own source, whether that is a paid provider or a list you maintain. If you have no proxies, installing ProxyCat gives you a listener with nothing behind it. A second limitation is the rotation trigger. The development plan includes an unchecked item for switching IP after a configurable number of requests, described as a way to handle threshold-based defenses. Until that lands, rotation follows the modes the README does document, sequential, random and custom, rather than a request counter. A third point is that the project is a security tool with an explicit disclaimer: the README states that users bear sole responsibility for any illegal use and that the authors accept no liability. That is not boilerplate to skim past. If your use case is scraping a site that prohibits proxy rotation, or anything where the legal footing is unclear, this is not the project to reach for. Finally, note the release cadence. The most recent release listed is ProxyCat-V2.0.4 from 2025-04-01, and the last push to the default branch was on 2026-07-21. The repository is not archived, but the release history shows a tool that ships in bursts rather than continuously.

ProxyCat against a plain proxy rotator or a commercial tunnel

The obvious comparison is a commercial tunnel proxy, which is exactly what the README frames ProxyCat against on cost. A commercial tunnel gives you a fixed endpoint and manages the underlying IP pool for you, including the supply. ProxyCat gives you the fixed endpoint but leaves the supply to you, in exchange for a much lower running cost if you already buy cheap short-lived IPs. The second comparison is a simple rotating proxy script, the kind that picks a random entry from a list on every request. Those usually live inside the client, which means every tool you run needs its own copy and its own configuration. ProxyCat moves that logic into a separate process that speaks HTTP and SOCKS5, so tools that know nothing about rotation can use it unchanged. The trade-off is an extra hop and an extra process to keep alive. A third point of difference is the management surface. ProxyCat ships a Web UI on port 5000 and supports Chinese and English, and the README lists real-time status display showing proxy state and switch time. A shell script rotator has no such view, which matters when you are trying to work out why a request failed.

Licence and the cost of keeping it running

ProxyCat is licensed under GPL-2.0. That is a copyleft licence, so if you distribute a modified version, the source of your modifications has to be made available under the same terms. Running it internally as a service does not trigger distribution, but bundling it into a product you ship does. This is a description of the licence, not legal advice; check with someone qualified if the distinction matters to you. On upgrade cost, the README lists automatic version checking as a feature, and the development plan has an unchecked item for automatic upgrades, so today the update path appears to be manual: pull the repository and rebuild the image. The Dockerfile deletes config/config.ini during the build and mounts /app/config as a volume, so your configuration survives a rebuild as long as you keep the volume. That is a small but real operational detail. The other recurring cost is proxy quota. Because GetIP only fetches when a request arrives, an idle ProxyCat does not consume proxies, which is the behaviour you want on a metered supply.

Editorial conclusion

ProxyCat fits people who already hold a supply of short-lived proxy IPs and need one stable address for tools that cannot handle rotation themselves. It does not fit anyone without a proxy source, since the README does not describe a built-in pool of free proxies, and the planned crawler pool is still an unchecked item. Before adopting it, read the Operation Manual and Investigation Manual under ProxyCat-Manual/, confirm the GPL-2.0 obligations are acceptable, and check that your proxy provider exposes an API that GetIP can call.

Frequently asked questions

Official sources

1. honmashironeko/ProxyCat on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases