# NH3 egress proxy (nh3-dev)

A durable, **internal-only** SOCKS5 egress proxy on `nh3-dev`
(`10.100.10.50:1080`) for colo/fleet services that get gated on their
**datacenter IP**. Traffic proxied through it exits via NH3's
**residential** line (egress ~`70.230.226.88`), which is not on the
datacenter blocklists that flag the Anaheim/Irvine colo ranges.

## Why it exists

YouTube (and a growing set of services) hard-flag datacenter IPs —
returning `LOGIN_REQUIRED` / "Sign in to confirm you're not a bot" even
for public content, regardless of cookies or PO-tokens. The origin case
was **yt-voice-clipper** on `irv-ml1` (Irvine colo): every yt-dlp fetch
was bot-gated. Confirmed it was purely IP reputation — the *same public
video fetched cleanly with no cookies* once routed through nh3-dev's
residential egress. This is **not** yt-voice-clipper-specific; it's a
reusable egress for any gated colo service.

## What it is

- **Daemon:** `dante-server` (danted), SOCKS5.
- **Listener:** `10.100.10.50:1080`, bound to the WG/LAN interface
  (`ens18`) only.
- **Egress:** nh3-dev's default route (`ens18` → residential uplink).
- **ACL:** client connections restricted to `10.100.0.0/16` (the
  WG/LAN). **NOT an open proxy** — an open proxy on a residential IP
  gets abused within hours and the IP flagged, defeating the purpose.
- **Managed by:** [`scripts/setup-nh3-egress-proxy.sh`](../../scripts/setup-nh3-egress-proxy.sh)
  (idempotent; writes `/etc/danted.conf`, enables the systemd service).

## How to use it

From any host in the WG/LAN (`10.100.0.0/16`), point the client at:

```
socks5h://10.100.10.50:1080
```

(the `h` = resolve DNS through the proxy). Examples:

```bash
curl --socks5-hostname 10.100.10.50:1080 https://api.ipify.org   # -> 70.230.226.88
yt-dlp --proxy socks5h://10.100.10.50:1080 -f bestaudio -g <url>
```

**Scope the proxy to only the gated calls.** Don't blanket-proxy a
whole service through it — large/un-gated transfers (model downloads,
bulk data) should go direct so they don't burn the residential line's
bandwidth. For yt-voice-clipper this means proxying the YouTube yt-dlp
calls only, not the whisperx/pyannote/HF model fetches.

## Caveats

- **Residential bandwidth is shared.** Every service pointed here egresses
  via one home broadband line. Watch aggregate volume / any data cap.
- **SPOF for whatever depends on it.** If nh3-dev or the proxy is down,
  every dependent service loses its un-gated egress. It's a convenience
  layer, not HA.
- **Reboot durability:** the systemd unit is enabled, but it must come up
  after `ens18` has `10.100.10.50` (dante fails to bind otherwise). If it
  doesn't start after a reboot, `systemctl restart danted` once the
  interface is up.

## Re-provision / change

Edit `scripts/setup-nh3-egress-proxy.sh` (the config is baked into it as
a heredoc — single source of truth), then re-run:

```bash
sudo bash scripts/setup-nh3-egress-proxy.sh
```

Verify: `systemctl is-active danted` and
`curl --socks5-hostname 10.100.10.50:1080 https://api.ipify.org`.