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 is configured through a combination of environment variables loaded at startup (via a .env file or the process environment) and constants compiled directly into the binary. Environment variables control runtime behavior like ports and API keys; compiled constants enforce hard limits such as queue sizes, file retention, and rate limiting. This page documents both layers.
Environment Variables
All variables are read by config.Load() at startup. Any variable not set falls back to its default. Copy .env.example to .env and edit as needed before running ./yoink.
Server
Controls the network interface and operational mode of the Yoink HTTP server.
| Variable | Default | Description |
|---|
PORT | 3001 | TCP port the server listens on. The server binds to :<PORT> on all interfaces. |
NODE_ENV | development | Runtime environment. Set to production to enable production-mode behaviors (e.g., stricter error responses). |
Authentication
Secrets used to protect privileged API endpoints.
| Variable | Default | Description |
|---|
BOT_SECRET | (none) | Shared secret that authenticates requests from the Discord bot to bot-only API routes. If unset, bot endpoints are unprotected and Yoink will log a warning at startup. |
COBALT_API_KEY | (none) | API key sent to authenticated Cobalt API instances. Leave blank if your Cobalt instance does not require authentication. |
Leaving BOT_SECRET unset exposes bot endpoints to anyone who can reach your server. Always configure this before a public deployment.
Cobalt API
Yoink uses the Cobalt API as a fast path for supported sites. You can point it at one or more self-hosted Cobalt instances.
| Variable | Default | Description |
|---|
COBALT_APIS | https://co.eepy.today | Comma-separated list of Cobalt API base URLs. Yoink distributes requests across all entries. |
SESSION_GENERATOR_URL | http://localhost:8080 | URL of the session token generator service used to create authenticated Cobalt sessions. |
SESSION_TOKEN_REFRESH_MIN | 15 | How often (in minutes) Cobalt session tokens are refreshed. Minimum effective value is 1. |
To add redundancy, list multiple Cobalt instances:COBALT_APIS=https://co.eepy.today,https://cobalt.your-domain.com
AI / Transcription
Required only if you want to enable the transcription feature, which uses OpenAI’s Whisper large model.
| Variable | Default | Description |
|---|
OPENAI_API_KEY | (none) | OpenAI API key. Enables the transcription endpoint, which calls the Whisper large model for audio-to-text. Leave blank to disable transcription. |
Proxy
Configure a rotating proxy pool for outbound download requests. Yoink constructs proxy URLs in the format http://<PROXY_USER_PREFIX><N>:<PROXY_PASSWORD>@<PROXY_HOST>:<PROXY_PORT> where N is a number from 1 to PROXY_COUNT.
| Variable | Default | Description |
|---|
PROXY_HOST | (none) | Hostname or IP address of the proxy server. |
PROXY_PORT | 80 | Port of the proxy server. |
PROXY_USER_PREFIX | (none) | Username prefix for proxy authentication. The proxy index number is appended to this prefix. |
PROXY_PASSWORD | (none) | Password for proxy authentication. |
PROXY_COUNT | 0 | Number of proxy slots in the rotation pool. Set to 0 to disable proxying entirely. |
Proxy support is optional. If PROXY_HOST is not set or PROXY_COUNT is 0, all outbound requests use the default network interface.
Alerts
Discord webhook integration for server health alerts and error notifications.
| Variable | Default | Description |
|---|
DISCORD_WEBHOOK_URL | (none) | Full Discord webhook URL. Setting this value enables Discord alert delivery. Leave blank to disable. |
DISCORD_PING_USER_ID | (none) | Discord user ID to @mention in alert messages. Optional — alerts are sent without a ping if omitted. |
| Variable | Default | Description |
|---|
EXTRACTOR_URL | http://localhost:3099 | Base URL of the extractor microservice. Yoink calls this service to resolve video metadata before dispatching download jobs. |
Discord Bot
These variables are read by the yoink-bot binary (cmd/bot/main.go). The bot will exit at startup if any required variable is not set.
| Variable | Required | Default | Description |
|---|
DISCORD_TOKEN | Yes | (none) | Discord bot token from the Discord Developer Portal. |
DISCORD_APP_ID | Yes | (none) | Application (client) ID of your Discord application. |
BOT_SECRET | Yes | (none) | Shared secret sent with every bot-to-server API request. Must match the BOT_SECRET value on the Yoink server. |
YOINK_API_URL | No | http://localhost:3003 | Internal URL the bot uses to call the Yoink REST API. |
YOINK_PUBLIC_URL | No | (value of YOINK_API_URL) | Public-facing URL embedded in bot response messages. Defaults to YOINK_API_URL if not set. |
Compiled-In Constants
The following values are fixed at compile time in internal/config/config.go. They cannot be changed via environment variables; rebuild the binary to change them.
Queue and Job Limits
| Constant | Value | Description |
|---|
MaxQueueSize | 50 | Maximum number of jobs that can be queued across all job types at any one time. |
MaxJobsPerClient | 3 | Maximum number of concurrent active jobs allowed per client IP address. |
| Job Type | Max Concurrent |
|---|
playlist | 2 |
convert | 2 |
compress | 1 |
transcribe | 1 |
fetchUrl | 2 |
File and Storage Limits
| Constant | Value | Description |
|---|
DiskSpaceMinGB | 5 GB | Minimum free disk space required before Yoink will accept new jobs. |
FileSizeLimit | 8 GB | Maximum size of any single output file. |
FileRetention | 20 minutes | How long completed output files are kept on disk before automatic cleanup. |
MaxPlaylistVideos | 1000 | Maximum number of videos in a single playlist download job. |
MaxVideoDuration | 4 hours | Maximum duration of a single video that Yoink will download. |
Timeout Values
| Constant | Value | Description |
|---|
HeartbeatTimeout | 30 seconds | Time between required client heartbeats before a job is considered abandoned. |
SessionIdleTimeout | 60 seconds | Time a session may be idle before it is expired. |
BotDownloadExpiry | 5 minutes | How long bot-triggered download results are held before expiry. |
PlaylistDownloadExp | 12 hours | How long playlist zip archives are retained after completion. |
AsyncJobTimeout | 1 hour | Maximum total wall-clock time allowed for any single async job. |
ChunkTimeout | 30 minutes | Timeout for a single chunk upload or download operation. |
Rate Limiting
Yoink applies an in-memory sliding-window rate limiter to every incoming request, keyed by client IP. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are included in every response.
| Constant | Value | Description |
|---|
RateLimitWindow | 60 seconds | Duration of the sliding rate-limit window. |
RateLimitMax | 60 requests | Maximum number of requests allowed per IP within the window. |
429 with a JSON body:
{
"error": "Too many requests. Please slow down.",
"resetIn": 42
}
These values are validated server-side against the AllowedFormats, AllowedModes, AllowedQualities, AllowedPresets, AllowedDenoise, and QualityHeight maps in config.go.
Video Containers
| Format | MIME Type |
|---|
mp4 | video/mp4 |
webm | video/webm |
mkv | video/x-matroska |
mov | video/quicktime |
| Format | MIME Type |
|---|
mp3 | audio/mpeg |
m4a | audio/mp4 |
opus | audio/opus |
wav | audio/wav |
flac | audio/flac |
Video Quality Targets
| Label | Target Height |
|---|
2160p | 2160 px |
1440p | 1440 px |
1080p | 1080 px |
720p | 720 px |
480p | 480 px |
360p | 360 px |
Compression Options
Modes
Quality Levels
Presets
Denoise
| Value | Description |
|---|
size | Target a specific output file size in megabytes. |
quality | Target a perceptual quality level rather than a file size. |
| Value | Description |
|---|
high | Lower CRF — larger file, better visual quality. |
medium | Balanced CRF for general use. |
low | Higher CRF — smaller file, reduced visual quality. |
| Value | FFmpeg Preset | Denoise Default | Description |
|---|
fast | ultrafast | none | Fastest encode; largest output for a given quality target. |
balanced | medium | auto | Good speed/quality trade-off for everyday use. |
quality | slow | auto | Slowest encode; best compression efficiency. |
| Value | FFmpeg Filter | Description |
|---|
auto | (preset-controlled) | Applies denoise when the selected preset enables it. |
none | (disabled) | No denoising applied. |
light | hqdn3d=2:1.5:3:2.25 | Gentle noise reduction, minimal detail loss. |
moderate | hqdn3d=4:3:6:4.5 | Balanced noise reduction for average-quality sources. |
heavy | hqdn3d=6:4:9:6 | Aggressive noise reduction for very noisy sources. |
Re-encode Modes
Controls when Yoink forces a full re-encode during download processing.
| Value | Description |
|---|
auto | Re-encode only when necessary (e.g., format conversion requires it). |
always | Always re-encode the output, regardless of the input format. |
never | Never re-encode; copy streams as-is. May fail if the container is incompatible. |
Crop Ratios
Supported aspect ratios for video cropping operations.
Audio Bitrates
Allowed audio bitrate values (in kbps) for audio encoding and conversion.
CORS Configuration
By default Yoink allows requests from all origins (with credentials disabled). To restrict origins, create a cors-origins.txt file in the same directory as the ./yoink binary, with one origin per line. Lines beginning with # are treated as comments.
# Allow the production frontend
https://yoink.your-domain.com
# Allow a staging environment
https://staging.your-domain.com
cors-origins.txt is present and non-empty, Yoink enables AllowCredentials: true and restricts AllowedOrigins to only the listed values.