Skip to content

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.

You need Homebrew and your vless:// link. Nothing here is sent anywhere except to the proxy server in your link.

  1. Install Xray (the same proxy software the server runs):

    Terminal window
    brew install xray
  2. 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/xray
    pbpaste | python3 -c '
    import json, sys, urllib.parse
    link = 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.json
    chmod 600 ~/.config/xray/proxy.json

    The file holds your personal link details. Treat it like the link itself.

  3. 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
  4. Test it from a second Terminal window before changing any settings:

    Terminal window
    curl --socks5-hostname 127.0.0.1:10808 https://ipinfo.io/json

    The ip, country and org lines should belong to the proxy, not to your own internet provider. Compare with curl https://ipinfo.io/json, which shows yours.

  5. 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.1 and the port to 10808, and click OK. Or in Terminal:

    Terminal window
    networksetup -listallnetworkservices # find your connection's name, e.g. Wi-Fi
    networksetup -setsocksfirewallproxy Wi-Fi 127.0.0.1 10808 # turn it on
    networksetup -getsocksfirewallproxy Wi-Fi # should say Enabled: Yes

    macOS may ask for your password.

  6. When you’re done, turn the proxy setting off before stopping Xray, or your browser loses its connection:

    Terminal window
    networksetup -setsocksfirewallproxystate Wi-Fi off

    Then press Ctrl+C in the Xray window.

  • 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.

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.

  1. Choose Apple menu → System Settings, then click Network in the sidebar.
  2. Click the Action pop-up menu (⋯), choose Add VPN Configuration, then choose IKEv2.
  3. 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.
  4. 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.

  1. Open Settings → General → VPN & Device Management.
  2. Tap Add VPN Configuration and choose IKEv2.
  3. Fill in Description, Server, Remote ID, Local ID (usually empty), then the Authentication type, User name and Password, as your provider gave them.
  4. 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.

Recent changes

  1. docs(privacy): travel and shutdown prep pages; bot travel, multi-device and onion lines @sac
  2. docs(wiki): private proxy on a Mac without an app, and how to check it works @sac