bgutil POT provider as one executable

Listenbox's packaging of Brainicism/bgutil-ytdlp-pot-provider: a Bun executable containing the JavaScript server, Canvas native addon, and its packaged shared libraries. The runtime host needs no Node.js, Bun, or installed JavaScript packages.

The approach is described in Single file JavaScript binaries with C++ dependencies.

Build

Build prerequisites: Node.js 22.18 or newer, Bun 1.4 or newer, nub, Bash, tar, and Git. Moon is optional for direct builds.

git clone --recurse-submodules https://github.com/listenbox/bgutil-pot-binary.git
cd bgutil-pot-binary
nub install
node build.ts linux
# Or build the macOS ARM64 target:
node build.ts macos

The upstream source is pinned by the submodule commit. Canvas prebuilds are pinned to version 3.2.3 and verified against SHA-256 digests. Build staging is temporary; upstream source is never patched in place.

moon run check

The local check runs the compiled Linux executable from an isolated directory, checks HTTP readiness and malformed requests, and terminates the process group. It does not contact YouTube. The optional live extractor check requires yt-dlp, the upstream Python plugin and a local cookie file:

node smoke.ts ./upstream /absolute/path/to/cookies.txt

Start the provider before running the live check. Cookie files are local inputs and must not be included in published artifacts.

Run

BGUTIL_POT_PROVIDER_BIND_LOOPBACK=1 ./bgutil-ytdlp-pot-provider-linux-amd64 --port 4416
curl --fail http://127.0.0.1:4416/healthz

/healthz maps to the upstream /ping endpoint. Oversized JSON requests receive a JSON 413 response. Enable loopback binding unless access is controlled by the deployment environment.

The executable extracts Canvas shared libraries to a fingerprinted temporary directory and relaunches itself once with TMPDIR pointing at that directory. Bun loads its embedded native addon alongside those files. The build also embeds jsdom's stylesheet and css-tree's JSON resources and removes jsdom's unused synchronous XHR worker resolver.

Single-file distribution does not eliminate host libc and system-library requirements. The supplied Dockerfile provides the Linux runtime libraries used by the original deployment:

docker build -t bgutil-pot-binary .
docker run --rm -p 127.0.0.1:4416:4416 bgutil-pot-binary

Ansible

The extracted role installs and supervises the executable with systemd, restricts it to loopback, and checks readiness. Create the service user and group before applying it, or override the role defaults with an existing unprivileged account.

ansible-galaxy collection install ansible.posix
ansible-playbook -i inventory.ini ansible/deploy.yaml

Use the pot_provider inventory group. Configuration is documented in ansible/roles/listenbox_pot_provider/meta/argument_specs.yaml. No Listenbox inventory or credentials are included.

License and attribution

GPL-3.0-only; see LICENSE. The provider is maintained upstream by Brainicism and contributors. This repository publishes Listenbox's build wrapper and deployment approach; the upstream submodule retains its own history and notices. Bundled third-party dependencies retain their respective licenses.