Skip to main content
The Native Helper is a lightweight Rust binary that runs locally and communicates with the MasterSelects web app over WebSocket and HTTP. It handles the capabilities that browsers cannot provide on their own.

​
When you need it

Firefox project storage

Firefox does not support the File System Access API. The Native Helper provides an equivalent file system layer so Firefox users can save and load projects.

Video downloads

Downloads from YouTube, TikTok, Instagram, Twitter/X, Vimeo, and all other yt-dlp-supported platforms. Requires yt-dlp installed on PATH.

External AI agent bridge

Exposes a local HTTP endpoint so external agents (Claude Code, curl scripts, etc.) can drive the running editor session.

Native FFmpeg paths

Protocol types for native FFmpeg decode and encode paths are defined in the browser client. These are planned future functionality and are not yet implemented in the current Rust server.

​
Architecture

Browser (MasterSelects)
    │
    ├── WebSocket  ws://127.0.0.1:9876
    └── HTTP       http://127.0.0.1:9877
            │
        Native Helper (Rust)
            │
            ├── yt-dlp subprocess
            ├── Local file system
            └── AI tool forwarding

​
Installation

​
Download a pre-built binary (recommended)

Click the Turbo indicator in the MasterSelects toolbar (or visit GitHub Releases) to download the latest build for your platform.
  • Linux / macOS: chmod +x masterselects-helper && ./masterselects-helper
  • Windows: Run the MSI installer; the helper launches automatically or run masterselects-helper.exe manually.

​
Build from source

Building from source requires Rust to be installed. On Windows, you also need the FFMPEG_DIR and LIBCLANG_PATH environment variables set to your FFmpeg and LLVM installations before running the build. See tools/native-helper/README.md for the full Windows setup.
cd tools/native-helper
cargo run --release

​
Command-line options

masterselects-helper [OPTIONS]

Options:
  -p, --port <PORT>              WebSocket port [default: 9876]
      --background               Run in background with minimal output
      --allowed-origins <LIST>   Comma-separated allowed origins (empty = all localhost)
      --generate-token           Print auth token and exit
      --log-level <LEVEL>        trace / debug / info / warn / error [default: info]
      --console                  Console mode (Windows; Linux/macOS always use console)
  -h, --help                     Print help
  -V, --version                  Print version

​
Ports

PortProtocolPurpose
9876WebSocketMain command channel
9877HTTPFile serving and AI tool bridge
HTTP port is always WebSocket port + 1.

​
Connecting

Once running, the MasterSelects toolbar shows Turbo when the helper is detected. Click the indicator to see the helper version, yt-dlp status, and download directory. If the indicator is missing, check that:
  1. The helper process is running (ps aux | grep masterselects-helper on Linux/macOS).
  2. Port 9876 is not blocked by a firewall (ss -tlnp | grep 9876).
  3. No other instance of the helper is already running.

​
AI bridge

The HTTP server on port 9877 exposes a POST /api/ai-tools endpoint. External agents can call this to execute actions in the connected editor session: 
curl -X POST http://127.0.0.1:9877/api/ai-tools \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <startup-token>" \
  -d '{"tool":"_list","args":{}}'
The startup token is printed to the helper’s console output at launch. A connected MasterSelects tab must be open and registered for tool calls to be forwarded.

​
Security

  • Localhost only — binds to 127.0.0.1, not exposed to the network
  • Origin validation — only accepts connections from allowed origins (defaults to all localhost origins)
  • Bearer token — a random token is generated at each startup; both HTTP and WebSocket bridge operations require it
  • No external network access — the helper only accesses the local file system and the yt-dlp subprocess
For the full security model see Security.

​
Platform notes

PlatformNotes
LinuxAlways runs in console mode. Enable Vulkan in Chrome for 60 fps: chrome://flags/#enable-vulkan
macOSConsole mode. Make the binary executable before running.
WindowsRuns as a system tray app by default. Use --console to see log output. Requires FFMPEG_DIR and LIBCLANG_PATH to build from source. MSI installer available on GitHub Releases.

Build docs developers (and LLMs) love

Get started for freeTalk to us