This page is about the cobalt you run yourself. The hosted one needs nothing from you, and almost every search for the name means that one. The instance on your own server is a different animal: it asks the video sites for a file from your address, and those sites answer a server address differently. We read every setting below in the code at the head of the project, commit a636575b, dated 6 April 2026.
Why an instance stops working
We measured what the video platforms return to a plain request from our own server on 19 September 2026. One request per site per run, two runs, no retries and no cookies, from a hosting network.
Both YouTube test videos answered with the sign-in wall, "Sign in to confirm you're not a bot", on the very first request in both runs. Vimeo returned a Cloudflare challenge. Bilibili answered 412 twice. SoundCloud and Dailymotion answered normally.
The first request. Not the hundredth. This matters because it tells you what a proxy fixes here and what it does not: the address is the problem, so a different address is the answer, and no amount of slowing down will help.
The three settings
HTTP_PROXY=http://user:password@GATEWAY_HOST:GATEWAY_PORT
HTTPS_PROXY=http://user:password@GATEWAY_HOST:GATEWAY_PORT
NO_PROXY=localhost
cobalt reads those names and hands them to undici, the HTTP client the project is built on. It then installs the result as the proxy for the whole process, so every outbound request of the instance uses it.
| Setting | What it does |
|---|---|
HTTP_PROXY | the line for plain requests, and for secure ones as well when HTTPS_PROXY is unset |
HTTPS_PROXY | the line for secure requests |
NO_PROXY | a list of hosts that stay direct; an entry may start with a dot or a star |
API_EXTERNAL_PROXY | the older name, still applied, warns at start that it will be removed |
FREEBIND_CIDR | the other way to change address, and it cannot be used with a proxy |
Two details are worth knowing. The login goes inside the address, as http://user:password@host:port, because that is the shape undici reads. And the instance watches these values while it runs. It does not read them once at start: when they change it builds the proxy again.
One thing it will not take is a SOCKS address. cobalt speaks to HTTP and HTTPS proxies only. The request for SOCKS has been open on its tracker since 30 January 2025, and the version of undici the project pins does not carry it either. Use the HTTP port of your line.
What the proxy carries
All of it. There are two steps in a download: the instance looks up where the file lives, then it fetches the file. Both run through the same proxy, because the proxy is installed for the whole process rather than for one call.
Somebody asked for a split in August 2025: use the proxy for the link lookup, and let the file itself come down directly, "because using a proxy for downloading large media files consumes a lot of bandwidth unnecessarily". It was closed as not planned a month later.
So plan for the bytes. On a line priced per gigabyte, the cost of an instance follows what it downloads, not how many links it resolves. A thousand link lookups are cheap. A hundred videos are not.
Two ways to change address
cobalt has a second trick. Give it an IPv6 range with FREEBIND_CIDR and it picks a random address out of that range for every download, then uses it for all requests of that one download. It is elegant and it costs no traffic, and it needs an IPv6 range routed to that machine.
You cannot have both. The instance refuses to start and says so plainly: freebind is not available when external proxy is enabled. The two features fill the same slot, the object undici sends a request with, and the project rules the pair out at start rather than letting one of them quietly win.
One more use of the word, so it does not confuse you later. cobalt also calls its own file relay a proxy or a tunnel. That is the part that hands the finished file to the person who asked for it. It has nothing to do with the outbound line on this page.
Which proxy type fits it?
Residential, for the sites that refuse a server address. That is what our test above measured, and it is the whole reason an instance that worked on a laptop stops working on a server.
Pick the type by what you download. A sticky port holds one address, which suits a run of several files from one site. A rotating port takes a fresh address per request. A sticky address can still change early if the device behind it leaves the network, so let your instance retry rather than fail.
Traffic is the number to watch here, more than on any other page we have written. The media rides the line, so a gigabyte downloaded is a gigabyte spent. On an HProxy Residential Premium plan you can also allow the server address itself, up to 150 per plan, which means the instance holds no password in its settings at all. The residential proxies page lists the plans, and the plan API manages allowed addresses from code.
What breaks when the proxy is on
- The instance will not start. You set
FREEBIND_CIDRas well. Remove one of the two. - A warning about API_EXTERNAL_PROXY. The old name still works. Move the value to
HTTP_PROXYbefore it is removed. - 407 Proxy Authentication Required. The login is missing or wrong in the address. Our 407 guide covers the causes.
- Traffic runs out faster than expected. The files travel through the line. Count gigabytes, not requests.
- A SOCKS address does nothing. cobalt takes HTTP and HTTPS lines only.
- The site still refuses. A proxy changes the address. It does not change the client, the headers or the fact that a platform may want an account.
What this page does not cover
We read cobalt as text at the head of its main branch and did not run an instance, so we did not measure the traffic a download spends through a line, and we did not test the IPv6 path. The statement that the media bytes ride the proxy follows from the code installing one proxy for the whole process, plus the declined request to split the two steps, rather than from a capture of our own. Our platform test used plain requests from one server address, on one day.
The project publishes no release tags and has not moved since 6 April 2026, so "the newest version" means the head of the branch on the day you clone it. We will read these settings again by 19 October 2026.
Where to go from here
Proxies for yt-dlp covers the other downloader people run on a server, which takes its line per command and can be told to use a proxy for the metadata only. Datacenter versus residential explains why the address type decides the outcome here. Sticky versus rotating sessions helps you pick the port.
Sources
- The proxy settings and their examples (docs/api-env-variables.md), the code that installs them for the whole process (api/src/core/api.js), the refusal to pair them with freebind (api/src/core/env.js), the per download address (api/src/stream/manage.js) and the pinned client version (api/package.json). imputnet/cobalt at commit a636575b, 6 April 2026, read on 19 September 2026.
- Issue 1084, open since 30 January 2025, on SOCKS support, and issue 1421, closed as not planned on 16 September 2025, on using the proxy for the link lookup only. cobalt issue tracker.
- How the environment proxy is chosen, and which shapes each agent accepts. Node.js, nodejs/undici, release 8.10.2, 4 September 2026.
- Plans, allowed addresses and sticky sessions. HProxy documentation, hproxy.com/docs, 19 September 2026.
- Our own test of 19 September 2026: one plain request per video page per run, two runs from our server address. The raw output is kept in the research folder of our yt-dlp page.
