Documentation Index
Fetch the complete documentation index at: https://mintlify.com/coah80/yoink/llms.txt
Use this file to discover all available pages before exploring further.
Yoink reads all configuration from environment variables at startup via the config.Load() function. Place these in a .env file at the working directory — the server loads it automatically using godotenv. Variables not set fall back to the defaults listed below.
Core settings
| Variable | Default | Description |
|---|
PORT | 3001 | TCP port the HTTP server listens on. |
NODE_ENV | development | Environment mode. Set to production in live deployments to enable production-specific behaviour. |
Security
If BOT_SECRET is not set, all /api/bot/* endpoints are completely unprotected and accessible by anyone who can reach your server. The server logs a [WARN] message on startup when this variable is missing. Always set this in production.
| Variable | Default | Description |
|---|
BOT_SECRET | (none) | Shared secret that the Discord bot sends with every request to /api/bot/*. Requests without a matching Authorization header are rejected. |
Cobalt API
COBALT_APIS accepts a comma-separated list of base URLs. Yoink will use these as fallback endpoints when yt-dlp fails or hits YouTube bot detection. Specifying multiple instances provides redundancy — if one is down or rate-limited, the next is tried.
| Variable | Default | Description |
|---|
COBALT_APIS | https://co.eepy.today | Comma-separated list of Cobalt API base URLs used as the YouTube fast-path and final fallback. Example: https://co.eepy.today,https://your-own-cobalt.example.com |
COBALT_API_KEY | (none) | API key to include when making requests to Cobalt API instances that require authentication. |
YouTube session tokens
Yoink runs a background goroutine that periodically fetches fresh YouTube session tokens (PO tokens + visitor data) from a session generator service. This helps avoid bot detection on YouTube downloads.
| Variable | Default | Description |
|---|
SESSION_GENERATOR_URL | http://localhost:8080 | Base URL of the session token generator service. Compatible with both yt-session-generator (GET /token) and bgutil-ytdlp-pot-provider (POST /get_pot) formats. |
SESSION_TOKEN_REFRESH_MIN | 15 | How often, in minutes, to refresh session tokens. Must be at least 1; values below 1 are clamped to 15. |
Transcription
| Variable | Default | Description |
|---|
OPENAI_API_KEY | (none) | OpenAI API key for cloud-based Whisper transcription. When set, Yoink can use OpenAI’s large Whisper model via the API instead of running a local model. |
WHISPER_SCRIPT | (auto-detected) | Explicit path to the whisper.py script used for local transcription. If not set, Yoink attempts to locate it automatically. Requires python3 with the whisper module installed. |
Proxy settings
These variables configure rotating HTTP proxies for YouTube downloads. See the Proxies page for full details on how proxy rotation works.
| Variable | Default | Description |
|---|
PROXY_HOST | (none) | Hostname of your proxy provider. |
PROXY_PORT | 80 | Port number for proxy connections. |
PROXY_USER_PREFIX | (none) | Username prefix used in proxy authentication. Many residential proxy providers use this for session and country targeting (e.g. user-country-us). |
PROXY_PASSWORD | (none) | Password for proxy authentication. |
PROXY_COUNT | 0 | Number of proxy endpoints available for rotation. Yoink selects a random number between 1 and this value to build each proxy URL. Set to 0 to disable proxies. |
Proxies are only activated when all four of PROXY_HOST, PROXY_USER_PREFIX, PROXY_PASSWORD, and PROXY_COUNT are set. Any missing value disables the proxy feature entirely.
Discord alerts
When DISCORD_WEBHOOK_URL is set, Yoink sends error alerts (such as session token failures) to the specified webhook. This is entirely optional.
| Variable | Default | Description |
|---|
DISCORD_WEBHOOK_URL | (none) | Webhook URL for error notifications. Setting this enables Discord alerts. Leave unset to disable. |
DISCORD_PING_USER_ID | (none) | Discord user ID (snowflake) to @mention in alert messages, so the right person gets notified. |
| Variable | Default | Description |
|---|
EXTRACTOR_URL | http://localhost:3099 | URL of the JavaScript extractor sidecar service. Used for sites that require browser-side JavaScript extraction. |
Rate limiting
Rate limiting is configured in code rather than via environment variables. For reference, the defaults baked into config.go are:
| Constant | Value | Description |
|---|
RateLimitMax | 60 | Maximum requests per window per IP. |
RateLimitWindow | 60s | Rolling time window for rate limit tracking. |
MaxJobsPerClient | 3 | Maximum concurrent active jobs per client. |
MaxQueueSize | 50 | Maximum number of jobs waiting in the queue. |
Example .env file
# Core
PORT=3001
NODE_ENV=production
# Security
BOT_SECRET=your-strong-random-secret-here
# Cobalt API fallback
COBALT_APIS=https://co.eepy.today,https://cobalt.your-domain.com
# YouTube session tokens
SESSION_GENERATOR_URL=http://localhost:8080
SESSION_TOKEN_REFRESH_MIN=15
# Transcription (choose one or both)
OPENAI_API_KEY=sk-...
# Proxies (all four required to enable)
PROXY_HOST=proxy.provider.com
PROXY_PORT=10000
PROXY_USER_PREFIX=user-country-us-session
PROXY_PASSWORD=yourpassword
PROXY_COUNT=100
# Discord alerts (optional)
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
DISCORD_PING_USER_ID=123456789012345678
