Skip to main content

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.

YouTube aggressively rate-limits and bot-checks IP addresses that make automated download requests. When a self-hosted Yoink instance starts hitting these limits, yt-dlp will begin failing with errors like "Sign in to confirm you're not a bot". Rotating HTTP proxies give each download request a fresh residential IP, making it indistinguishable from ordinary browser traffic.

​
How Yoink uses proxies

Proxies in Yoink are scoped to YouTube downloads only — other sites are downloaded directly without a proxy. The full fallback chain for a YouTube request is:
1

Try yt-dlp directly

Yoink first attempts the download with yt-dlp using YouTube session tokens (PO token + visitor data) for authentication. No proxy is used at this stage.
2

Retry with a proxy

If yt-dlp fails and a proxy is configured, Yoink retries the same download with a randomly selected proxy URL injected via --proxy. A new random proxy instance is picked for each attempt.
3

Fall back to Cobalt API

If the proxy attempt also fails — or if no proxy is configured — Yoink falls back to the Cobalt API. This final fallback is always available regardless of proxy configuration.
The Cobalt API fallback is always present even without any proxy configuration. Proxies extend the yt-dlp path before reaching Cobalt — they do not replace the fallback.

​
Proxy URL format

Yoink constructs a proxy URL for each download request using this format, drawn directly from internal/util/proxy.go: 
http://{PROXY_USER_PREFIX}-{N}:{PROXY_PASSWORD}@{PROXY_HOST}:{PROXY_PORT}
Where {N} is a randomly selected integer between 1 and PROXY_COUNT (inclusive). This matches the session-based username pattern used by major residential proxy providers — the number suffix selects a specific proxy endpoint or geographic session. For example, with the configuration below, a generated URL might look like: 
http://user-country-us-session-42:hunter2@proxy.provider.com:10000
Proxy selection is performed by GetRandomProxyURL() in internal/util/proxy.go, which uses crypto/rand for secure random number generation.

​
Configuration

All four proxy variables must be set for proxy support to activate. If any one of PROXY_HOST, PROXY_USER_PREFIX, PROXY_PASSWORD, or PROXY_COUNT is missing or empty, HasProxy() returns false and yt-dlp runs without a proxy. 
# .env
PROXY_HOST=proxy.provider.com
PROXY_PORT=10000
PROXY_USER_PREFIX=user-country-us-session
PROXY_PASSWORD=yourpassword
PROXY_COUNT=100
VariableDescription
PROXY_HOSTHostname of the proxy provider’s endpoint.
PROXY_PORTPort number. Defaults to 80 if not set.
PROXY_USER_PREFIXUsername prefix. The random session index is appended as -{N}.
PROXY_PASSWORDProxy authentication password.
PROXY_COUNTTotal number of proxy endpoints to rotate across. Yoink selects N in the range [1, PROXY_COUNT].

​
Choosing a proxy provider

Use rotating residential proxies, not datacenter proxies. YouTube’s bot detection is highly effective against datacenter IP ranges. Residential proxies route traffic through real consumer ISP addresses, which are far less likely to trigger CAPTCHA or sign-in challenges. Providers like Bright Data, Oxylabs, IPRoyal, and Smartproxy all support the username-{session}:password@host:port URL pattern that Yoink expects.
When selecting a provider:
  • Look for providers that support sticky sessions via username suffixes — this is the pattern Yoink uses.
  • Choose a provider with a large residential IP pool for maximum rotation diversity.
  • US-based pools tend to have the best YouTube reliability, but match the region to your primary audience if download speeds matter.

​
Verifying proxy configuration

When Yoink starts, you can confirm that proxies are properly configured by checking the startup logs. If PROXY_HOST is set and HasProxy() returns true, proxy URLs will be passed to yt-dlp as --proxy http://... during YouTube download retries. If you want to test proxy connectivity independently: 
yt-dlp --proxy "http://user-country-us-session-1:yourpassword@proxy.provider.com:10000" \
  "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
A successful download confirms that the proxy credentials and host are correct before wiring them into Yoink’s environment.

​
Proxies and Cobalt API together

Proxies and the Cobalt API serve complementary roles. Cobalt is the final safety net — it handles cases where both the direct yt-dlp attempt and the proxy retry fail. Configuring both gives you the best resilience:

With proxies only

yt-dlp direct → yt-dlp via proxy → Cobalt API fallback. Proxy adds one extra attempt before Cobalt.

With Cobalt only

yt-dlp direct → Cobalt API fallback. No proxy retry step. Simpler but more Cobalt-dependent.
Yoink monitors yt-dlp stderr output for these specific strings to detect YouTube bot-check failures:
Sign in to confirm you
confirm your age
Sign in to confirm your age
This video is unavailable
Private video
When any of these appear, the download is classified as a bot-detection failure and the proxy retry path is triggered (if proxies are configured), or the Cobalt API fallback is used.

Build docs developers (and LLMs) love

Get started for freeTalk to us