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**, then sets it as the
Space's **`YT_PROXY`** secret. The Space's YouTube requests then exit from *your* IP and
stop getting blocked.

> **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. Download `bore.exe` from <https://github.com/ekzhang/bore/releases> and put it on your
   PATH (or in this folder).
2. That's it — it uses the shared public `bore.pub` server.

## 3. Launch the panel

```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 `proxy.py` 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 the **YT_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 **Set YT_PROXY on Space** → it writes the `YT_PROXY` secret to your Space
   (auto-detecting your HF token, or paste one). The Space restarts and picks it up.
   - Or click **Copy YT_PROXY URL** and paste it into the Space's secret manually.

## 5. Verify on the Space

Run a topic on the Space. The **transcript** and **screenshot** steps should now 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.