Proxy for Claude: Claude Code, the Desktop App and claude.ai
Claude Code reads HTTP proxy variables and refuses SOCKS. How to put Claude Code, the desktop app and the browser on one proxy, which errors that fixes and which it does not.
Key takeaways
Claude Code reads HTTPS_PROXY, HTTP_PROXY and NO_PROXY, and its documentation states that SOCKS proxies are not supported.
A SOCKS5 proxy still works through a local HTTP endpoint, or through a tunnel, where no application setting is involved at all.
The desktop app follows the operating system's proxy setting, the browser follows the browser's, and HTTP/3 travels only through a tunnel.
A proxy changes the exit address and nothing else. Account eligibility follows Anthropic's supported regions policy, which is about where the person is.
Quick comparison
| Factor | claude.ai in a browser | Claude desktop app | Claude Code |
|---|---|---|---|
| Where the proxy is set | Browser settings or an extension | The operating system's proxy settings | The HTTPS_PROXY environment variable |
| Takes a SOCKS5 proxy | Yes, in the browser | Not from the Windows settings box | No, stated in the documentation |
| Takes an HTTP proxy | Yes | Yes | Yes |
| Proxy with a password | Browser prompt or extension | Yes | Written into the address |
| HTTP/3 and QUIC | Only inside a tunnel | Only inside a tunnel | Not used |
| Covered by a TUN tunnel | Yes | Yes | Yes |
What a proxy changes here, and what it does not
A proxy changes one thing: the address Anthropic's servers see when your request arrives. That is enough for a certain set of problems and useless for the rest, so it is worth sorting them before paying for anything.
It helps when the address is the problem. A VPN exit shared with thousands of people collects extra checks and logs you out. A home address that changes every night makes every sign in look like a new place. An office network lets outbound traffic through one gateway and nothing else. A team wants one known address for a shared machine. In all four cases the fix is an address of your own.
It does not help when the account is the problem. Anthropic limits its products to a list of supported countries and territories, and the policy is written around where a person is located and where their organisation is, not around which address a packet arrives from. Using Claude from an unsupported region, or working around that restriction, is a reason to lose the account. No proxy changes that, and this guide does not try to.
It also does nothing for an account that is already suspended. The route there is the appeal link in Anthropic's own message, not a new address.
“A proxy changes the address a request leaves from. It does not change which account Anthropic lets you keep, and anyone selling it that way is selling you a ban.”
Three clients, three different settings
Claude comes in three clients and they do not share a network setting. The table above is the short version, and here is what each one actually does.
In a browser, claude.ai follows the browser. Chrome and Edge on Windows take the system setting unless an extension overrides it, and an extension is the only way to feed them a SOCKS5 proxy with a password without extra software.
The desktop app follows the operating system. On Windows that is the proxy box in network settings, which expects an HTTP proxy with a host and a port, so a SOCKS5 proxy cannot simply be typed into it.
Claude Code reads environment variables, and the documentation is specific about which. It uses the first value it finds in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. NO_PROXY takes hosts separated by spaces or commas. Loopback addresses never go through the proxy, so you do not need an entry for them. The values are read once at launch, which is the usual reason a change seems to be ignored. Restart the session after exporting them.
# A proxy that asks for a password, straight in the address
export HTTPS_PROXY=http://user:[email protected]:8080Why Claude Code refuses a SOCKS5 proxy
The documentation states it in one line: "Claude Code does not support SOCKS proxies." That rules out the format most proxies are sold in, because SOCKS5 is what a provider hands you by default.
There are two ways around it, and neither needs a different proxy.
The first is a local HTTP endpoint. Something on your own machine listens on 127.0.0.1 as an HTTP proxy and forwards everything to the SOCKS5 upstream, so Claude Code sees an HTTP proxy and the provider still sees SOCKS5. Proxya Desktop has this as a switch, and the recipe is further down.
The second is to stop using proxy settings. A TUN tunnel puts traffic on a virtual network adapter before any application is involved, so Claude Code connects the way it normally does and still leaves through the proxy. Nothing to export, nothing to restart, and command line tools that have no proxy settings at all are covered the same way.
The errors, and which ones an address fixes
Before buying anything, read the message. These are the ones that bring people to this page, and they do not have the same cause.
App unavailable in region, or a note that Claude Code might not be available in your country. This is the region check, not the network. A proxy does not settle it, and trying to settle it that way is what puts the account at risk.
403 on sign in. Sometimes the account, more often the network in between. Open claude.ai in a plain browser on the same machine before blaming anything else.
ECONNRESET, fetch failed, connection reset by peer. Something between you and the endpoint is cutting the stream. A filtering network does this, and so does a VPN adapter with a broken packet size. This is the group where a clean direct address genuinely helps.
Timeouts on long requests. Gateways and proxies that close connections while the model is still writing. A proxy that holds idle connections open fixes it, and the documentation lists the timeout variables for the rest.
Certificate errors behind a corporate gateway. An inspection proxy presents its own certificate authority. If that authority is in the operating system trust store it works with no extra setting, otherwise NODE_EXTRA_CA_CERTS points at the file, and CLAUDE_CODE_CERT_STORE chooses which store is trusted.
One more cause of random failures: Claude Code needs more hosts than api.anthropic.com. The documentation lists claude.ai, claude.com, platform.claude.com, sso.claude.com, downloads.claude.ai and bridge.claudeusercontent.com among others, plus github.com and the npm registry for updates and plugins. Put one host through the proxy and leave the rest out, and sign in fails for reasons that look unrelated.
Add the proxy once
Proxya Desktop is a proxy client for Windows and macOS. It takes proxies from any provider, a Proxya account is optional, and it is free. Download it, run the installer, then paste the proxy.
The address field understands the formats a provider gives you, including host:port:user:pass and a full socks5:// address, and the clipboard button takes a whole list at once. Check verifies the proxy before you save it and prints where the address actually sits, how fast the proxy answers and whether UDP passes through it.
Tunnel or system proxy
Both modes send the same traffic to the same proxy and differ in how applications are caught.
Tunnel mode creates a virtual network adapter. It covers everything, including the terminal, and it needs a small service installed once with an administrator prompt. This is the mode that makes Claude Code work with no variables at all.
System proxy mode writes the proxy into the operating system setting and needs no administrator rights. It covers applications that read that setting, which is the desktop app and most browsers, and it does not cover Claude Code, which reads environment variables instead.
Either mode offers the same three choices for applications: all of them, all except the ones you pick, or only the ones you pick. For Claude alone, pick Only the chosen and add the executables. On Windows the desktop app is Claude.exe and the command line tool is claude.exe. Sites through the proxy adds claude.ai, claude.com and anthropic.com by name, so those go through the proxy even when the application that asked for them is not on the list.
Next to another VPN, use system proxy mode. Two tunnels compete for the same routes, and the one with narrower routes wins, so a tunnel can report a connection that is not carrying anything. On Windows the app checks which adapter carries the traffic after connecting and disconnects with an explanation rather than leaving you with a connection in name only.
Claude Code, the two recipes
With the tunnel there is nothing to set. Connect, open a terminal, start Claude Code.
With system proxy mode and a SOCKS5 proxy, switch on Local proxy in Settings. The app opens 127.0.0.1:2080, that port accepts both HTTP and SOCKS5, and the proxy itself stays SOCKS5 upstream. Then point Claude Code at the local address. On our own ISP proxy a request through that port left with the proxy's address and api.anthropic.com answered in about 1.2 seconds.
Variables are read at launch, so set them before starting the session. If you prefer them to survive a reboot, the same values live in the env block of the Claude Code settings file.
# macOS and Linux, in the shell where you start Claude Code
export HTTPS_PROXY=http://127.0.0.1:2080
export NO_PROXY="localhost,127.0.0.1,::1,*.local"
claude# Windows PowerShell, for the current window
$env:HTTPS_PROXY = "http://127.0.0.1:2080"
$env:NO_PROXY = "localhost,127.0.0.1,::1,*.local"
claude{
"env": {
"HTTPS_PROXY": "http://127.0.0.1:2080",
"NO_PROXY": "localhost,127.0.0.1,::1,*.local"
}
}
Settings that matter for this
DNS. Resolved by the proxy is the default and keeps name lookups inside the proxy connection, so your own provider does not resolve the names for you. Choosing Cloudflare, Google, Quad9 or AdGuard switches to DNS over HTTPS through the proxy instead, which in our tests costs about 0.6 seconds on the first request to a new site.
Masking. The connection to a SOCKS5 or HTTP proxy is not encrypted, and some networks read two things out of it: the destination address in the handshake and the site name in the first packet inside the stream. Masking splits both across two packets with a short random pause so neither travels whole. It is on by default. It is not encryption, and the results we recorded for it were on Telegram and Instagram over a filtering network, not on Claude.
Kill switch. While it is armed, traffic that does not come from the tunnel adapter is blocked, so a dead engine means no connection rather than a connection that quietly goes direct. Windows only.
IPv6 is off by default. Turn it on only if the proxy carries IPv6, otherwise half the connections go nowhere.
Which proxy to buy for this
The requirement here is unusual for proxy buying: you want one address that does not move, in a country where the service is supported, held for months.
ISP proxies, sold elsewhere as static residential, fit that exactly. The address is registered to an internet provider and stays yours for the term, billed per proxy with unmetered traffic, from $2.50/proxy/mo. For an account you sign in to every day, this is the type to take.
Residential proxies rotate through home connections and are billed per gigabyte, from $2.40/GB. They suit collecting data across many countries. They are the wrong tool for staying signed in, because the address changes under you.
Datacenter proxies are the cheapest and the easiest to label as hosting. They are fine for a server on your own infrastructure and a poor choice for consumer platforms.
Whichever you take, keep the address steady and keep it in one country. Hopping between countries is what resets sessions and raises questions about an account.
Download and the limits worth knowing
Builds for Windows x64 and macOS on Apple Silicon are published with their SHA-256 checksums. The Windows installer is not signed with a certificate yet, so SmartScreen shows an unknown publisher. Compare the checksum first, then choose More info and Run anyway.
The kill switch is Windows only. The macOS build does not support Intel Macs. The tunnel needs a service installed once, with an administrator prompt, and system proxy mode needs neither.
Proxy passwords and the account session are encrypted on disk with a key held in Windows Credential Manager or the macOS Keychain, so copying the folder to another machine carries neither.
Frequently asked
No. The documentation states that Claude Code does not support SOCKS proxies. It reads HTTPS_PROXY, HTTP_PROXY and NO_PROXY, so a SOCKS5 proxy has to be presented to it as a local HTTP endpoint, or the traffic has to go through a tunnel instead of proxy settings.
HTTPS_PROXY, HTTP_PROXY and NO_PROXY, lowercase variants included. It uses the first it finds in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. A password goes into the address as user:password@host:port. The values are read once at launch, so restart the session after changing them.
Neither is on Anthropic's list of supported countries and regions, and neither are Hong Kong and Macau. Taiwan is on the list. The policy covers people while they are physically located in an unsupported region, so an address in another country does not make an account eligible, and using one to get around the restriction is grounds for losing it.
No. That message is the region check on the account, not a network failure, and Anthropic's supported regions policy is written around where the person is located. Working around it is grounds for losing the account.
Using a proxy to work around a regional restriction can, because that is the restriction being worked around. Using one inside a supported region, for a stable address on a corporate network or a shared machine, is ordinary network setup. We cannot promise how any provider reads a given address, and nobody who tells you otherwise has measured it.
It follows the operating system's proxy setting, so setting the system proxy covers it. In Proxya Desktop that is system proxy mode. Tunnel mode covers it too, without touching the system setting at all.
The system proxy is enough for the desktop app and browsers. Claude Code ignores it and reads environment variables, so either point those at the local proxy port or use the tunnel, which covers every application including the terminal.
An ISP proxy, also sold as static residential, because the address stays the same for the whole term. Residential proxies rotate and are billed per gigabyte, which suits data collection rather than staying signed in. Datacenter addresses are the cheapest and the most likely to be labelled hosting.
It is free, and an account is optional. Add proxies from any provider by hand and it never asks you to sign in. Signing in adds your Proxya orders and lets you generate residential proxies from your traffic balance inside the app.
