Cobalt: A Self-Hostable Media Downloader That Works Like a Fancy Proxy

What Cobalt Actually Solves

Cobalt solves a specific annoyance: saving media from the web without being buried in ads, trackers, or paywalls. The README describes it as a media downloader that doesn't piss you off, and the pitch is simple: paste the link, get the file, move on. This is for people who run their own infrastructure or want a clean frontend for downloading public content. The project explicitly positions itself against the usual downloader clutter. It is not for people who want to bypass paywalls or grab non-public content. The ethics section is blunt: it takes zero liability and the end user is responsible for what they download.

The Proxy-Like Architecture

The core mechanism is visible in the repository layout. The monorepo contains an api tree, a web tree, and a packages tree. The api directory includes a stream subdirectory, and the README links to that path when explaining how cobalt works. The key claim is that cobalt never caches any content. It works like a fancy proxy. That means the API likely fetches media on demand and passes it through to the client, rather than storing files on a server. This design choice has direct consequences: no cache means no storage overhead, but it also means repeated downloads hit the source every time. The frontend is built with Svelte, which is noted as the primary language. The docs tree includes separate guides for running an instance, protecting it, and configuring environment variables.

Getting It Running: Commands and Config

The README does not include a quickstart command, but it points to concrete documentation files. To run an instance, you follow the guide at docs/run-an-instance.md. Protecting the instance is covered in docs/protect-an-instance.md. The API environment variables are listed in docs/api-env-variables.md, and the API itself is documented in docs/api.md. Since the README only provides these links, the actual commands are not shown. You would need to open those docs to get the exact setup steps. The repository is a monorepo, so you likely build the api and web packages separately. The presence of a packages tree suggests shared code between the frontend and backend, but the README does not specify what those packages contain.

The No-Cache Constraint as a Double-Edged Sword

The no-cache policy is a genuine limitation. Because cobalt never caches content, every request goes straight to the source. That is good for avoiding legal issues around storing copyrighted material, and it keeps the server footprint small. But it also means performance depends entirely on the source server's speed and availability. If a video host is slow or rate-limits requests, your download will be slow too. For a self-hosted instance, this also means the server must have enough bandwidth to handle concurrent streams. The README frames the proxy behavior as a feature, but it is a trade-off. If you want a local cache for frequently accessed media, cobalt is the wrong tool.

Ethics and the Piracy Boundary

The README spends a paragraph on ethics, which is unusual for a downloader project. It states that cobalt is in no way a piracy tool and cannot be used as such. It can only download free and publicly accessible content. The argument is that the same content can be downloaded via dev tools of any modern web browser. That is a narrow definition of legitimacy. For an engineer evaluating this, the ethical stance is a practical constraint. If you need to download content that requires a login or a paid subscription, cobalt will not help you. The project also takes zero liability, which is a clear warning that the maintainers do not want to be responsible for misuse.

Licensing and Maintenance Costs

The repository is licensed under AGPL-3.0, unless specified otherwise. The api and web READMEs may have their own licenses, so you need to check those files before reusing code. AGPL-3.0 has network copyleft implications, which means if you modify the API and offer it as a network service, you may need to release your modifications. That is a significant consideration for a self-hosted service. The README does not mention a release cadence, the repository has no GitHub releases, and the last push was on 2026-04-06. That makes maintenance cost hard to judge. The README links a community Discord server, Twitter and Bluesky. You should inspect the commit history and docs before committing to a deployment.

Alternatives and How They Differ

A common alternative to cobalt is yt-dlp, a command-line downloader that supports many sites. The difference is architectural. yt-dlp runs locally on your machine and does not require a server or a web frontend. Cobalt, on the other hand, is designed as a client-server system with an API and a Svelte web UI. That means cobalt is better if you want a shared instance for multiple users or a web-based interface. yt-dlp is better if you want a scriptable tool that works offline and has no network service to maintain. Another difference is caching: yt-dlp can cache data locally, while cobalt explicitly does not. The choice depends on whether you want a service or a tool.

Editorial conclusion

Adopt cobalt if you want a self-hosted, no-cache media downloader for free public content and you accept the AGPL-3.0 license and the responsibility for what you download. Do not adopt it if you expect caching, piracy support, or a turnkey hosted service. Before deploying, verify the API environment variables and the protection guide, since the README points to those docs but does not summarize them. The project's own stance is clear: it is a proxy, not a piracy tool, and that boundary is the first thing to test.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository