tools/build_panel.md

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)

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)

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.