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)

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