Deploy and Host Cobalt Tools on Railway

Cobalt is an open-source media downloader focused on a clean, privacy-first experience. This Railway template deploys the official Cobalt API as a lightweight, stateless service.

Cobalt Tools

Important: This template deploys the Cobalt API only. It does not include a web interface. You interact with it via API requests (or connect it to your own frontend / automation tools).

Looking for a ready-to-use Web UI? Deploy the official companion template here:
Cobalt Web UI →

What This Template Deploys

Service	Description
Cobalt API	Stateless media processing API. Accepts a public media URL and returns download links, redirects, tunnels, or picker responses.

Image used:

ghcr.io/imputnet/cobalt:latest

Default port: 9000

No database, Redis, or persistent volume is required for basic usage.

About Hosting Cobalt Tools

Hosting your own Cobalt instance gives you a private, ad-free, and tracking-free media downloader API under your control.

Cobalt is designed to be stateless. Every request is processed independently without storing files or user data. This makes it very lightweight and easy to deploy on Railway.

This template is ideal for:

Personal media downloading workflows
Automation pipelines (n8n, Make, custom scripts)
Backend for custom download frontends
Privacy-conscious users who want to avoid public downloader sites

Supported Platforms

Cobalt supports downloading from many public platforms, including:

Video: YouTube, Vimeo, Dailymotion, Twitch clips
Social: TikTok, Instagram, Twitter/X, Reddit
Audio: SoundCloud and other supported audio platforms

Platform support can change because websites frequently update their systems. Always refer to the official Cobalt repository for the latest compatibility.

Environment Variables

Only API_URL is strictly required. The other variables are pre-configured for better Railway deployment experience and safer public usage.

Variable	Description	Default	Recommended
`API_URL`	Base URL of your Cobalt instance	Auto-filled by Railway	Required
`PORT` / `API_PORT`	Port the API listens on	`9000`	Yes
`CORS_WILDCARD`	Allow requests from any origin	`1`	Yes
`RATELIMIT_MAX`	Max requests per IP per window	`20`	Yes
`DURATION_LIMIT`	Maximum media duration allowed (in seconds)	`10800` (3 hours)	Yes
`TUNNEL_RATELIMIT_MAX`	Rate limit specifically for tunnel responses	`40`	Yes
`FORCE_LOCAL_PROCESSING`	Force local processing instead of remote resolution	`never`	Optional

You can adjust rate limits, duration limits, and other settings according to your needs after deployment.

Deployment

Click Deploy on this template.
Railway will automatically set API_URL to your public domain.
Wait for the deployment to finish.
Your Cobalt API is now ready at your Railway public domain.

No additional configuration, database, Redis, or volume is needed for basic usage.

How to Use the API

Send a POST request to your deployed URL:

curl -X POST "https://your-app.up.railway.app/" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9wgccc",
    "downloadMode": "auto",
    "videoQuality": "1080",
    "audioFormat": "mp3"
  }'

Cobalt will respond with the appropriate download information (direct link, tunnel, picker, etc.) depending on the platform and your request parameters.

Authentication (Recommended for Public Deployments)

By default, authentication is disabled to make testing easy. If you expose your instance publicly, it is strongly recommended to enable authentication.

Cobalt supports two authentication methods via the Authorization header:

Authorization: Api-Key your-secret-key
Authorization: Bearer your-token

After enabling authentication, only requests with a valid key/token will be accepted.

Comparison

Feature	Self-hosted Cobalt (This Template)	Public Cobalt Instances	Typical Ad-supported Sites
Ads	✅ None	✅ None	❌ Often aggressive
Tracking	✅ None	✅ None	❌ Common
Privacy	✅ Full control (your own server)	✅ High	❌ Low
Full API Access	✅ Unlimited	❌ Limited / rate-limited	❌ Usually none
Self-hostable	✅ Yes	❌ No	❌ No
Database / Storage required	✅ No	✅ No	⚠️ Varies
Rate limit control	✅ Full control	❌ Shared	❌ None
Authentication	✅ Optional (recommended)	❌ Not available	❌ Not available
Automation friendly (n8n etc.)	✅ Excellent	⚠️ Limited	❌ Poor
Risk of sudden shutdown	✅ Very low	⚠️ Medium	❌ High
Custom frontend / integration	✅ Full control	❌ Restricted	❌ Impossible
Cost control	✅ You decide	Free but limited	Free (with ads)

Troubleshooting

API returns errors or doesn't work

Make sure API_URL is correctly set to your Railway public domain (including trailing slash).
Check that you're sending a POST request with valid JSON body.

Getting rate limited too quickly

Increase RATELIMIT_MAX or TUNNEL_RATELIMIT_MAX according to your usage.
Consider enabling authentication to prevent abuse.

Want to use this with a web interface

This template only provides the API.
For a ready-made Web UI, deploy the companion template:
Cobalt Web UI

Platform suddenly stops working

This is normal. Websites frequently change their systems. Update to the latest Cobalt image when available, or check the official repository for updates.

Frequently Asked Questions

Does this include a web UI like cobalt.tools?
No. This template only deploys the Cobalt API backend.
Want a full Web UI? Use this companion template: Cobalt Web UI

Does Cobalt store the downloaded files?
No. Cobalt is stateless and does not store files. It only resolves and returns download links.

Do I need Redis?
No for single-instance deployments. Redis is only useful for advanced multi-instance or shared tunnel setups.

Can I restrict who can use my instance?
Yes. Enable authentication using the Authorization header.

Is it safe to expose publicly?
It is safer to enable authentication if you make it public. You can also tighten rate limits.

Why Deploy Cobalt Tools on Railway?

Railway makes it easy to run infrastructure without managing servers, SSL certificates, or networking. This template takes advantage of Railway’s automatic domain, SSL, and scaling so you can have your own clean media downloader API running in minutes with almost zero maintenance.