Detailed Feature Guide
Detailed ZeroTrace Proxy capability guide covering app shell, core tools, engines, workspace memory, exports, settings, and unique capabilities.
This page is the deep reference for ZeroTrace Proxy. Use it when you want to understand the full shape of the product: how tasks move through the workspace, what each core tool records, what the runtime engines remember, and which smaller controls matter when you are building a repeatable proxy workflow.
Use the tutorial pages when you want a guided flow. Use this guide when you are comparing capabilities, checking an exact field, or deciding which tool should own the next step.
Desktop Shell and App Services
| Feature | Details |
|---|---|
| Desktop app shell | Wails desktop app with embedded Next/React frontend. |
| Window baseline | Frameless main window with a 1500 x 747 baseline and matching minimum size in the current app build. |
| Window behavior | Always-on-top, content-protection, disable-resize, and startup state settings. |
| Startup states | Normal, maximised, fullscreen, and minimised. |
| Local data | Dedicated app data directory under the user config path plus a dedicated WebView user data path. |
| Registered services | Files, extraction tasks, checker tasks, benchmark tasks, chain tester tasks, leak test tasks, proxy viewer, task history, proxy pools, task profiles, notifications, settings, Chain Engine, and Rotation Engine. |
| UI stack | Next, React, TypeScript, Tailwind, shadcn-style components, TanStack Table/Virtual, Recharts, and Sonner notifications. |
Shared Task Lifecycle
| Tiny feature | What it does |
|---|---|
| Start now | Runs immediately when the tool has capacity. |
| Queue | Waits for an active slot in that tool's queue. |
| Schedule | Runs after the configured due timestamp. |
| Active limit | Each core task type allows up to two active runs at once. |
| Queue loop | Queue state refreshes on a one-second loop. |
| Oldest first | Queued tasks start oldest-first when slots free up. |
| Restart cleanup | Running, queued, and scheduled snapshots normalize to stopped after app restart so stale jobs do not look alive. |
| Progress memory | Progress callbacks persist task snapshots while work is running. |
| Batch updates | Batch progress updates reduce noisy persistence churn. |
| Cancellation | Task contexts support cancellation and stop flows. |
| Dependencies | Shared task-builder helpers include dependency validation, cycle detection, deterministic insertion, and first-failure cancellation. |
Scheduled time parsing accepts RFC3339Nano, RFC3339, 2006-01-02T15:04, and 2006-01-02 15:04 formats.
Proxy Extractor
| Area | Full detail |
|---|---|
| Source kinds | Single URL/source, many URLs/sources, and local file. |
| Task metadata | Name, notes, tags, start mode, and scheduled timestamp. |
| Fetch controls | Concurrency, timeout seconds, random User-Agent toggle, custom User-Agent, follow redirects toggle, custom headers, and cookies. |
| Parser profiles | Auto, plain text, HTML, and JSON. |
| Auto parser | Chooses based on content type, body shape, selector, JSON path, and fallback results. |
| JSON paths | Dot paths, numeric indexes like [0], and wildcards like [*]. |
| JSON inference | Finds proxy-shaped objects using host, hostname, ip, address, server, port, scheme, protocol, type, username, user, login, password, and pass fields. |
| HTML extraction | Supports selectors, table tr, pre, code, textarea, ul li, ol li, data-ip, data-host, data-proxy, and data-address. |
| HTML attributes | Reads text plus useful attributes such as data-*, href, content, value, and title. |
| HTML extras | Understands table cells and child elements, and inspects script blocks that look like JSON or contain proxy signals. |
| Body handling | HTTP extraction body limit is about 4 MiB. |
| Decompression | Handles gzip, zlib, and deflate-style encodings. |
| Dedupe | Full proxy string, host plus port, host only, and prefer-strongest dedupe behavior. |
| Source metrics | HTTP status, duration, content type, response bytes, parser used, extraction scope count, candidate count, duplicate count, proxy count, and error. |
Supported extracted proxy formats include host:port, scheme://host:port, host:port:user:pass, user:pass@host:port, bracketed IPv6, HTTP, HTTPS, SOCKS4, SOCKS4a, SOCKS5, and SOCKS5h. The parser also normalizes malformed scheme variants such as missing or partial ://.
Proxy Checker
| Area | Full detail |
|---|---|
| Inputs | Single proxy, many proxies, file, saved pool, and handoff rows from other tools. |
| Controls | Concurrency, timeout seconds, random/custom User-Agent, custom request URL, country/location resolution, expected status code, expected status code list, HTTPS check toggle, and protocol hint. |
| Protocol hints | Auto, HTTP, and SOCKS. |
| Auto detection | Proxies without schemes are tried with likely protocol candidates. SOCKS-oriented ports such as 1080, 1081, 9050, and 9051 try SOCKS first. |
| Auth signals | Detects configured credentials, proxy auth challenge, and no-auth cases. |
| Enrichment | Exit IP, country code, country, region, city, ASN, ISP, organization, network type, and network confidence. |
| Network type | Residential, mobile, datacenter, or unknown. |
| Anonymity | Elite, anonymous, transparent, or unknown from headers such as Via, X-Forwarded-For, and Forwarded. |
| Quality | Quality score from 0 to 100 and labels high, medium, low, and poor. |
| Scoring inputs | Anonymity, HTTPS support, latency, and auth status. |
| Enrichment fallback | Uses api.ipapi.is, then falls back to ipwho.is; location/network enrichment is cached. |
Checker output includes raw proxy, normalized proxy, alive/dead status, detected protocol, support for HTTP and HTTPS, latency, exit IP, location fields, ASN/ISP/org, auth signal, has-auth flag, error, and checked timestamp.
Proxy Benchmark
| Area | Full detail |
|---|---|
| Inputs | Single proxy, many proxies, file, pool, and tool handoff rows. |
| Rounds | Default 3 rounds, maximum 10 rounds. |
| Shared controls | Protocol hint, request URL, expected status codes, country resolution, HTTPS check, User-Agent controls, timeout, and concurrency. |
| Method | Runs checker-style validation repeatedly for each proxy. |
| Best sample | Chooses the best successful sample by latency. |
| Failure detail | Preserves useful failure detail when all rounds fail. |
| Summary | Benchmarked count, passing count, failing count, and average latency. |
Benchmark output includes total runs, pass count, fail count, success rate, average latency, best latency, worst latency, HTTPS support, exit IP, country/location data, last error, and benchmarked timestamp.
Proxy Leak Tester
| Area | Full detail |
|---|---|
| Inputs | Single proxy, many proxies, file, pool, and handoff rows. |
| Default target | Uses an httpbin-style anything response that exposes headers and origin. |
| Response expectation | Target must return inspectable JSON with headers and origin. |
| Leak signals | via, forwarded, x-forwarded-for, proxy-authorization, and origin-mismatch. |
| Leak counting | Signals are sorted and counted. |
| Classification | Transparent when forwarding headers expose the route, elite when no leak signals are present, anonymous for other working cases. |
| Summary | Tested count, clean count, leaked count, transparent count, and average latency. |
Leak output includes raw proxy, normalized proxy, detected protocol, status, latency, exit IP, country/location data, anonymity, per-signal flags, origin mismatch flag, origin value, leak signal list, leak count, error, and tested timestamp.
Proxy Viewer
| Area | Full detail |
|---|---|
| Methods | GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS. Unsupported methods fall back to GET. |
| Request body | Body input is supported for methods that can send a body. |
| Controls | Timeout, random/custom User-Agent, follow redirects, resolve location, custom headers, cookies, and max body preview size. |
| Preview clamp | Minimum 64 KiB, default 512 KiB, maximum 2048 KiB. |
| Scheme attempts | Auto-detects candidate proxy schemes and tries until one succeeds. |
| Redirects | Manual redirect following up to 8 hops when enabled. 301, 302, and 303 can convert to GET except for GET/HEAD cases. |
| Body rendering | Detects HTML, JSON, image, and binary-ish responses. |
| Inspectors | Request headers, response headers, cookies, redirect chain, attempt log, exit IP, and geolocation. |
| Truncation | Large bodies get a truncation marker; binary responses can be omitted instead of dumped. |
Attempt logs include scheme, normalized proxy, requested URL, success flag, status code/status, latency, final URL, redirect count, exit IP, and error.
Chain Tester
| Area | Full detail |
|---|---|
| Inputs | Single chain, many chains, and file input. |
| Chain separators | Newlines, arrows such as => or ->, and pipe separators. |
| Controls | Concurrency, timeout, random/custom User-Agent, request URL, country/location resolution, follow redirects, and expected status codes. |
| Dialer | Real chained dialer implementation, hop by hop. |
| Hop protocols | HTTP CONNECT, HTTPS CONNECT, SOCKS4, SOCKS4a, and SOCKS5. |
| Auth | SOCKS5 username/password and HTTP Basic Proxy-Authorization for CONNECT. |
| SOCKS4a | Remote hostname marker support. |
| Probes | Per-hop HTTP and HTTPS probes. |
| Grade | Chain score from 0 to 100 and grades A, B, C, D, and F. |
Chain result fields include original chain, normalized chain, hop count, working hop count, failed hop index, status, HTTP support, HTTPS support, status codes, latencies, redirect count, final URL, score, grade, exit IP, country/location data, error, hops, and tested timestamp.
Autonomous Harmony Mode
Harmony mode can search for working chains instead of only testing pasted chains. It supports pasted or permuted order, max hops normalized up to 10, default beam width 96, default candidate-test budget 3000, hard candidate-test budget 15000, individual proxy preflight, deeper expansion with unused proxies, and expansion ranking by HTTPS support, HTTP support, latency, and chain string.
Chain Engine
| Area | Full detail |
|---|---|
| Saved chains | Persistent chain definitions with ID, name, notes, tags, primary hops, hop labels, fallback chain IDs, policy ID, created timestamp, and updated timestamp. |
| Fallback graph | Validates fallback routes, detects cycles, and detects missing fallback chain references. |
| Delete protection | Default policy cannot be deleted, policies in use cannot be deleted, and chains used as fallback cannot be deleted. |
| Default policy | Balanced policy, startup validation off, auth off, HTTPS fallback probe, expected 200, request timeout 20s, connect timeout 12s, health interval 20s, failure threshold 3, retry budget 1, fallback enabled. |
| Policy fields | Startup validation, require auth, auth username/password, probe URL, expected status code list, request timeout, connect timeout, health interval, failure threshold, retry budget, fallback enabled, and bandwidth limit MB. |
| Runtime endpoint | Local HTTP proxy and CONNECT tunnel endpoint bound to 127.0.0.1. |
| Port fallback | If the requested port is busy, the runtime binds a random local port and records a notice. |
| Auto-start | Runtime configs can auto-start and are restored when the service is created. |
| Health | Health loop probes routes on the policy interval and marks routes unhealthy after the failure threshold. |
| Degraded start | Runtime can start degraded if the primary route fails validation but a fallback route can run. |
| Local auth | Basic proxy auth with constant-time credential comparison and Proxy-Authenticate challenge. |
| Bandwidth cap | Bandwidth limit can enforce status 509 when the cap is reached. |
| Traffic cap | Keeps the latest 500 traffic entries. |
Runtime snapshots include endpoint URL, requested port, bound port, active chain, route count, healthy route count, last exit IP, last notice, last error, last health timestamp, started/stopped timestamps, request count, success count, failure count, switch count, bytes received, and bytes sent.
Rotation Engine
| Area | Full detail |
|---|---|
| Rotators | Persistent rotator definitions with ID, name, notes, tags, sources, selection strategy, policy ID, created timestamp, and updated timestamp. |
| Sources | Saved proxy pool sources and inline direct proxy list sources. |
| Migration | Legacy primary/fallback pool fields are migrated into normalized source records. |
| Strategies | Round robin, random, and least recently used. |
| Default policy | Balanced Rotation, startup validation off, expected 200, request timeout 20s, connect timeout 12s, health interval 30s, max requests per session 1, max session seconds 300, max bytes per session 50 MB, sticky target host off, failure threshold 2, retry budget 1, rotate on 403/429/502/503/504, cooldown 30s, quarantine 300s, max concurrent requests per proxy 4, fallback enabled. |
| Policy fields | Startup validation, probe URL, expected status codes, request/connect timeout, health interval, max requests/session, max session seconds, max bytes/session, sticky by target host, failure threshold, retry budget, rotate-on status code list, cooldown, quarantine, max concurrent requests per proxy, and fallback. |
| Large caps | Max bytes per session normalizes very large caps up to about 1 TiB. |
| Runtime endpoint | Local HTTP proxy and CONNECT tunnel endpoint bound to 127.0.0.1. |
| Health | Health loop probes each proxy, updates latency and exit IP, and maintains available/cooling/quarantined counts. |
| Sessions | Global session key by default; per-target-host session key when sticky target host is enabled. |
| Rotation reasons | New session, sticky reuse, status-triggered rotation, unavailable proxy, quarantined proxy, cooling proxy, over concurrency limit, max requests reached, max session time reached, max session bytes reached, and primary source exhausted. |
| Penalties | Failures can trigger cooldown, then quarantine after the failure threshold. |
| Concurrency | Enforces max concurrent requests per proxy with active request counters. |
| Traffic cap | Keeps the latest 500 traffic entries. |
Rotation runtime snapshots include endpoint URL, requested/bound port, active rotator, active source, active proxy, source count, available proxy count, cooling count, quarantined count, last exit IP, last switch reason, last notice, last error, last health timestamp, started/stopped timestamps, request count, success count, failure count, switch count, bytes received, and bytes sent.
Proxy Pools
| Feature | Details |
|---|---|
| Pool limit | Maximum 100 pools. |
| Pool fields | ID, name, description, entries, created timestamp, and updated timestamp. |
| Entry fields | Proxy, tags, source tool, source task ID, source task name, and added timestamp. |
| Save modes | Create new pool, save into existing pool, replace entries, and merge entries. |
| Dedupe | Dedupes by exact proxy string. |
| Tags | Tags normalize to lowercase, dedupe, and sort. |
| Merge memory | Source metadata merges when entries collide, and newest added timestamp is kept. |
| Maintenance | Delete pools, remove specific entries, migrate legacy single JSON pool file to index/detail directory format, and trim orphaned detail files. |
| Input reuse | Shared task builders can read pool input. |
| Save dialog | Supports selected candidates, existing pool target, new pool creation, candidate normalization/dedupe, smart tags, source context, and preview of first candidates. |
History, Profiles, and Notifications
| Feature | Details |
|---|---|
| Task history | Stored in zerotrace-task-history.json with a 250-entry cap. |
| History metrics | Input count, output count, success count, failure count, and average latency. |
| History links | Stores tool, task ID, name, href, status, created/completed/updated timestamps, and metrics. |
| Sorting | History is sorted newest-first and powers the dashboard overview. |
| Task profiles | Stored per tool under zerotrace-task-profiles. |
| Defaults | Save profile, apply profile, delete profile, set default profile, and enforce one default profile per tool. |
| Default apply | Frontend applies default setup when a builder opens. |
| Notifications | Stored in zerotrace-core-notifications.json with a 250-entry cap. |
| Notification fields | Kind, tool, task ID, title, message, href, level, created timestamp, and read flag. |
| Notification actions | Add notification, mark one read, mark all read, clear notifications, show unread count, and show recent updates. |
Discord and File Export
| Feature | Details |
|---|---|
| Webhook setting | Discord webhook URL lives in settings. |
| Validation | URL must be valid, HTTPS, and have a host containing discord. |
| Username | Default webhook username is ZeroTrace. |
| Payloads | Sends content, embeds, and attached files. |
| Content cap | Content truncates at 1900 characters. |
| Embed cap | Up to 10 embeds. |
| Embed field caps | Title 256 chars, description 4096 chars, 25 fields, field name 256 chars, field value 1024 chars. |
| File cap | Up to 10 files. |
| File size handling | File content truncates at 7 MiB with a [truncated] marker. |
| Multipart | Multipart upload is used when files are present. |
| File picker | Files service can pick .txt files and save proxy lists to .txt. |
| Export filenames | Export filename slugifies the task name. |
| Export workspace | Shows metrics, current export rules, preview, and final save action. |
Frontend UX and Handoffs
| Feature | Details |
|---|---|
| Sidebar groups | Workspace, Core Tools, Chain Engine, Rotation Engine, and System. |
| Dashboard | Total runs, completed runs, inputs, outputs, live queue, recent runs, task links, tool mix, pools, profiles, and latest run cards. |
| Tables | Searchable column, deferred search, sorting, column sort menu, hide column, visibility dropdown, pagination, selectable rows, virtualized rows above threshold, visible data callback, selected data callback, and table settings persisted in localStorage. |
| Builders | Name, notes, tags, start now, queue, schedule, single/many/file/pool inputs, protocol hint, HTTPS toggle, country/location toggle, User-Agent controls, request URL, and accepted status codes. |
| Handoffs | Send selected rows, visible rows, or all ready rows to follow-up tools; inherit notes/tags/options where supported; navigate/open destination tool; report successes/failures. |
| Insights | Extractor yield and duplicate pressure, checker live percentage and quality risks, benchmark stability, leak cleanliness, and chain winner quality. |
Settings and Storage Visibility
Settings shows window behavior, Discord webhook URL, base app data directory, settings file, task history file, notifications file, chain definitions/policies, chain runtimes, rotation definitions/policies, rotation runtimes, proxy pools directory, proxy pools index, task profiles directory, task runs directory, and WebView user data path.
Most Unique Features
| Unique feature | Why it stands out |
|---|---|
| Autonomous chain harmony search | Most proxy tools let you define a chain; ZeroTrace Proxy can search for working multi-hop candidates from a set. |
| Extract to operate workflow | Extraction, checking, benchmarking, leak testing, chaining, pooling, rotation, reporting, and runtime logs live in one desktop workspace. |
| Structured extractor | HTML selectors, JSON paths, proxy-shaped object inference, script inspection, decompression, headers/cookies, and dedupe policies go beyond simple regex paste tools. |
| Dual local runtimes | Separate Chain Engine and Rotation Engine expose local HTTP/CONNECT endpoints with health, fallback, policies, auto-start, and traffic logs. |
| Session-aware rotation | Sticky host sessions, max requests/time/bytes, rotate-on status, cooldown, quarantine, retry, fallback, and per-proxy concurrency are all policy-driven. |
| Leak testing as a first-class stage | Header leaks, proxy auth exposure, origin mismatch, leak counts, and anonymity labels are captured as a normal workflow step. |
| Operational memory | Pools, profiles, history, notifications, Discord reports, exports, and traffic logs make it a workflow cockpit instead of a one-shot checker. |
What It Does Not Try To Be
ZeroTrace Proxy is not an OS-wide per-application proxifier, not a browser-only URL pattern switcher, not a commercial proxy network provider, not a full MITM traffic rewriting/debugging suite, and not a Unix preload-style command wrapper. It is strongest when the work is finding, cleaning, scoring, leak-testing, chaining, rotating, and operating proxy lists from a desktop app.