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 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

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).

Or from source:

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.