you can customize your processing instance's behavior using these environment variables. all of them but API_URL are optional.
this document is not final and will expand over time. feel free to improve it!
| name | default | value example |
|---|---|---|
| API_URL | https://api.url.example/ |
|
| API_PORT | 9000 |
1337 |
| COOKIE_PATH | /cookies.json |
|
| PROCESSING_PRIORITY | 10 |
|
| API_INSTANCE_COUNT | 6 |
|
| API_REDIS_URL | redis://localhost:6379 |
|
| DISABLED_SERVICES | bilibili,youtube |
| name | default | value example |
|---|---|---|
| API_LISTEN_ADDRESS | 0.0.0.0 |
127.0.0.1 |
| API_EXTERNAL_PROXY | http://user:[email protected]:8080 |
|
| FREEBIND_CIDR | 2001:db8::/32 |
| name | default | value example |
|---|---|---|
| DURATION_LIMIT | 10800 |
18000 |
| TUNNEL_LIFESPAN | 90 |
120 |
| RATELIMIT_WINDOW | 60 |
120 |
| RATELIMIT_MAX | 20 |
30 |
| SESSION_RATELIMIT_WINDOW | 60 |
60 |
| SESSION_RATELIMIT | 10 |
10 |
| name | default | value example |
|---|---|---|
| CORS_WILDCARD | 1 |
0 |
| CORS_URL | https://web.url.example |
|
| TURNSTILE_SITEKEY | 1x00000000000000000000BB |
|
| TURNSTILE_SECRET | 1x0000000000000000000000000000000AA |
|
| JWT_SECRET | see details | |
| JWT_EXPIRY | 120 |
240 |
| API_KEY_URL | file://keys.json |
|
| API_AUTH_REQUIRED | 1 |
| name | value example |
|---|---|
| CUSTOM_INNERTUBE_CLIENT | IOS |
| YOUTUBE_SESSION_SERVER | http://localhost:8080/ |
| YOUTUBE_SESSION_INNERTUBE_CLIENT | WEB_EMBEDDED |
Note
API_URL is required to run the API instance.
the URL from which your instance will be accessible. can be external or internal, but it must be a valid URL or else tunnels will not work.
the value is a URL.
port from which the API server will be accessible.
the value is a number from 1024 to 65535.
path to the cookies.json file relative to the current working directory of your cobalt instance (usually the main (src/api) folder).
nice value for ffmpeg subprocesses. available only on unix systems.
note: the higher the nice value, the lower the priority. you can read more about nice here.
the value is a number.
supported only on linux and node.js >=23.1.0. when configured, cobalt will spawn multiple sub-instances amongst which requests will be balanced. API_REDIS_URL is required to use this option.
the value is a number.
when configured, cobalt will use this redis instance for tunnel cache. required when API_INSTANCE_COUNT is more than 1, because else sub-instance wouldn't be able to share cache.
the value is a URL.
comma-separated list which disables certain services from being used.
the value is a string of cobalt-supported services.
defines the local address for the api instance. if you are using a docker container, you usually don't need to configure this.
the value is a local IP address.
URL of the proxy that will be passed to ProxyAgent and used for all external requests. HTTP(S) only.
if some feature breaks when using a proxy, please make a new issue about it!
the value is a URL.
IPv6 prefix used for randomly assigning addresses to cobalt requests. available only on linux systems.
setting a FREEBIND_CIDR allows cobalt to pick a random IP for every download and use it for all requests it makes for that particular download.
to use freebind in cobalt, you need to follow its setup instructions first.
if you want to use this option and run cobalt in a docker container, you also need to set the API_LISTEN_ADDRESS env variable to 127.0.0.1 and set network_mode for the container to host.
the value is an IPv6 range.
media duration limit, in seconds
the value is a number.
the duration for which tunnel info is stored in ram, in seconds.
it's recommended to keep this value either default or as low as possible to preserve efficiency and user privacy.
the value is a number.
rate limit time window for api requests, but not session requests, in seconds.
the value is a number.
amount of api requests to be allowed within the time window of RATELIMIT_WINDOW.
the value is a number.
rate limit time window for session creation requests, in seconds.
the value is a number.
amount of session requests to be allowed within the time window of SESSION_RATELIMIT_WINDOW.
the value is a number.
Note
in order to enable turnstile bot protection, TURNSTILE_SITEKEY, TURNSTILE_SECRET, and JWT_SECRET must be set. all three at once.
defines whether cross-origin resource sharing is enabled. when enabled, your instance will be accessible from foreign web pages.
the value is a number. 0: disabled. 1: enabled.
configures the cross-origin resource sharing origin. your instance will be available only from this URL if CORS_WILDCARD is set to 0.
the value is a URL.
cloudflare turnstile sitekey used by the web client to request & solve a challenge to prove that the user is not a bot.
the value is a specific key.
cloudflare turnstile secret used by the processing instance to verify that the client solved the challenge successfully.
the value is a specific key.
the secret used for issuing JWT tokens for request authentication. the value must be a random, secure, and long string (over 16 characters).
the value is a specific key.
the duration of how long a cobalt-issued JWT token will remain valid, in seconds.
the value is a number.
the URL to the the external or local key database. for local files you have to specify a local path using the file:// protocol.
see the api key section in the "how to protect your cobalt instance" document for more details.
the value is a URL.
when set to 1, the user always needs to be authenticated in some way before they can access the API (either via an api key or via turnstile, if enabled).
the value is a number.
innertube client that will be used instead of the default one.
the value is a string.
URL to an instance of yt-session-generator. used for automatically pulling poToken & visitor_data for youtube. can be local or remote.
the value is a URL.
innertube client that's compatible with botguard's (web) poToken and visitor_data.
the value is a string.