BgUtils POT Provider (Rust Implementation)

A high-performance YouTube POT (Proof-of-Origin Token) provider implemented in Rust, designed to help yt-dlp bypass the "Sign in to confirm you're not a bot" restrictions with improved performance and reliability.

[!CAUTION] Providing a POT token does not guarantee bypassing 403 errors or bot checks, but it may help your traffic seem more legitimate.

This Rust implementation uses LuanRT's BotGuard interfacing library through the rustypipe-botguard crate to generate authentic POT tokens, helping bypass YouTube's bot detection when using yt-dlp from flagged IP addresses. See the PO Token Guide for technical details.

Why Rust?

This Rust rewrite offers significant improvements over the original TypeScript version:

• 📦 Easy Deployment: Single binary with no runtime dependencies
• 🚀 Performance: Sub-second token generation with optimized caching
• 💾 Memory Efficiency: Lower memory footprint and better resource management
• 🔒 Reliability: Memory safety and robust error handling
• 🌐 Cross-Platform: Native support for Linux, Windows, and macOS

Architecture Overview

The system consists of two main components working together:

yt-dlp
  ↓ (via POT plugin)
Python Plugin
  ↓ HTTP API calls or CLI calls
Rust POT Provider
  ↓ BotGuard integration
YouTube BotGuard API
  ↓ returns POT Token
yt-dlp (bypasses bot check)

Core Components

1. Rust POT Provider (this project): Two operation modes:

   • HTTP Server Mode (bgutil-pot server): Always-running REST API service (recommended)
   • Script Mode (bgutil-pot): Per-request command-line execution

2. Python Plugin: Integrates with yt-dlp's POT framework to automatically fetch tokens from the provider.

Installation

Prerequisites

1. yt-dlp: Version 2025.05.22 or above
2. System Requirements:
   • Linux (x86_64), Windows (x86_64), or macOS (Intel/Apple Silicon)
   • 512MB available memory
   • Stable internet connection

Step 1: Install the Rust POT Provider

Option A: Pre-compiled Binaries (Recommended)

Download the latest release from GitHub Releases:

# Download the binary for your platform
# Example for Linux x86_64:
wget https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs/releases/latest/download/bgutil-pot-linux-x86_64

# Make executable and move to PATH
chmod +x bgutil-pot-linux-x86_64
sudo mv bgutil-pot-linux-x86_64 /usr/local/bin/bgutil-pot

Option B: Build from Source

Requirements: Rust 1.85+ (edition 2024) and Cargo

git clone https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs.git
cd bgutil-ytdlp-pot-provider-rs

# Option 1: Build only (binaries in target/release/)
cargo build --release

# Option 2: Build and install to ~/.cargo/bin (recommended)
cargo install --path .

Option C: Container (Docker/Podman)

• Run the prebuilt container image

  podman run -p 4416:4416 ghcr.io/jim60105/bgutil-pot:latest
  

• Or build your own container image

  # Build the container image
  podman build -t bgutil-pot .
  
  # Run the container (basic usage)
  podman run -p 4416:4416 bgutil-pot
  
  # Run with custom configuration
  podman run -p 8080:4416 -e RUST_LOG=debug bgutil-pot server --host 0.0.0.0 --port 4416
  
  # Using Docker instead of Podman
  docker build -f Containerfile -t bgutil-pot .
  docker run -p 4416:4416 bgutil-pot
  

[!NOTE]
The Containerfile is designed for SELinux-enabled systems. On non-SELinux systems, remove the ,z flags from --mount options.

Step 2: Install the yt-dlp Plugin

1. Download the latest plugin zip from GitHub Releases (bgutil-ytdlp-pot-provider-rs.zip)
2. Extract to one of the yt-dlp plugin directories

~/yt-dlp-plugins
└── bgutil-ytdlp-pot-provider
    ├── pyproject.toml
    └── yt_dlp_plugins
        └── extractor
            ├── getpot_bgutil_cli.py
            ├── getpot_bgutil_http.py
            └── getpot_bgutil.py

[!IMPORTANT]
This plugin is different from the upstream TypeScript implementation. If you have an existing bgutil-ytdlp-pot-provider folder from the original project, please remove it first to avoid conflicts before installing this Rust version.

Usage

HTTP Server Mode (Recommended)

The HTTP server mode provides the best performance and user experience.

1. Start the POT Provider Server

# Using default settings (binds to [::]:4416, IPv6 with IPv4 fallback)
./bgutil-pot server

# Custom port
./bgutil-pot server --port 8080

# Custom host address
./bgutil-pot server --host 127.0.0.1 --port 4416

# With verbose logging
./bgutil-pot server --verbose

Server Command Line Options:

• --host <HOST>: Host address to bind to (default: ::)
• --port <PORT>: Listen port (default: 4416)
• --verbose: Enable verbose logging

Server API Endpoints

The HTTP server provides the following REST API endpoints:

• POST /get_pot: Generate a new POT token
• GET /ping: Health check endpoint
• POST /invalidate_caches: Clear all internal caches
• POST /invalidate_it: Invalidate integrity tokens
• GET /minter_cache: Get minter cache status

2. Use with yt-dlp

Once the server is running, yt-dlp will automatically detect and use it:

# Standard usage - works automatically with default settings
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

# If using a custom port, specify the base URL
yt-dlp --extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080" "VIDEO_URL"

# If tokens stop working, try legacy mode
yt-dlp --extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:4416;disable_innertube=1" "VIDEO_URL"

Script Mode

For occasional use or environments where running a persistent service is not desired:

1. Generate POT Token Manually

# Generate token for a specific video
./bgutil-pot --content-binding "VIDEO_ID"

# With proxy support
./bgutil-pot --content-binding "VIDEO_ID" --proxy "http://proxy.example.com:8080"

# Bypass cache to force new token generation
./bgutil-pot --content-binding "VIDEO_ID" --bypass-cache

# With verbose logging
./bgutil-pot --content-binding "VIDEO_ID" --verbose

Generate Command Line Options:

• --content-binding <CONTENT_BINDING>: Content binding (video ID, visitor data, etc.)
• --proxy <PROXY>: Proxy server URL (format: http://host:port, socks5://host:port, etc.)
• --bypass-cache: Bypass cache and force new token generation
• --source-address <SOURCE_ADDRESS>: Source IP address for outbound connections
• --disable-tls-verification: Disable TLS certificate verification
• --verbose: Enable verbose logging
• --version: Show version information

2. Integrate with yt-dlp

# Specify the script path for yt-dlp integration
yt-dlp --extractor-args "youtubepot-bgutilscript:script_path=/path/to/bgutil-pot" "VIDEO_URL"

Configuration

Both modes support comprehensive configuration via:

1. Command line arguments (highest priority)
2. Environment variables
3. Configuration file
4. Default values (lowest priority)

Environment Variables:

Configuration File Example (config.toml):

[server]
host = "::"
port = 4416
timeout = 30
enable_cors = true

[token]
ttl_hours = 6
enable_cache = true
max_cache_entries = 1000

[botguard]
request_key = "O43z0dpjhgX20SCx4KAo"
enable_vm = true
vm_timeout = 30
disable_innertube = false

[network]
connect_timeout = 30
request_timeout = 60
max_retries = 3
user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

[logging]
level = "info"
verbose = false
format = "text"

[cache]
enable_file_cache = true
memory_cache_size = 100
enable_compression = false

Example usage with environment variables:

# Set logging level
export RUST_LOG=debug
./bgutil-pot server

# Multiple settings
RUST_LOG=debug ./bgutil-pot --content-binding "VIDEO_ID"

Proxy Support

Both modes support proxy configuration:

# HTTP/HTTPS proxy
--proxy "http://proxy.example.com:8080"

# SOCKS5 proxy
--proxy "socks5://proxy.example.com:1080"

# Proxy with authentication
--proxy "http://user:pass@proxy.example.com:8080"

Verification

To verify the plugin installation, check yt-dlp's verbose output:

yt-dlp -v "https://www.youtube.com/watch?v=VIDEO_ID"

You should see output similar to:

[debug] [youtube] [pot] PO Token Providers: bgutil:http-1.2.2 (external), bgutil:script-1.2.2 (external)

Troubleshooting

Common Issues

POT tokens not working

If tokens stop working, try the following in order:

1. Restart the provider: Stop and restart the HTTP server or regenerate tokens with --bypass-cache
2. Check your IP: Your IP might be flagged. Try using a different network or proxy
3. Legacy mode: Add disable_innertube=1 to extractor arguments
4. Update software: Ensure you're using the latest versions of both this provider and yt-dlp

Connection issues

# Check if the server is running (HTTP mode)
curl http://127.0.0.1:4416/ping

# Test with verbose logging
./bgutil-pot server --verbose

# Test script mode
./bgutil-pot --content-binding "test" --verbose

Plugin not detected

Verify the plugin installation:

yt-dlp -v "https://www.youtube.com/watch?v=dQw4w9WgXcQ" 2>&1 | grep -i "pot"

Should show: [debug] [youtube] [pot] PO Token Providers: bgutil:http-...

Performance Tips

• Use HTTP server mode for better performance and resource usage
• Configure appropriate cache TTL (default 6 hours) based on your usage patterns
• Use proxy rotation if making many requests from the same IP
• Monitor memory usage - the server typically uses <50MB RAM

Environment Variables

Contributing

This project welcomes contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs.git
cd bgutil-ytdlp-pot-provider-rs

# Install development dependencies
cargo build

# Run tests
cargo nextest run

# Run quality checks
./scripts/quality_check.sh

Acknowledgments

• LuanRT for the BgUtils library
• ThetaDev for the Rust implementation of POT Generator
• Brainicism for the original TypeScript implementation
• The yt-dlp team for the excellent POT provider framework

LICENSE

[!CAUTION]
A GPLv3 licensed Containerfile means that you MUST distribute the source code with the same license, if you

• Re-distribute the image. (You can simply point to this GitHub repository if you doesn't made any code changes.)
• Distribute an image that uses code from this repository.
• Or distribute an image based on this image. (FROM ghcr.io/jim60105/bgutil-pot in your Containerfile)

"Distribute" means to make the image available for other people to download, usually by pushing it to a public registry. If you are solely using it for your personal purposes, this has no impact on you.

Please consult the LICENSE for more details.

GNU GENERAL PUBLIC LICENSE Version 3

Copyright (C) 2024 Jim Chen Jim@ChenJ.im, Brian Le brainicism@gmail.com.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.