How to set up a proxy on macOS

Published: 19 July 2026 · 5 min read

Which method should you use?

The question we get most often about macOS is some version of “is the proxy only working in my browser? How do I make it apply to everything?” It can absolutely apply to everything - there are three ways to do it, and the right one depends on your hardware and how much routing control you want.

Method	Works on	Covers	Setup effort
Shadowrocket	Apple silicon only	Every app (system VPN)	Lowest
System proxy settings	Any Mac	Browsers and proxy-aware apps	Low, no install
Clash-family client, TUN mode	Any Mac	Every app, plus routing rules	Highest

Method 1: Shadowrocket (recommended on Apple silicon)

M-series Macs can run the iOS build of Shadowrocket directly, and it is configured exactly the same way as on an iPhone. This is the least fiddly path.

1. Open the Mac App Store, search for Shadowrocket, and switch to the iPhone & iPad Apps tab. Developers can withdraw permission for their iOS app to be installed on macOS at any time, so if it does not appear there, it is simply not available right now - move on to method 2 or 3 rather than hunting for workarounds.
2. Follow our Shadowrocket setup guide for the configuration steps - server gw.roamproxy.com, port 41080, SOCKS5 with your gateway username and password.
3. Once enabled it runs as a system-level VPN, so all app traffic goes through the proxy, not just the browser.

Intel Macs cannot install iOS apps at all. Skip to method 2 or 3.

Method 2: macOS system proxy settings (no software required)

Go to System Settings → Network → select your active connection (Wi-Fi or Ethernet) → Details → Proxies:

1. Enable SOCKS proxy.
2. Set the server to gw.roamproxy.com and the port to 41080.
3. Tick Proxy requires password and enter your gateway username and password.
4. Click OK, then Apply.

What this method does not cover

Only programs that deliberately read the system proxy configuration will use it. Safari and Chrome do. Many command-line tools - curl, git, language SDKs - do not read it by default and will continue to use your real IP. That mismatch is the single most common source of “the browser shows the proxy IP but my script does not” reports.

The system proxy panel also has no concept of chaining, so if your network cannot reach our gateway directly - a restricted network, a corporate firewall that blocks outbound 41080 - this method cannot be made to work. Use method 1 or method 3 instead.

Configuring the command line separately

export ALL_PROXY=socks5h://username:password@gw.roamproxy.com:41080

Use socks5h rather than socks5 so that DNS resolution also happens at the proxy. With plain socks5 your Mac resolves hostnames locally, which leaks DNS and frequently causes lookup failures.

Character	Write it as
#	%23
@	%40
/	%2F
:	%3A

For a single command you can skip the encoding entirely by passing the credentials separately with -U:

curl -x socks5h://gw.roamproxy.com:41080 -U 'username:password' https://ip.sb

Method 3: Clash-family client (Intel Macs, or when you need routing rules)

Clients such as ClashX and Clash Verge support an enhanced mode / TUN mode that captures all system traffic at the network layer, and they can also chain our exit through another proxy you already run.

Add Roam as a proxy in your configuration:

proxies:
  - name: RoamProxy
    type: socks5
    server: gw.roamproxy.com
    port: 41080
    username: your-username
    password: your-password
    udp: true

Chaining Roam behind an existing proxy

If your network cannot reach gw.roamproxy.com:41080 directly - a restricted network, a corporate firewall, or a machine that is only allowed out through one approved egress - add dialer-proxy to the RoamProxy entry, pointing at the upstream proxy you already have working:

    dialer-proxy: your-upstream-proxy-name

Clash will then dial our gateway through that upstream, and the traffic still exits from a Roam residential IP.

Finally, turn on enhanced mode / TUN mode to make the configuration system-wide.

Verify it works

In Terminal, run:

curl https://ip.sb

If it returns your Roam exit IP, you are done. If the browser shows the proxy IP but curl shows your real one, only the system proxy is in effect and the command line is not going through it - go back to the ALL_PROXY step in method 2.

If nothing loads at all, see proxy connected but not working.

FAQ

Does a proxy on a Mac only work inside the browser?

No - that is just the most common way people set it up. The macOS system proxy setting only affects apps that choose to read it, and browsers are the apps that always do. Shadowrocket and Clash TUN mode operate at the network layer instead, so every app on the machine is covered. If you only need the browser, the system proxy setting is enough; if you need Terminal, Node, Python, or a native app to go through the proxy, use Shadowrocket, TUN mode, or set ALL_PROXY in your shell.

Why does curl fail with "Unsupported proxy syntax" when my browser works fine?

Your proxy password almost certainly contains a special character. ALL_PROXY is parsed as a URL, so a #, @, /, or : in the password breaks the parse - a # in particular makes curl reject the string outright. Percent-encode the password (# becomes %23, @ becomes %40) or, for a one-off command, pass the credentials separately with -U so no encoding is needed.

Should I use socks5 or socks5h?

Use socks5h. With plain socks5, your Mac resolves hostnames locally and only the TCP connection goes through the proxy, which leaks your DNS queries and often causes resolution failures for sites your local resolver cannot reach. socks5h hands the hostname to the proxy and lets the exit node resolve it, which is what you want for geo-accurate results.

I have an Intel Mac and cannot install Shadowrocket. What are my options?

Intel Macs cannot run iOS apps, so Shadowrocket is unavailable. Use the built-in system proxy settings if browser and system-proxy-aware app traffic is all you need, or install a Clash-family client (ClashX, Clash Verge) and enable TUN mode for genuine system-wide capture. Clash is also the only one of the three that supports chaining and per-domain routing rules.

Roam gives you SOCKS5 and HTTP access to rotating residential IPs at $2/GB and dedicated static residential IPs at $4/IP per month, on one gateway that works with every method on this page. Create an account and get 300MB of free trial traffic to test your Mac setup end to end.