**Residential proxy donation works by having donors run a lightweight client that opens a persistent outbound tunnel (almost always WebSocket/WSS) to your central server. Your server then multiplexes incoming SOCKS5 or HTTP CONNECT requests over those tunnels so traffic exits through the donor’s residential IP.**

This is a reverse-proxy style architecture. The client never listens on a public port; it only dials out. That is why WebSocket (or a similar long-lived bidirectional channel) is the natural transport.

### Core client design (common to all options)
1. Client authenticates (token / account) and opens a WebSocket to your server.
2. Server treats each live WebSocket as a residential exit node.
3. When a customer requests a connection through that node, the server sends a framed “open TCP to host:port” message over the WebSocket.
4. The client opens the TCP socket locally and bidirectionally relays bytes.
5. Keep-alives, automatic reconnect with exponential backoff, and optional bandwidth/rate limits on the client side.

Open-source references that implement exactly this pattern include `residential-proxy-aggregator` (Python WS server + client agents), `pywssocks`, and various WS-SOCKS tools.

### Option comparison

| Option | Reliability / Always-on | Install friction | Resource use | Store / distribution | Best for | Major limitations |
|--------|-------------------------|------------------|--------------|----------------------|----------|-------------------|
| **Browser extension (MV3)** | Medium | Very low | Medium (browser process) | Chrome Web Store / Firefox AMO | Mass casual donors | Service worker idle timeouts; store policies; only while browser runs |
| **systemd user service** (or Windows Service / LaunchAgent) | High | Medium | Very low | Binary + unit file / package | Technical / always-on Linux users | Platform-specific packaging |
| **Desktop app** (Tauri / Electron / native) | High | Medium-High | Low–Medium | Website / GitHub releases | Cross-platform reliability | Larger download, code-signing |
| **Plain webpage / PWA with open tab** | Low | Lowest | Low while open | Just a URL | Quick experiments | Tab throttling, user closes tab, background limits |
| **Service Worker alone** | Poor | Low | Low | Part of a site | Not recommended as primary | Cannot reliably hold long-lived outbound tunnels |

### 1. Browser extension (Manifest V3)
Technically feasible and the lowest-friction option for many donors.

- Background service worker opens the WebSocket.
- Since Chrome 116, WebSocket activity resets the service-worker idle timer, but you still need an explicit keepalive (send a ping every ~20 seconds).
- Use `chrome.alarms` (minimum ~30 s) as a durable backup that survives worker termination and forces reconnects.
- You will also need careful reconnect logic, state persistence (e.g. `chrome.storage.session`), and handling of the case where the worker is killed mid-relay.

**Store and policy issues**
Chrome Web Store (and Firefox AMO) require a clear single purpose and honest disclosure. An extension whose primary function is “share my residential connection / bandwidth” must state that prominently. Proxy-related extensions receive extra scrutiny. Misleading claims or hidden data collection will get you removed. Historical precedent exists (uProxy was a browser-extension peer-proxy system, later discontinued and succeeded by Snowflake).

**Practical limits**
- Only runs while the browser is open.
- Higher CPU/battery impact than a native binary.
- On mobile Chrome the background behaviour is even more restricted.

### 2. systemd user service (Linux) / equivalent on other OSes
This is one of the cleanest long-running options.

- Ship a small static binary (Go, Rust, or even a Node/Python script).
- Provide a user unit file (`~/.config/systemd/user/residential-proxy.service`).
- `systemctl --user enable --now residential-proxy.service`.
- It reconnects automatically, uses almost no resources when idle, and survives reboots (with lingering enabled).

Windows equivalent: a Windows Service or scheduled task. macOS: LaunchAgent. This matches the architecture used by the open-source residential-proxy-aggregator project (C++ Windows service + watchdog).

### 3. Desktop application (Tauri preferred over Electron)
Tauri gives you a small native binary with a system tray, automatic updates, and full control over the WebSocket and TCP relay. Electron works but is heavier. This is the most reliable cross-platform choice if you want something that “just stays on” without requiring users to keep a browser open.

### 4. Service Worker / PWA
A regular service worker (or even an extension service worker without the keepalive tricks) is **not** a good primary client.

Service workers are event-driven and get terminated after short idle periods. They cannot reliably maintain a persistent outbound TCP/WebSocket tunnel that is ready to accept new SOCKS connections at any moment. They are useful for secondary tasks (notifications, caching) but not as the proxy agent itself. Background throttling on inactive tabs and especially on mobile makes a pure PWA approach unreliable for always-available residential exits.

### Other practical considerations

- **Keepalive & reconnect**: Mandatory everywhere. WebSocket idle timeouts on reverse proxies/load balancers are often 60–100 s; your application-level heartbeat should be more aggressive.
- **Bandwidth and rate limiting**: Enforce soft and hard limits on the client so a donor is not surprised by a sudden bill or congestion.
- **Consent & transparency**: Show clear UI that the user is sharing their IP and bandwidth, with an easy off switch. Log (or at least allow users to see) roughly how much traffic has been relayed.
- **ISP terms**: Many residential ISPs prohibit running open proxies, commercial use of the connection, or significant bandwidth resale. Donors should be warned.
- **Abuse & liability**: Residential proxy pools are frequently abused for scraping, credential stuffing, ad fraud, etc. You will need authentication of donors, monitoring, the ability to ban nodes quickly, and clear Terms of Service that shift responsibility appropriately. Pure “donation” models still create platform liability if the traffic is used illegally.
- **Authentication**: Prefer short-lived tokens or account-based auth so you can revoke a donor’s participation instantly.
- **Mobile**: Background execution limits make reliable always-on clients difficult on iOS and restricted on Android. Not recommended as a primary platform.

### Recommended starting path

1. **Prototype** with a simple Node/Go/Rust WebSocket client + a matching server that exposes a SOCKS5 listener (look at `pywssocks` or the residential-proxy-aggregator design for structure).
2. **First distribution channel**: browser extension (for reach) + a tiny systemd/LaunchAgent/Windows service binary (for reliability).
3. Later add a polished Tauri tray app if the project gains traction.

The WebSocket-upstream model is the right foundation. The choice of packaging mainly affects how many people will actually leave the client running and how painful the operational reality becomes. Browser extensions win on distribution; native user services and desktop apps win on reliability and resource behaviour.#