How to Configure a SOCKS5 Proxy in macOS Using System Settings and networksetup

Whether routing development traffic through an encrypted SSH bastion host (ssh -D), securing web browsing over untrusted public Wi-Fi, or bypassing restrictive network firewalls, configuring a SOCKS5 proxy provides a robust, protocol-agnostic transport layer. Unlike standard HTTP proxies which only handle web requests, SOCKS5 operates at layer 5 of the OSI model, seamlessly routing arbitrary TCP (and optionally UDP) application traffic without requiring deep packet inspection.

macOS includes full, system-level support for SOCKS proxies. You can configure and manage proxies either graphically via the modern System Settings interface or programmatically through the command-line networksetup utility.

Method 1: Configuring SOCKS5 Proxy via macOS System Settings

To configure a SOCKS5 proxy in modern macOS (Sonoma, Sequoia, and later):

1. Click the Apple menu () in the top left corner and select System Settings…
2. Select Network from the left sidebar.
3. Click your active network service (e.g. Wi-Fi or Ethernet).
4. Click the Details… button next to your connection status.
5. In the configuration sheet that appears, select the Proxies tab from the left navigation.
6. Locate the SOCKS proxy entry in the list of protocols and toggle its switch to the On position.
7. Enter the proxy server connection details:
   • Server: The hostname or IP address (e.g. 127.0.0.1 for an SSH tunnel or proxy.company.com).
   • Port: The port number (e.g. 1080).
8. If your proxy server requires credentials, toggle Proxy server requires password and enter your Username and Password.
9. In the Bypass proxy settings for these Hosts & Domains field, specify internal hosts or local subnets that should connect directly (e.g. *.local, 192.168.0.0/16, localhost).
10. Click OK, then click Apply to commit the changes.

Method 2: Configuring SOCKS5 Proxy via Terminal Using networksetup

For system administrators, DevOps engineers, and automated shell scripts, the macOS networksetup command-line utility enables instant proxy configuration without touching the GUI:

1. Identifying the Active Network Service

Before modifying settings, determine the exact service name assigned to your network hardware:

networksetup -listallnetworkservices

Common service names include Wi-Fi, Ethernet, or Thunderbolt Ethernet.

2. Setting the SOCKS Firewall Proxy

To enable and configure a SOCKS5 proxy on the Wi-Fi interface:

# Syntax: networksetup -setsocksfirewallproxy <service> <host> <port> [authenticated] [username] [password]
sudo networksetup -setsocksfirewallproxy "Wi-Fi" 127.0.0.1 1080

If authentication is required:

sudo networksetup -setsocksfirewallproxy "Wi-Fi" proxy.example.com 1080 on "proxyuser" "SecretPassword123"

3. Verifying the Active Proxy Configuration

To audit the current SOCKS proxy status and verify the parameters:

networksetup -getsocksfirewallproxy "Wi-Fi"

Output:

Enabled: Yes
Server: 127.0.0.1
Port: 1080
Authenticated Proxy Enabled: 0

4. Disabling the SOCKS Proxy in Terminal

To disable the SOCKS proxy when the tunnel or session finishes:

sudo networksetup -setsocksfirewallproxystate "Wi-Fi" off

Creating a Dynamic SSH SOCKS5 Proxy Tunnel

A classic, powerful workflow on macOS is combining ssh with the local SOCKS proxy configuration to route all system web traffic through a remote Linux server:

1. Open Terminal and establish a background dynamic SOCKS5 forward:

   ssh -D 1080 -C -q -N [email protected]

   • -D 1080: Binds local port 1080 as a dynamic SOCKS listener.
   • -C: Enables data compression.
   • -q: Quiet mode (suppresses warnings).
   • -N: Tells SSH not to execute remote commands (tunnelling only).
2. Enable the SOCKS proxy in macOS pointing to 127.0.0.1:1080 as shown above.
3. Verify your outward-facing IP address in Terminal:

   curl --socks5 127.0.0.1:1080 https://icanhazip.com

Your macOS system will now route its traffic cleanly through the encrypted SSH tunnel.