Private proxy on a Mac without an app
Most people should use the Hiddify app, as described in Using a private proxy link. It takes two minutes and covers every app on the Mac. This page is for people who can’t or don’t want to install an app, and for anyone who already tried pasting the link into System Settings.
Why System Settings → Proxies doesn’t work
Section titled “Why System Settings → Proxies doesn’t work”macOS has a Proxies page (System Settings → Network → Wi-Fi → Details → Proxies). It looks like the right place, but it only understands four kinds of proxy: web (HTTP), secure web (HTTPS), SOCKS, and automatic configuration (PAC).
A vless:// link is none of those. It describes an encrypted, disguised connection
(VLESS with REALITY) that macOS has no code for. Pasting the link into any box on that
page does nothing. The box labelled Bypass proxy settings for these hosts & domains
is a list of sites that should skip the proxy, so a link pasted there is just ignored.
The same is true on iPhone and iPad: Settings → Wi-Fi → (your network) → Configure Proxy only takes a plain web proxy.
What does work: a small program on your Mac speaks VLESS to the server and offers a plain SOCKS proxy on your own computer, and the Proxies page points at that. The Hiddify app does exactly this for you. The Terminal steps below do it by hand.
Terminal: run the proxy with Xray
Section titled “Terminal: run the proxy with Xray”You need Homebrew and your vless:// link. Nothing here is sent
anywhere except to the proxy server in your link.
-
Install Xray (the same proxy software the server runs):
Terminal window brew install xray -
Copy your whole link, then turn it into a config file. This reads the link from your clipboard, so it never appears on screen or in your shell history:
Terminal window mkdir -p ~/.config/xray && chmod 700 ~/.config/xraypbpaste | python3 -c 'import json, sys, urllib.parselink = urllib.parse.urlsplit(sys.stdin.read().strip())if link.scheme != "vless" or "@" not in link.netloc:sys.exit("That is not a vless:// link. Copy the whole link and try again.")q = dict(urllib.parse.parse_qsl(link.query))user, server = link.netloc.split("@", 1)host, port = server.rsplit(":", 1)print(json.dumps({"log": {"loglevel": "warning"},"inbounds": [{"listen": "127.0.0.1", "port": 10808, "protocol": "socks","settings": {"udp": True}}],"outbounds": [{"protocol": "vless","settings": {"vnext": [{"address": host, "port": int(port),"users": [{"id": user, "encryption": "none", "flow": q.get("flow", "")}]}]},"streamSettings": {"network": q.get("type", "tcp"), "security": "reality","realitySettings": {"serverName": q["sni"], "fingerprint": q.get("fp", "chrome"),"publicKey": q["pbk"], "shortId": q.get("sid", "")}}}]}, indent=2))' > ~/.config/xray/proxy.jsonchmod 600 ~/.config/xray/proxy.jsonThe file holds your personal link details. Treat it like the link itself.
-
Check the file and start Xray. Leave this Terminal window open; closing it stops the proxy.
Terminal window xray run -test -c ~/.config/xray/proxy.json # should end with "Configuration OK."xray run -c ~/.config/xray/proxy.json -
Test it from a second Terminal window before changing any settings:
Terminal window curl --socks5-hostname 127.0.0.1:10808 https://ipinfo.io/jsonThe
ip,countryandorglines should belong to the proxy, not to your own internet provider. Compare withcurl https://ipinfo.io/json, which shows yours. -
Send your Mac’s traffic through it. Either use System Settings → Network → Wi-Fi → Details → Proxies, turn on SOCKS proxy, set the server to
127.0.0.1and the port to10808, and click OK. Or in Terminal:Terminal window networksetup -listallnetworkservices # find your connection's name, e.g. Wi-Finetworksetup -setsocksfirewallproxy Wi-Fi 127.0.0.1 10808 # turn it onnetworksetup -getsocksfirewallproxy Wi-Fi # should say Enabled: YesmacOS may ask for your password.
-
When you’re done, turn the proxy setting off before stopping Xray, or your browser loses its connection:
Terminal window networksetup -setsocksfirewallproxystate Wi-Fi offThen press Ctrl+C in the Xray window.
What this covers, and what it doesn’t
Section titled “What this covers, and what it doesn’t”- Covered: Safari, Chrome, and other apps that follow the Mac’s proxy settings.
- Not covered: apps that ignore system proxies, including many games, some messaging apps and command-line tools. Their traffic goes out directly, unprotected.
- Hiddify in VPN mode covers everything. If you need every app protected, use it.
- Do the leak checks after switching on the proxy setting. With a SOCKS proxy some browsers still look up site names through your own network, and WebRTC can reveal your real address.
The built-in VPN (IKEv2): why we don’t recommend it
Section titled “The built-in VPN (IKEv2): why we don’t recommend it”macOS, iPhone and iPad can connect to an IKEv2 VPN with no app at all. It sounds like the perfect answer, but it’s a poor one against censorship:
- It’s easy to spot and block. IKEv2 always uses the same UDP ports (500 and 4500) and starts with a recognizable handshake. Countries with serious filtering, including Russia, China and Iran, block it routinely. See VPN Protocols and How They Differ and Windscribe’s notes on restricted countries. The private proxy is built to look like ordinary website traffic, which is exactly what IKEv2 can’t do.
- We don’t run an IKEv2 server. You’d need a provider that offers it.
- Proton VPN is retiring it. Proton is removing IKEv2 from its servers, starting April 2026 and ending February 2027, so Proton accounts won’t help either.
When IKEv2 is fine: on a network that only filters websites, such as a hotel, school or workplace, or when your employer or university gives you IKEv2 settings and nothing else.
Set up IKEv2 on a Mac
Section titled “Set up IKEv2 on a Mac”You need the settings from your VPN provider: server address, remote ID, and how to sign in (user name and password, or a certificate). If they give you a configuration profile file instead, open it and let System Settings install it.
- Choose Apple menu → System Settings, then click Network in the sidebar.
- Click the Action pop-up menu (⋯), choose Add VPN Configuration, then choose IKEv2.
- Fill in the fields exactly as your provider gave them:
- Display Name: any name, for example “Work VPN”.
- Server Address: the server’s hostname or IP address.
- Remote ID: usually the same hostname as the server address. Copy it exactly; a wrong remote ID is the most common reason IKEv2 won’t connect.
- Local ID: leave empty unless your provider gave you one.
- Authentication: the method your provider uses, then your user name and password, or the certificate. A certificate may first need to be added to the System keychain and marked trusted.
- Click Create. Connect from the VPN switch in the Network settings, or from the VPN status menu in the menu bar.
Apple’s own steps: Set up a VPN on Mac.
Set up IKEv2 on iPhone or iPad
Section titled “Set up IKEv2 on iPhone or iPad”- Open Settings → General → VPN & Device Management.
- Tap Add VPN Configuration and choose IKEv2.
- Fill in Description, Server, Remote ID, Local ID (usually empty), then the Authentication type, User name and Password, as your provider gave them.
- Tap Done, then switch the VPN on.
Apple’s own steps: Set up a VPN on iPhone and iPad.
Whichever way you connect, run the checks afterwards.
Related
Section titled “Related”- Using a Private Proxy Link: the app-based setup for every device
- Bypassing VPN Blocks: working out what a network blocks
- VPN Recommendation: choosing a VPN where VPNs aren’t blocked
- Travelling to a Censored Country: a checklist for before you leave, at the border and while you’re there
Sources
Section titled “Sources”- Apple: Set up a VPN on Mac, VPN settings on Mac and Set up a VPN on iPhone and iPad (checked November 2026)
- Proton VPN: IKEv2 is ending (March 2026)
- Xray: Xray-core and its Homebrew package. The Terminal steps were tested with Xray 26.10.31 against a working private proxy.