tools/README.md

# Home Proxy Panel — give the Space *your* home IP

The TutorialMaker Space can't fetch transcripts or stream URLs from its datacenter IP
(YouTube blocks it). This tool runs a small **authenticated HTTP proxy on your computer**
(your home/residential IP) and exposes it through a **raw TCP tunnel**. You then paste the
resulting **proxy URL into the Space's *Your proxy URL* field** — the Space's YouTube
requests for *your* generation exit from *your* IP and stop getting blocked.

**Per-user by design:** every user runs their own panel and uses their own proxy URL for
their own generation, so there's no single shared residential proxy to run or bottleneck.
Combined with the per-user Hugging Face token the Space already asks for, each user is fully
self-served (their own compute + their own IP).

> **Just want to run it?** Grab the prebuilt **HomeProxyPanel** app for your OS (no Python
> needed) — see [build_panel.md](build_panel.md) for how the executables are produced. Or
> run the script directly per the steps below.

> **Owner note:** the **Set on Space (owner)** button writes the global `YT_PROXY` secret and
> only works if you have HF write access to the Space; end users don't need it — they use the
> *Your proxy URL* field instead.

> **Why a TCP tunnel (not Cloudflare/Tailscale):** a forward proxy speaks HTTP `CONNECT`,
> which only survives a transparent **TCP** tunnel. HTTP *reverse* tunnels (Cloudflare
> quick-tunnel, Tailscale Funnel) cannot carry it — use **ngrok TCP** or **bore**.

---

## 1. Install the Python deps

```bash
pip install -r tools/requirements.txt
```

## 2. Install a tunnel (pick ONE)

**Option A — ngrok (more reliable, free account):**
1. Sign up at <https://ngrok.com> (free).
2. Install the ngrok agent and put `ngrok` on your PATH
   (<https://ngrok.com/download>).
3. Copy your authtoken from the ngrok dashboard → you'll paste it into the panel.

**Option B — bore (no account, less reliable):**
1. Nothing to install — the panel **auto-downloads** the right `bore` binary for your OS on
   first use (into the folder next to the app). It uses the shared public `bore.pub` server.
2. (Optional) To pre-place it, download `bore` from
   <https://github.com/ekzhang/bore/releases> and put it on your PATH or next to the app.

## 3. Launch the panel

Prebuilt app (no Python): double-click **HomeProxyPanel** (see [build_panel.md](build_panel.md)).

Or from source:
```bash
python tools/home_proxy_panel.py
```

## 4. Use it (in order)

1. **Proxy port / user / password** are pre-filled (a random password is generated). Keep
   the password — it protects your public proxy from being used by strangers.
2. Pick the **Tunnel provider** (`ngrok`, `bore`, or `manual`). For ngrok, paste your
   **authtoken**.
3. Click **Start proxy** → it runs the forward proxy on `127.0.0.1:<port>`.
4. Click **Start tunnel** → the **Public endpoint** field fills in
   (`x.tcp.ngrok.io:NNNN` or `bore.pub:NNNN`) and **Your proxy URL** is computed.
5. Click **Test proxy** → in the log, the **egress IP should be your home IP** and YouTube
   should be **reachable**. If so, the proxy works.
6. Click **📋 Copy my Proxy URL**, then paste it into the TutorialMaker Space's **Your proxy
   URL** field and click **Generate**. Keep the panel running while you generate.
   - *(Space owner only)* **Set on Space (owner)** instead writes the global `YT_PROXY`
     secret for everyone — end users don't use this.

## 5. Verify on the Space

Paste your proxy URL into **Your proxy URL** and run a topic. **Check YouTube access** should
show your home IP as the egress, and the **transcript** and **screenshot** steps should
succeed instead of failing with an SSL/TLS block.

## Keep it running

The proxy + tunnel must stay running on your machine while the Space is in use. Close the
panel (or **Stop proxy/Stop tunnel**) when you're done — the `YT_PROXY` secret will then
point at a dead endpoint until you start it again (the Space falls back to text-only / a
clear error).

---

## Security notes

- The proxy is **public** while tunneled, so it **requires the username/password** — keep
  them non-trivial (use **New password** to rotate). Without the right credentials nobody
  can use your proxy.
- This routes YouTube traffic through your home connection and consumes your bandwidth.
- Stop the tunnel when not needed; rotate the password periodically.

## Manual endpoint (router port-forward / other tunnel)

If you forward a router port (and you're **not** behind CGNAT) or use another raw-TCP
tunnel, choose provider **`manual`** and enter the public `host:port`. The panel will
build the `YT_PROXY` URL and can set the secret + test it.

## Troubleshooting

- **`proxy.py` not found** → `pip install proxy.py`.
- **ngrok: no tcp tunnel** → ensure the authtoken is set; free TCP tunnels are supported
  but only one at a time — close other ngrok agents.
- **Test egress IP is *not* your home IP** → the tunnel/proxy chain is wrong; restart both.
- **YouTube still blocked on the Space** → confirm the secret value matches the panel's
  YT_PROXY URL exactly (including `user:pass@`), and that the panel is still running.