TOPTRACING

Cobalt: best way to save what you love

Dec 8, 2024

0
https://cobalt.tools/https://github.com/imputnet/cobalt

Cobalt is a media downloader that doesn't piss you off. it's friendly, efficient, and doesn't have ads, trackers, paywalls or other nonsense.

Paste the link, get the file, move on. that simple, just how it should be.

Cobalt is a tool that makes downloading public content easier. it takes zero liability. the end user is responsible for what they download, how they use and distribute that content. cobalt never caches any content, it works like a fancy proxy.

Cobalt is in no way a piracy tool and cannot be used as such. it can only download free & publicly accessible content. same content can be downloaded via dev tools of any modern web browser.

How to run a cobalt instance

Using docker compose and package from github (recommended)

To run the cobalt docker package, you need to have docker and docker-compose installed and configured.

If you need help with installing docker, follow only the first step of these tutorials by digitalocean:

Create a folder for cobalt config file, something like this:

mkdir cobalt

Go to cobalt folder, and create a docker compose config file:

cd cobalt && nano docker-compose.yml

nano used in this example, it may not be available in your distro. you can use any other text editor.

Copy and paste the sample config from here for either web or api instance (or both, if you wish) and edit it to your needs. make sure to replace default URLs with your own or cobalt won't work correctly.

Finally, start the cobalt container (from cobalt directory):

docker compose up -d

If you want your instance to support services that require authentication to view public content, create cookies.json file in the same directory as docker-compose.yml. example cookies file can be found here.

Cobalt package will update automatically thanks to watchtower.

It's highly recommended to use a reverse proxy (such as nginx) if you want your instance to face the public internet. look up tutorials online.

Run cobalt api outside of docker (useful for local development)

requirements:

  • node.js >= 18
  • git
  • pnpm
  1. clone the repo: git clone https://github.com/imputnet/cobalt.
  2. go to api/src directory: cd cobalt/api/src.
  3. install dependencies: pnpm install.
  4. create .env file in the same directory.
  5. add needed environment variables to .env file. only API_URL is required to run cobalt. if you don't know what api url to use for local development, use http://localhost:9000/.
  6. run cobalt: pnpm start.

ubuntu 22.04 workaround

nscd needs to be installed and running so that the ffmpeg-static binary can resolve DNS (#101):

sudo apt install nscd
sudo service nscd start

How to protect your cobalt instance

if you keep getting a ton of unknown traffic that hurts the performance of your instance, then it might be a good idea to enable bot protection.

Configure cloudflare turnstile

turnstile is a free, safe, and privacy-respecting alternative to captcha. cobalt uses it automatically to weed out bots and automated scripts. your instance doesn't have to be proxied by cloudflare to use turnstile. all you need is a free cloudflare account to get started.

cloudflare dashboard interface might change over time, but basics should stay the same.

Warning: never share the turnstile secret key, always keep it private. if accidentally exposed, rotate it in widget settings.

  1. open the cloudflare dashboard and log into your account
  2. once logged in, select Turnstile in the sidebar
  3. press Add widget
  4. enter the widget name (can be anything, such as "cobalt")
  5. add cobalt frontend domains you want the widget to work with, you can change this list later at any time. if you want to use your processing instance with cobalt.tools frontend, then add cobalt.tools to the list
  6. select invisible widget mode
  7. press create
  8. keep the page with sitekey and secret key open, you'll need them later. if you closed it, no worries! just open the same turnstile page and press "settings" on your freshly made turnstile widget.

You've successfully created a turnstile widget! time to add it to your processing instance.

Enable turnstile on your processing instance

This tutorial assumes that you only have API_URL in your environment variables list. if you have other variables there, just add new ones after existing ones.

Open your docker-compose.yml config file in any text editor of choice.

Copy the turnstile sitekey & secret key and paste them to their respective variables. TURNSTILE_SITEKEY for the sitekey and TURNSTILE_SECRET for the secret key:

environment:
    API_URL: "https://your.instance.url.here.local/"
    TURNSTILE_SITEKEY: "2x00000000000000000000BB" # use your key
    TURNSTILE_SECRET: "2x0000000000000000000000000000000AA" # use your key

Generate a JWT_SECRET. we recommend using an alphanumeric collection with a length of at least 64 characters. this string will be used as salt for all JWT keys.

You can generate a random secret with pnpm -r token:jwt or use any other that you like.

environment:
    API_URL: "https://your.instance.url.here.local/"
    TURNSTILE_SITEKEY: "2x00000000000000000000BB" # use your key
    TURNSTILE_SECRET: "2x0000000000000000000000000000000AA" # use your key
    JWT_SECRET: "bgBmF4efNCKPirD" # create a new secret, NEVER use this one

Restart the docker container.

Configure api keys

If you want to use your instance outside of web interface, you'll need an api key!

Warning: when storing keys file remotely, make sure that it's not publicly accessible and that link to it is either authenticated (via query) or impossible to guess.

If api keys leak, you'll have to update/remove all UUIDs to revoke them.

Create a keys.json file following the schema and example here.

Expose the keys.json to the docker container:

volumes:
    - ./keys.json:/keys.json:ro # ro - read-only

Add a path to the keys file to container environment:

environment:
    # ... other variables here ...
    API_KEY_URL: "file:///keys.json"

Restart the docker container.

Limit access to an instance with api keys but no turnstile

By default, api keys are additional, meaning that they're not required, but work alongside with turnstile or no auth (regular ip hash rate limiting).

To always require auth (via keys or turnstile, if configured), set API_AUTH_REQUIRED to 1:

environment:
    # ... other variables here ...
    API_AUTH_REQUIRED: 1
  • if both keys and turnstile are enabled, then nothing will change.
  • if only keys are configured, then all requests without a valid api key will be refused.

How to configure a cobalt instance for youtube

If you get various errors when attempting to download videos that are: publicly available, not region locked, and not age-restricted; then your instance's ip address may have bad reputation.

In this case you have to use disposable google accounts. there's no other known workaround as of time of writing this document.

Caution: NEVER use your personal google account for downloading videos via any means. you can use any google accounts that you're willing to sacrifice, but be prepared to have them permanently suspended. we recommend that you use accounts that don't link back to your personal google account or identity, just in case. use incognito mode when signing in. we also recommend using vpn/proxy services (such as mullvad).

  1. if you haven't done it already, clone the cobalt repo, go to the cloned directory, and run pnpm install
  2. run pnpm -C api token:youtube
  3. follow instructions, use incognito mode in your browser when signing in. i cannot stress this enough, but again, DO NOT USE YOUR PERSONAL GOOGLE ACCOUNT.
  4. once you have the oauth token, add it to youtube_oauth in your cookies file. you can see an example here. you can have several account tokens in this file, if you like.
  5. all done! enjoy freedom.

liability

You're responsible for any damage done to any of your google accounts or any other damages. you do this by yourself and at your own risk.