Per-user residential proxy: proxy URL field + downloadable Home Proxy Panel

- app.py: new per-request 'Your proxy URL' field (overrides YT_PROXY secret) threaded
through run_pipeline/check_access; intro links the Home Proxy Panel GitHub repo. Merged
onto the current media-proxy/probe-battery app.
- pipeline/transcribe.py: redact proxy credentials from error hints.
- tools/home_proxy_panel.py: end-user flow (Copy my Proxy URL), bore auto-download,
frozen (--run-proxy) PyInstaller support.
- tools/home_proxy_panel.spec + build_panel.md: standalone executable build.
- README + tools/README: how to compile + use the residential proxy with this Space
(repo: github.com/vivekchakraverty/tutorialmaker-home-proxy-panel).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -52,11 +52,32 @@ single best YouTube video on that topic. **No video download** — acquisition i
 ## Notes on YouTube access
 
 The transcript and the stream-URL resolution hit YouTube directly. From a datacenter IP
-(like a Space) these can occasionally be **blocked**:
+(like a Space) these are usually **blocked**. The fix is a **residential proxy** — and each
+user can bring their own.
 
-- If transcript/stream resolution fails, set the optional **`YT_PROXY`** secret (a
-  residential proxy) and/or **`YT_COOKIES`** (Netscape cookies.txt contents, raw or
-  base64) — used only as a thin fallback.
+### Recommended: run your own residential proxy (per user)
+
+Paste your own proxy URL into the **Your proxy URL** field so YouTube requests for *your*
+generation exit from *your* home IP. Get a proxy with the **Home Proxy Panel**:
+
+**GitHub:** <https://github.com/vivekchakraverty/tutorialmaker-home-proxy-panel>
+(also in [`tools/`](tools/) here).
+
+1. **Download** the prebuilt `HomeProxyPanel` app for your OS from the repo's Releases (no
+   Python needed), **or** run from source: `pip install -r tools/requirements.txt` then
+   `python tools/home_proxy_panel.py`.
+2. **Compile it yourself** (optional): `pip install pyinstaller` then
+   `pyinstaller tools/home_proxy_panel.spec` → `dist/HomeProxyPanel`. PyInstaller doesn't
+   cross-compile, so build on each OS (or use the repo's GitHub Actions matrix). Full details
+   in [`tools/build_panel.md`](tools/build_panel.md).
+3. **Use it:** Start proxy → Start tunnel (bore auto-downloads) → Test proxy →
+   **📋 Copy my Proxy URL** → paste into **Your proxy URL** above → **Generate**. Keep the
+   panel running during generation.
+
+### Fallbacks (owner)
+
+- Set the optional **`YT_PROXY`** secret (a shared residential proxy) and/or **`YT_COOKIES`**
+  (Netscape cookies.txt contents, raw or base64). The per-user field above overrides `YT_PROXY`.
 - If the stream URL can't be resolved, the Space still produces a **text-only** tutorial.
 
 ## Local run

app.py

@@ -104,8 +104,11 @@ def _cookiefile(workdir: str) -> str | None:
     return path
 
 
-def _resolve_proxy() -> str | None:
-    proxy = os.environ.get("YT_PROXY", "").strip()
+def _resolve_proxy(ui_proxy: str | None = None) -> str | None:
+    """A per-user proxy pasted in the UI wins over the shared YT_PROXY secret, so each
+    user can route through their own residential proxy (see tools/home_proxy_panel.py).
+    It also backs screenshot downloads (capture_shots falls back to it)."""
+    proxy = (ui_proxy or "").strip() or os.environ.get("YT_PROXY", "").strip()
     return proxy or None
 
 
@@ -122,14 +125,15 @@ def _resolve_api_key(ui_key: str | None) -> str | None:
     return key or None
 
 
-def check_access():
+def check_access(yt_proxy=None):
     """Health check: which secrets are set, the egress IP, and YouTube reachability."""
     import requests
 
-    proxy = _resolve_proxy()
+    proxy = _resolve_proxy(yt_proxy)
     proxies = {"http": proxy, "https": proxy} if proxy else None
+    src = "your proxy field" if (yt_proxy or "").strip() else "YT_PROXY secret"
     lines = [
-        f"- **Proxy** (`YT_PROXY`): {'set ✅' if proxy else 'not set ⚪'}",
+        f"- **Proxy**: {('set ✅ (' + src + ')') if proxy else 'not set ⚪'}",
         f"- **Media proxy** (`YT_MEDIA_PROXY`, screenshots): "
         f"{'set ✅' if _resolve_media_proxy() else 'not set ⚪ (falls back to YT_PROXY)'}",
         f"- **Cookies** (`YT_COOKIES`): {'set ✅' if os.environ.get('YT_COOKIES') else 'not set ⚪'}",
@@ -218,7 +222,7 @@ def _collect_keywords(primary_kw, secondary_kw) -> dict:
     return {"primary": primary, "secondary": secondary}
 
 
-def run_pipeline(topic, hf_token, yt_api_key, llm_model, vlm_model,
+def run_pipeline(topic, hf_token, yt_api_key, yt_proxy, llm_model, vlm_model,
                  w_llm, w_whisper, lead, max_shots, primary_kw, secondary_kw,
                  content_brief="", progress=gr.Progress()):
     """Generator yielding (status_md, ranking_df, transcript, docx_file)."""
@@ -239,9 +243,11 @@ def run_pipeline(topic, hf_token, yt_api_key, llm_model, vlm_model,
     try:
         api_key = _resolve_api_key(yt_api_key)
         cookiefile = _cookiefile(workdir)
-        proxy = _resolve_proxy()
+        proxy = _resolve_proxy(yt_proxy)
         if proxy:
-            log.append("🔐 `YT_PROXY` is set — transcript + stream requests route through it.")
+            # Never log the proxy URL itself — it carries user:pass credentials.
+            src = "your proxy" if (yt_proxy or "").strip() else "the `YT_PROXY` secret"
+            log.append(f"🔐 Routing transcript + screenshot requests through {src}.")
 
         # 1. Search ------------------------------------------------------------------
         progress(0.03, desc="Searching")
@@ -333,7 +339,12 @@ def build_ui():
             "Enter a topic, your **Hugging Face token** (LLM + vision model, billed to you) "
             "and a **YouTube Data API key** (for comments). The Space picks the best video by "
             "comment sentiment, pulls its transcript, writes an AEO-friendly tutorial, grabs "
-            "real screenshots at the right moments, and builds a **.docx**."
+            "real screenshots at the right moments, and builds a **.docx**.\n\n"
+            "> 🏠 **YouTube blocks this Space's datacenter IP.** Run your own residential proxy "
+            "with the **Home Proxy Panel** "
+            "([download / source](https://github.com/vivekchakraverty/tutorialmaker-home-proxy-panel)) "
+            "and paste its URL into **Your proxy URL** below — transcript + screenshots then route "
+            "through your home IP. Each user brings their own proxy."
         )
         with gr.Row():
             with gr.Column(scale=2):
@@ -342,6 +353,13 @@ def build_ui():
                                       placeholder="hf_…  (Inference Providers permission)")
                 yt_api_key = gr.Textbox(label="YouTube Data API key", type="password",
                                         placeholder="for comments (or set the YOUTUBE_API_KEY secret)")
+                yt_proxy = gr.Textbox(
+                    label="Your proxy URL (recommended)", type="password",
+                    placeholder="http://user:pass@bore.pub:12345  — from the Home Proxy Panel",
+                    info="Run the Home Proxy Panel (github.com/vivekchakraverty/"
+                         "tutorialmaker-home-proxy-panel) on your own machine and paste its "
+                         "proxy URL here so YouTube requests exit from your residential IP. "
+                         "Leave blank to use the Space's shared proxy, if configured.")
             with gr.Column(scale=1):
                 llm_model = gr.Dropdown(LLM_CHOICES, value=LLM_CHOICES[0],
                                         label="Tutorial LLM", allow_custom_value=True)
@@ -393,10 +411,10 @@ def build_ui():
         transcript_box = gr.Textbox(label="Transcript preview", lines=10, max_lines=20)
         docx_file = gr.File(label="Download tutorial (.docx)")
 
-        health_btn.click(check_access, outputs=health_md)
+        health_btn.click(check_access, inputs=[yt_proxy], outputs=health_md)
         run_btn.click(
             run_pipeline,
-            inputs=[topic, hf_token, yt_api_key, llm_model, vlm_model,
+            inputs=[topic, hf_token, yt_api_key, yt_proxy, llm_model, vlm_model,
                     w_llm, w_whisper, lead, max_shots, primary_kw, secondary_kw,
                     content_brief],
             outputs=[status_md, ranking_df, transcript_box, docx_file],

pipeline/transcribe.py

@@ -8,8 +8,17 @@ timestamps, which we normalize into ``{start, end, text}`` segments.
 """
 from __future__ import annotations
 
+import re
 import time
 
+# Strip credentials from any proxy URL that a library exception might echo, so a pasted
+# http://user:pass@host proxy never leaks into the UI/logs.
+_CRED_RE = re.compile(r"(https?://)[^/@\s]+@")
+
+
+def _redact(text: str) -> str:
+    return _CRED_RE.sub(r"\1", str(text))
+
 
 class TranscriptError(RuntimeError):
     """Raised when no usable transcript can be fetched (disabled, blocked, none)."""
@@ -94,7 +103,7 @@ def transcript_text(segs: list[dict]) -> str:
 
 def _hint(exc: Exception) -> str:
     name = type(exc).__name__
-    msg = str(exc)
+    msg = _redact(str(exc))
     low = (name + " " + msg).lower()
     # Check specific transcript states first (note: "transcripts" contains "ip").
     if "disabled" in low or "transcriptsdisabled" in low:

tools/README.md

@@ -1,10 +1,23 @@
-# Home Proxy Panel — give the Space your home IP
+# 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.
+(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
@@ -27,12 +40,16 @@ pip install -r tools/requirements.txt
 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.
+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
 ```
@@ -43,19 +60,21 @@ python tools/home_proxy_panel.py
    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>`.
+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 the **YT_PROXY URL** is computed.
+   (`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 **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.
+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
 
-Run a topic on the Space. The **transcript** and **screenshot** steps should now succeed
-instead of failing with an SSL/TLS block.
+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
 

tools/build_panel.md

@@ -0,0 +1,68 @@
+# Building the Home Proxy Panel as a standalone app
+
+This produces a **double-click executable** of `home_proxy_panel.py` so end users can run
+their own residential proxy **without installing Python**. Each user runs it, clicks
+**Copy my Proxy URL**, and pastes that URL into the TutorialMaker Space's *Your proxy URL*
+field — their generation then routes YouTube requests through their own home IP.
+
+## ⚠️ One binary per OS — PyInstaller does not cross-compile
+
+You must build **on each target OS** (Windows `.exe` on Windows, macOS binary on macOS,
+Linux ELF on Linux). Options:
+- Build on the three machines you have, or
+- Use a GitHub Actions matrix (`windows-latest`, `macos-latest`, `ubuntu-latest`) and
+  attach the artifacts to a Release. A ready starter workflow is in the section below.
+
+## Build steps (run on the target OS)
+
+```bash
+pip install pyinstaller proxy.py huggingface_hub requests
+# from the TutorialMaker repo root:
+pyinstaller tools/home_proxy_panel.spec
+```
+
+Output: `dist/HomeProxyPanel` (`.exe` on Windows). Ship that single file.
+
+Notes:
+- `proxy.py` (the forward proxy) is bundled. The app runs it by re-invoking itself with a
+  hidden `--run-proxy` flag, so it works even though `sys.executable` is the packaged app.
+- `bore` is **not** bundled by default — the app auto-downloads the correct release binary
+  for the host on first use (into the folder next to the executable). To bundle it instead
+  (offline installs), drop `bore`/`bore.exe` next to `home_proxy_panel.spec` before building
+  — the spec picks it up automatically.
+- `console=False` makes it a windowed GUI app. Set `console=True` in the spec temporarily if
+  you need to see tracebacks while debugging a build.
+
+## macOS gotchas
+- Unsigned apps are quarantined: users run `xattr -dr com.apple.quarantine HomeProxyPanel`
+  or right-click → Open the first time. For public distribution, codesign + notarize.
+
+## GitHub Actions matrix (optional starter)
+
+```yaml
+name: build-proxy-panel
+on: { workflow_dispatch: {} }
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install pyinstaller proxy.py huggingface_hub requests
+      - run: pyinstaller tools/home_proxy_panel.spec
+      - uses: actions/upload-artifact@v4
+        with:
+          name: HomeProxyPanel-${{ matrix.os }}
+          path: dist/*
+```
+
+## Verify a built binary
+On a machine **without** Python:
+1. Launch `HomeProxyPanel`.
+2. **Start proxy** → **Start tunnel** (bore auto-downloads on first use) → **Test proxy**:
+   the log's egress IP should be your home IP and YouTube should be reachable.
+3. **Copy my Proxy URL**, paste it into the Space's *Your proxy URL* field, and generate.

tools/home_proxy_panel.py

@@ -16,17 +16,100 @@ from __future__ import annotations
 
 import json
 import os
+import platform
 import queue
 import re
 import secrets
+import shutil
 import subprocess
 import sys
+import tarfile
 import threading
+import zipfile
 
 CONFIG_PATH = os.path.join(os.path.expanduser("~"), ".tutorialmaker_proxy.json")
 DEFAULT_REPO = "vivekchakraverty/TutorialMaker"
 _NO_WINDOW = 0x08000000 if os.name == "nt" else 0
 
+# Where to keep a downloaded bore binary. When frozen by PyInstaller sys.frozen is set and
+# the binary lives next to the executable; otherwise next to this script.
+APP_DIR = os.path.dirname(sys.executable if getattr(sys, "frozen", False)
+                          else os.path.abspath(__file__))
+
+
+def _bore_target_triple() -> tuple[str, str, str] | None:
+    """(rust-triple, archive-ext, binary-name) for the current OS/arch, or None."""
+    sysname = platform.system()
+    mach = platform.machine().lower()
+    is_arm = mach in ("arm64", "aarch64")
+    if sysname == "Windows":
+        return ("x86_64-pc-windows-msvc", ".zip", "bore.exe")
+    if sysname == "Darwin":
+        triple = "aarch64-apple-darwin" if is_arm else "x86_64-apple-darwin"
+        return (triple, ".tar.gz", "bore")
+    if sysname == "Linux":
+        triple = "aarch64-unknown-linux-musl" if is_arm else "x86_64-unknown-linux-musl"
+        return (triple, ".tar.gz", "bore")
+    return None
+
+
+def ensure_bore(log=lambda m: None) -> str | None:
+    """Return a runnable bore path: PATH copy, a previously downloaded one, or a freshly
+    downloaded release binary for this OS/arch. Returns None if it can't be obtained."""
+    found = shutil.which("bore")
+    if found:
+        return found
+    tri = _bore_target_triple()
+    if not tri:
+        log("[bore] no prebuilt binary for this platform — install bore manually.")
+        return None
+    triple, ext, binname = tri
+    local = os.path.join(APP_DIR, binname)
+    if os.path.exists(local):
+        return local
+
+    import urllib.request
+    api = "https://api.github.com/repos/ekzhang/bore/releases/latest"
+    try:
+        log("[bore] not found — fetching latest release info…")
+        req = urllib.request.Request(api, headers={"User-Agent": "tutorialmaker-panel"})
+        with urllib.request.urlopen(req, timeout=30) as r:
+            rel = json.load(r)
+        asset = next((a for a in rel.get("assets", [])
+                      if triple in a["name"] and a["name"].endswith(ext)), None)
+        if not asset:
+            log(f"[bore] no asset matching {triple}{ext} in the latest release.")
+            return None
+        url = asset["browser_download_url"]
+        archive = os.path.join(APP_DIR, asset["name"])
+        log(f"[bore] downloading {asset['name']}…")
+        dl = urllib.request.Request(url, headers={"User-Agent": "tutorialmaker-panel"})
+        with urllib.request.urlopen(dl, timeout=120) as resp, open(archive, "wb") as fh:
+            shutil.copyfileobj(resp, fh)
+        if ext == ".zip":
+            with zipfile.ZipFile(archive) as z:
+                z.extract(binname, APP_DIR)
+        else:
+            with tarfile.open(archive) as t:
+                member = next((m for m in t.getmembers()
+                               if os.path.basename(m.name) == binname), None)
+                if member is None:
+                    log("[bore] archive did not contain the bore binary.")
+                    return None
+                member.name = binname
+                t.extract(member, APP_DIR)
+        try:
+            os.remove(archive)
+        except OSError:
+            pass
+        if os.name != "nt":
+            os.chmod(local, 0o755)
+        log(f"[bore] ready at {local}")
+        return local
+    except Exception as exc:
+        log(f"[bore] download failed: {type(exc).__name__}: {str(exc)[:160]}")
+        return None
+
 
 # ----------------------------------------------------------------- pure helpers (tested)
 def build_proxy_url(host: str, port, user: str, pw: str) -> str:
@@ -213,8 +296,14 @@ def main():
 
     # --- proxy ---
     def start_proxy():
-        cmd = [sys.executable, "-m", "proxy", "--hostname", "127.0.0.1",
-               "--port", port.get(), "--basic-auth", f"{user.get()}:{pw.get()}"]
+        auth = f"{user.get()}:{pw.get()}"
+        pargs = ["--hostname", "127.0.0.1", "--port", port.get(), "--basic-auth", auth]
+        if getattr(sys, "frozen", False):
+            # In a PyInstaller build sys.executable is THIS app, not python, so `-m proxy`
+            # won't work — re-invoke ourselves with the --run-proxy sentinel (see __main__).
+            cmd = [sys.executable, "--run-proxy", *pargs]
+        else:
+            cmd = [sys.executable, "-m", "proxy", *pargs]
         proxy_proc.start(cmd)
         status_var.set("proxy starting…")
 
@@ -239,7 +328,19 @@ def main():
             tunnel_proc.start(["ngrok", "tcp", port.get(), "--log", "stdout"])
             root.after(2500, _grab_ngrok)
         elif prov == "bore":
-            tunnel_proc.start(["bore", "local", port.get(), "--to", "bore.pub"])
+            status_var.set("preparing bore…")
+            def work():
+                bore = ensure_bore(log)
+                if not bore:
+                    log("[tunnel] bore unavailable — download bore.exe from "
+                        "https://github.com/ekzhang/bore/releases or pick ngrok.")
+                    status_var.set("bore unavailable")
+                    return
+                root.after(0, lambda: tunnel_proc.start(
+                    [bore, "local", port.get(), "--to", "bore.pub"]))
+                status_var.set("tunnel starting…")
+            threading.Thread(target=work, daemon=True).start()
+            return
         status_var.set("tunnel starting…")
 
     def _grab_ngrok():
@@ -320,15 +421,16 @@ def main():
         ttk.Button(btns, text=txt, command=fn).pack(side="left", **pad)
 
     btns2 = ttk.Frame(root); btns2.pack(fill="x", **pad)
-    for txt, fn in [("Test proxy", do_test), ("Set YT_PROXY on Space", do_set_secret),
-                    ("Copy YT_PROXY URL", copy_url), ("Save config", save_cfg),
-                    ("New password", lambda: pw.set(secrets.token_urlsafe(10)))]:
+    for txt, fn in [("📋 Copy my Proxy URL", copy_url), ("Test proxy", do_test),
+                    ("Save config", save_cfg),
+                    ("New password", lambda: pw.set(secrets.token_urlsafe(10))),
+                    ("Set on Space (owner)", do_set_secret)]:
         ttk.Button(btns2, text=txt, command=fn).pack(side="left", **pad)
 
     info = ttk.Frame(root); info.pack(fill="x", **pad)
     ttk.Label(info, text="Public endpoint:").grid(row=0, column=0, sticky="w", **pad)
     ttk.Label(info, textvariable=endpoint_var, foreground="#0a7").grid(row=0, column=1, sticky="w", **pad)
-    ttk.Label(info, text="YT_PROXY URL:").grid(row=1, column=0, sticky="w", **pad)
+    ttk.Label(info, text="Your proxy URL:").grid(row=1, column=0, sticky="w", **pad)
     ttk.Entry(info, textvariable=yturl_var, width=70, state="readonly").grid(row=1, column=1, sticky="w", **pad)
     ttk.Label(info, text="Status:").grid(row=2, column=0, sticky="w", **pad)
     ttk.Label(info, textvariable=status_var, foreground="#06c").grid(row=2, column=1, sticky="w", **pad)
@@ -355,11 +457,21 @@ def main():
         proxy_proc.stop(); tunnel_proc.stop(); root.destroy()
 
     root.protocol("WM_DELETE_WINDOW", on_close)
-    log("Ready. 1) Start proxy  2) Start tunnel  3) Test proxy  4) Set YT_PROXY on Space.")
+    log("Ready. 1) Start proxy  2) Start tunnel  3) Test proxy  4) Copy my Proxy URL")
+    log("     → paste that URL into the TutorialMaker Space's 'Your proxy URL' field, then Generate.")
     log("Tip: 'Test proxy' egress IP should be your HOME IP, and YouTube should be reachable.")
+    log("(bore auto-downloads on first use; 'Set on Space (owner)' is only for the Space owner.)")
     poll()
     root.mainloop()
 
 
 if __name__ == "__main__":
-    main()
+    # Frozen (PyInstaller) re-entry: act as `python -m proxy` when asked, so the packaged
+    # executable can run the forward proxy as a normal killable subprocess of itself.
+    if "--run-proxy" in sys.argv:
+        _i = sys.argv.index("--run-proxy")
+        import proxy
+        sys.argv = ["proxy", *sys.argv[_i + 1:]]
+        proxy.main()
+    else:
+        main()

tools/home_proxy_panel.spec

@@ -0,0 +1,57 @@
+# PyInstaller spec for the TutorialMaker Home Proxy Panel.
+#
+# Build (on the SAME OS you want to target — PyInstaller does NOT cross-compile):
+#     pip install pyinstaller proxy.py huggingface_hub requests
+#     pyinstaller tools/home_proxy_panel.spec
+# Output: dist/HomeProxyPanel(.exe)
+#
+# The forward proxy (proxy.py) is bundled and launched by the app re-invoking itself with
+# the --run-proxy sentinel (see the __main__ guard in home_proxy_panel.py). `bore` is NOT
+# bundled here — the app downloads the correct release binary for the host on first use;
+# to ship it inside the exe instead, drop a `bore`/`bore.exe` next to this spec and add it
+# to `datas` below.
+import os
+
+block_cipher = None
+
+# SPECPATH is injected by PyInstaller = the directory holding this spec (…/tools).
+_here = SPECPATH
+_script = os.path.join(_here, "home_proxy_panel.py")
+_bore = "bore.exe" if os.name == "nt" else "bore"
+_bore_path = os.path.join(_here, _bore)
+datas = [(_bore_path, ".")] if os.path.exists(_bore_path) else []
+
+a = Analysis(
+    [_script],
+    pathex=[_here],
+    binaries=[],
+    datas=datas,
+    # proxy.py loads its plugins by dotted path at runtime, so PyInstaller's static
+    # analysis misses them — pull the whole package in.
+    hiddenimports=["proxy"],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    cipher=block_cipher,
+)
+# Ensure proxy.py's data/plugin modules are collected.
+try:
+    from PyInstaller.utils.hooks import collect_submodules, collect_data_files
+    a.hiddenimports += collect_submodules("proxy")
+    a.datas += collect_data_files("proxy")
+except Exception:
+    pass
+
+pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
+
+exe = EXE(
+    pyz, a.scripts, a.binaries, a.zipfiles, a.datas, [],
+    name="HomeProxyPanel",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    runtime_tmpdir=None,
+    console=False,  # windowed GUI app (no console)
+)