Proxy Workbench v3.0.3

Proxy Workbench 3.0.3

A refreshed desktop interface and documentation for collecting public proxies, checking them against your own services, and using the verified results through exports, a rotating gateway or a local API. The pictured proxy addresses are synthetic examples from RFC 5737 ranges.

Choose a download

Platform	File
macOS, Apple Silicon	DMG
macOS, Intel	DMG
Windows x64	Installer · Portable ZIP
Python 3.11+	Wheel · Source archive
Docker	ghcr.io/davidvoitenko/proxy-workbench:3.0.3

What's improved

• Scan target URLs remain visible next to their protocol selectors.
• Results rows are no longer covered by idle bulk-action controls.
• Example addresses in the interface use reserved documentation ranges.
• Windows exports now recover from brief file locks without leaving partially published files.
• English and Russian guides, the eight-tab gallery, animated tour, website and social preview now match the current application.

The English guide, Russian guide and project website describe installation, API, gateway, limits and privacy. Public proxies and source feeds change over time; check results only describe the services and time measured. Desktop installers are unsigned, so macOS or Windows may request confirmation on first launch. SHA-256 checksums and build manifests are attached below.

Full changes from v3.0.2

Proxy Workbench v3.0.2

Fixed

• Source retries now publish candidates only from a completed response. Byte and line limits keep valid following addresses, and the scan enforces each target's request cap even when one probe makes several requests.
• The API rejects invalid numbers and cursors cleanly, executes concurrent retries with the same idempotency key once, pages scoped jobs and events correctly, and releases SSE slots when clients leave.
• API key forms submit the selected permissions. The import wizard offers every CSV/JSON column, accepts the first or duplicate column, and discards previews after the input changes. Switched tabs remain visible when a browser pauses animations.
• Docker includes the service preset catalog. Its Compose gateway can start on the configured network bind, and the CLI shows a generated password or usable authenticated examples without printing a supplied secret.

What's Changed

• Release 3.0.2: fix collection, API, UI and Docker workflows by @DavidVoitenko in #30
• Fix idempotency lock collisions under concurrent API requests by @DavidVoitenko in #31

Full Changelog: v3.0.1...v3.0.2

Proxy Workbench v3.0.1

Fixed

• Checks run up to 16× faster on large lists. Every scan was held at 64 checks in flight whatever the worker setting said (the memory reserved for response bodies had a fixed 64 MiB budget); the budget now grows with the workers up to 1 GiB. Ports of one IP no longer queue up together either: the first port of every host is checked first and further ports follow host by host. A full check of 663,000 collected addresses went from 25 to about 390 addresses per second with 512 workers.
• macOS app: collecting and HTTPS checks work again. The 3.0.0 macOS builds looked for trusted certificates in a folder of the build machine, so every HTTPS source failed with a connection error and no proxies could be collected. Every HTTPS connection (sources, HTTPS checks, the gateway's HTTPS upstreams) now also trusts the certificate bundle shipped inside the app, while the system store is still used.
• The rotating proxy is far more reliable with flaky free proxies. A proxy that does not answer within 2 seconds no longer blocks the request: the next proxy is tried alongside it and the first working tunnel wins (up to 4 proxies; a failed request now gives up after about 14 s instead of 24 s). When every proxy in a small pool was resting after failures, the gateway answered 502 instantly for five minutes; it now falls back to the proxy that is due back first. On 11 real public proxies right after a restart: 18 of 20 requests succeeded instead of 6 of 10.
• Simultaneous gateway connect outcomes now record failed proxies before serving the winner. Proxies still connecting after another wins are marked slow, so they stop delaying each request. A failover session is pinned to the tunnel that actually won, and strict sessions keep their single-proxy rule.
• The results view looks up source provenance only for its selected profile, avoiding a scan of every collected candidate on each request.
• “This data folder is already used by another run” when starting a check. The desktop app's background job runner and scheduler hold the data lock for a moment every second, and a check started from the interface gave up on the first try. A run now waits up to 10 seconds for such a short hold; a folder that stays busy is still refused.
• The interface server reads or closes the body of a request it refuses, so a refused request no longer shows up as a reset connection on Windows or as a garbled next request.

What's Changed

• Release 3.0.1: fix HTTPS in the macOS app by @DavidVoitenko in #29

Full Changelog: v3.0.0...v3.0.1

Proxy Workbench v3.0.0

Important

macOS users: please download 3.0.1. The 3.0.0 macOS app cannot collect proxies (it does not trust any HTTPS certificate). Windows, pipx and Docker are not affected.

Finds free proxies that actually work — on the sites you need. Proxy Workbench collects free proxies from 150 public sources, tests every one against your own sites and services, and keeps only the working ones: as ready lists, one rotating proxy for your browser, Telegram and any app, or an API for your scripts. Runs on your own computer, no sign-up, no telemetry.

⬇️ Download

Your system	File	How
macOS, Apple Silicon (M1–M4)	proxy-workbench-3.0.0-macos-arm64.dmg	Open, drag Proxy Workbench into Applications. First start: right-click → Open (the app is not notarized).
macOS, Intel	proxy-workbench-3.0.0-macos-x86_64.dmg	Same as above.
Windows 10/11	proxy-workbench-3.0.0-windows-x64-setup.exe	Run the installer (no admin rights needed). SmartScreen: More info → Run anyway.
Windows, no install	proxy-workbench-3.0.0-windows-x64-portable.zip	Unzip anywhere and start proxy-workbench-gui.exe; proxy-workbench-cli.exe is the command line.
Linux / any OS with Python 3.11+	pipx install git+https://github.com/DavidVoitenko/proxy-workbench	Then run proxy-workbench.
Server / NAS	docker compose up -d	Checker + API + rotating proxy, see the README.

Every file has a SHA-256 checksum next to it (*.sha256, SHA256SUMS-*).

🎬 See it in action

Scan — your sites, success rules and live progress	Results — ranked, filtered, ready to export
Details — every attempt against every service	Light theme and 12 languages

_{Screenshots use synthetic data from documentation address ranges.}

What’s new in 3.0

The biggest release so far: a new interface, a source catalog of 150 lists, a desktop app that lives in the menu bar, persistent proxy pools with schedules, API keys, diagnostics that explain an empty result, and backups you can preview before restoring. Existing data folders are upgraded in place, with an automatic copy taken first.

Highlights

• Redesigned interface. A new dark-first design layer with a reworked light theme, consistent typography, micro-animations and a live feed of the running check. The layout adapts to phones and tablets (a side rail on tablets, a compact layout on phones), and heavy tables stay smooth on large result sets.
• 12 interface languages. English and Russian are joined by German, Spanish, French, Italian, Japanese, Polish, Portuguese, Turkish, Ukrainian and Chinese, every one of them complete.
• Source catalog: 150 sources, 117 of them fully free and public; 106 feeds are collected out of the box. Every entry says who publishes it, what it serves (proxy list, subscription config, API), whether an account is needed, which protocols it carries and how it was verified. Ready-made sets (quick, all supported, extended, by protocol), one-click enable/disable, per-source reports and a comparison that spots lists which republish each other. Only sources marked safe to collect are fetched; commercial, trial and rejected entries are shown for reference.
• Desktop app. Starting proxy-workbench without arguments now launches the desktop app: a macOS menu-bar icon, a single running instance, optional start at login, and correct recovery after sleep/wake. proxy-workbench gui (or --no-desktop) opens only the web interface, as before.
• Proper installers. A macOS .app/.dmg (Apple Silicon and Intel) and Windows GUI and CLI executables with a per-user installer; Linux installs with pipx or Docker. Data lives in per-user folders, with a portable mode and automatic migration of an old data/ folder.

Added

• Pools. A named pool keeps N working proxies for a profile, with a reserve, quotas and resource budgets; it refills and re-checks itself, and tells you why it is short.
• Schedules. Re-check collections or pools on an interval, in your time zone, with quiet hours, request/byte budgets and notifications when a proxy's state changes.
• Named profiles with revisions and presets. Target rules, success criteria and settings are saved as profiles; every change is a revision, and profiles can be shared without secrets.
• Collections and import. Bring your own lists from TXT, URI, CSV, JSON, Clash or sing-box files with a preview, column mapping and a report of every rejected line; imports are transactional and merge or replace.
• Service catalog. Ready-made checks for popular services, grouped into sets, with an explicit rule for which fields a preset overwrites.
• Geography and exit country. Filter by the proxy's own country, the country traffic actually exits from, or either; exclude countries; choose how unknown locations are treated.
• Rotating gateway, upgraded. Bind the gateway to a pool from the GUI, serve it on your LAN (--lan, --gateway-interface), and use upstream proxies that need a login (HTTP Basic, SOCKS5 username/password). The gateway has its own password (--gateway-token), separate from the API token.
• API keys. Create named keys with permissions, collection/pool scope, rate and concurrency limits, expiry, rotation with a grace window, revocation and an audit log — in the GUI (Keys page) and the CLI (api-key). A secret is shown exactly once.
• Secret store and access identities. Proxy credentials are stored separately and referenced, never copied into exports or diagnostics.
• Diagnostics. A funnel shows where candidates were lost; "why 0 results" explains an empty run in plain words; a health check; and a redacted diagnostic bundle you can review before saving (diagnose funnel|zero|control|health|bundle).
• Backup, restore and retention with preview. backup create|list|verify|preview|restore|rollback|retention|cleanup|rebind; every change is previewed first and runs only with --apply (or the confirm button in the GUI).
• Run budgets and "find N". --want N with --count-what endpoint|ip|exit, --deadline, --max-requests, --run-max-bytes; a run that falls short says which unit it could not reach.
• Export targets. --client-target / --client-binary validate sing-box output for a specific client version.
• Versioned control API /v1 for scripts and integrations: collections, sources, profiles, jobs, results, pools, gateway, schedules, exports, imports and keys. A machine-readable description ships as proxy_workbench/openapi.json.

Changed

• Breaking: running proxy-workbench / python -m proxy_workbench with no arguments opens the desktop app instead of only the web interface. Use proxy-workbench gui for the old behaviour. All CLI commands are unchanged.
• Breaking: the database schema moves to version 20. Older data folders (1.x and 2.x) are migrated on first start; a backup is taken before any non-additive step and can be restored with backup rollback. Do not open an upgraded folder with 2.x.
• Breaking: the rotating gateway no longer accepts the API token as its password; set --gateway-token / PROXY_WORKBENCH_GATEWAY_TOKEN. The bundled compose.yml already does.
• Each proxy address is now one row per profile and access identity, so an address no longer appears twice in proxies.txt, ranked.*, proxy.pac, clash.yaml, singbox.json or /proxies.
• Python 3.11 or newer; CI tests 3.11, 3.12 and 3.14 on Linux, macOS and Windows.

Fixed

• Checks are much faster on real-world lists. A scan no longer waits on its own database lock for every job item, and dead proxies no longer push the number of parallel checks down to one: 3,000 mostly dead candidates now take seconds instead of hours. Running out of file descriptors is no longer recorded as a dead proxy.
• The database no longer grows without limit under --watch. Each source keeps its last three downloaded lists; older ones are pruned right after a collection, and backup retention cleans up history left by earlier versions. A list the server reports as unchanged is re-applied to collections that lost it, and a retry after a broken download no longer counts the first attempt against the size limit.
• Collecting is faster and reads more lists. Addresses are written in batches (a full collection o...

Proxy Workbench v2.2.1

Fixed

• Collecting from public sources returned nothing. The transport that pins a source to its checked IP sent two Host headers, so every hostname-based list failed with LocalProtocolError. Tests only used IP-literal sources, which skip that path; new tests cover hostname sources.
• A proxy with a malformed SOCKS5 reply stopped the whole scan. socksio's parse error escaped as an ExceptionGroup. Any error of a single proxy is now recorded as that proxy's failure.
• Speed tests use a high-resolution timer; on Windows very fast downloads could lose their Mbit/s value.

Changed

• Default per-source limits are 32 MiB and 500,000 candidates, so the largest public lists are no longer cut off.

What's Changed

• Refresh screenshots and landing page; time speed tests with perf_counter by @DavidVoitenko in #23
• Update the social preview image for 2.x by @DavidVoitenko in #24
• Use an absolute link-preview image URL on the landing page by @DavidVoitenko in #25
• Release 2.2.1: fix collecting from hostname sources and malformed SOCKS5 replies by @DavidVoitenko in #26

Full Changelog: v2.2.0...v2.2.1

Proxy Workbench v2.2.0

Added

• Recommended sort (now the default) combines four signals:

  • quality;
  • survival across re-checks;
  • how rare a proxy is across lists: an address offered by one niche list is less crowded than one in twenty lists;
  • the track record of the list it came from.

  Exports gain listed_in and recommended.

• proxy-workbench get prints working proxies from the latest export for shell scripts (--protocol, --country, --top, --random, --format txt|hostport|json, --no-hosting).

• proxy-workbench test PROXY… checks your own proxies against the usual targets without storing anything.

• sing-box config: singbox.json in every export and /singbox in the API.

• Use in Telegram button for the rotating proxy (opens tg://socks with its address).

• The results table follows a running check every few seconds.

• Settings can be saved to a file and loaded back (Help tab).

What's Changed

• Release 2.2.0: recommended sort, get/test commands, sing-box, Telegram button by @DavidVoitenko in #22

Full Changelog: v2.1.0...v2.2.0

Proxy Workbench v2.1.0

Added

• Rotating proxy for scrapers.
  • The user name picks what you need: country-de_nl, protocol-socks5, latency-800, anonymity-elite.
  • session-<id> keeps one proxy for a whole session while it works.
  • --max-per-proxy caps simultaneous connections per proxy.
  • GET /status on the gateway shows the pool, sessions and per-proxy counts.
• Real download speed: an optional speed test file (--speedtest-url, GUI field) is downloaded through each working proxy.
  • The Mbit/s column, the bandwidth sort, mbps in exports and the API, and an API min_mbps filter show the result.
• Provider of every proxy: update-geoip also fetches DB-IP ASN Lite. Each proxy gets its AS number, organisation and a hosting flag.
  • --no-hosting and the GUI option skip cloud and data-centre ranges before checking.
  • The results table gets a Provider column and a filter; exports and the API get asn, provider, hosting and hosting=0/1.

What's Changed

• Release 2.1.0: scraper-friendly gateway, speed test, proxy providers by @DavidVoitenko in #21

Full Changelog: v2.0.0...v2.1.0

Proxy Workbench v2.0.0

Added

• Windows executable: every release ships proxy-workbench-…-windows-x64.exe built with PyInstaller. It opens the GUI on double-click, runs the CLI with arguments, and keeps its data in a data folder next to itself; no Python needed.
• pipx install (#3): pipx install git+https://github.com/DavidVoitenko/proxy-workbench gives a proxy-workbench command. Without arguments it opens the GUI; with arguments it runs the CLI (python -m proxy_workbench works too). Releases also attach the wheel.
• Docker Compose: compose.yml runs a checker that keeps 100 proxies fresh, the API and the rotating proxy from one shared volume.
• Quick pre-check (--prefilter, on by default with 512 connections; GUI: Performance → Quick pre-check). A plain TCP connect runs before the full check, so addresses that do not even accept a connection (most of any public list) are dropped at a fraction of the cost. They are stored as UNREACHABLE, so a stopped scan resumes where it left off.
• End-to-end package check: packaging/smoke.py installs nothing and touches no public network. It starts the built app, runs a check through a local mock proxy and reads the result back through the API and the gateway. CI runs it for the wheel on Linux and Windows and for the Windows executable; releases run it before publishing.

Fixed

• On Windows, background checks started from an environment without PYTHONUTF8 (the new .exe and pipx installs) failed on the first Cyrillic log line. Terminal output is now always UTF-8.

Changed

• The code now lives in the proxy_workbench package. proxytool.py, gui.py, Start.bat, Start.command and run.sh keep working from a source folder, and an existing data/ folder there is used as before.
• The data folder is chosen as follows: PROXY_WORKBENCH_DATA, then data/ in a source checkout or next to the .exe, then the user profile for pipx installs.
• The Docker image sets PROXY_WORKBENCH_DATA=/app/data.
• The GUI starts its checks as python -m proxy_workbench …, or through the executable itself when frozen.

What's Changed

• Release 2.0.0: Windows executable, pipx install, Docker Compose by @DavidVoitenko in #20

Full Changelog: v1.9.0...v2.0.0

Proxy Workbench v1.9.0

Added

• Rotating proxy gateway on 127.0.0.1:8899. It starts with the GUI (--gateway-port, --no-gateway) and runs on servers as the gateway command (--rotate, filters, --api-token password for network binds).
  • One address accepts HTTP, CONNECT and SOCKS5 clients.
  • Each new connection goes through the next working proxy, with retries through other proxies and a rest period for failing ones.
• Browser and client configs: proxy.pac (10 best proxies, no direct fallback) and clash.yaml (Clash / Mihomo with an automatic url-test group). Both are in every export and live at /pac and /clash in the API with its filters.
• Ready-made checks for Google, YouTube, Telegram, Discord, Instagram, the OpenAI API, GitHub, Wikipedia and Cloudflare in the GUI.
• Exit IP and exit country from the anonymity judge: exit_ip / exit_country in CSV, JSON and the API; the Country column shows DE → NL when they differ.
• Keep fresh in the GUI: re-check working proxies every N minutes while the app stays open; the results table, API and gateway follow each new export.
• Protocol and country summary of matching proxies above the download buttons and in status.json (breakdown).

What's Changed

• Release 1.9.0: rotating proxy gateway, PAC and Clash, ready-made checks, exit country, keep fresh by @DavidVoitenko in #19

Full Changelog: v1.8.0...v1.9.0

Proxy Workbench v1.8.0

Added

• SOCKS4 proxies: collected from five new built-in lists and Geonode, checked through a built-in SOCKS4 connector (httpx has none), exported to socks4.txt and proxychains.txt, and available in every protocol filter and the API.
• Protocol detection: auto URL sources and the Try HTTP, SOCKS4 and SOCKS5 option for your own list (--detect-protocols) check addresses without a protocol as all three; whichever works is kept.
• Any web page as a source: text URL pulls every ip:port out of HTML tables, CSV and free text, including rows split across lines. free-proxy-list.net, sslproxies.org and us-proxy.org are built in (55 sources in total).
• Source upkeep in one click: Remove dead sources drops lists that gave at least 20 checked addresses and none working; Get new sources adds lists published on GitHub after your version without bringing back the ones you removed.
• English terminal messages and --help with examples; the language follows the system and PROXY_WORKBENCH_LANG overrides it (#2).

What's Changed

• Release 1.8.0: SOCKS4, protocol detection, web page sources, English CLI by @DavidVoitenko in #18

Full Changelog: v1.7.0...v1.8.0