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

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

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.