Setup guide

SOCKS Proxy Setup for macOS

Complete guide to configuring SOCKS proxy on macOS using Terminal.

← Back to Support Documentation

📋 Before You Begin

Ensure you have your username and SSH password ready. You’ll need your SSH server hostname (provided via email when you requested SOCKS access), username, and password to connect to our secure SOCKS proxy servers.

Important: All SOCKS proxy servers are under the cotse.net domain. The codamail.com domain is exclusively for email services. SOCKS access must be requested separately from your email account.

💻 Step 1: SSH is Pre-installed on macOS

macOS (based on FreeBSD) includes SSH by default, so no additional software installation is required. You’ll use the built-in Terminal application to create your SOCKS proxy tunnel.

Accessing Terminal

  • Press ⌘ + Space to open Spotlight search.
  • Type “Terminal” and press Enter.
  • Alternatively: Applications → Utilities → Terminal.
  • Or: Launchpad → Other → Terminal.

🔐 Step 2: Create SOCKS Proxy Tunnel

Open a Terminal window and type the command below. Make sure to substitute your account name and the SSH server you were assigned:

ssh -L 5000:127.0.0.1:1080 youraccount@yourassignedsocksserver

SOCKS Configuration: This command creates a SOCKS proxy tunnel on port 5000, forwarding to port 1080 on the server. Unlike HTTP tunnels, SOCKS works at a lower network level.

🚀 Step 3: Establish SOCKS Connection

First Connection

  • Paste the command into Terminal and press Enter.
  • On first connection, you’ll see a host key verification prompt similar to: 
    The authenticity of host 'sp1.cotse.net (67.159.26.71)' can't be established.
DSA key fingerprint is 88:f6:bc:71:bf:6f:1f:be:85:a0:81:4d:ed:3c:d7:dc.
Are you sure you want to continue connecting (yes/no)?
  • Type yes to accept the server key.
  • Enter your password when prompted (typing may not echo, just type and press Enter).
  • Important: Leave the Terminal window open. This maintains your SOCKS tunnel.

Connection Success: Once connected, you’ll see a shell prompt or the connection will appear to “hang”. This is normal and means your SOCKS tunnel is active.

🦊 Firefox Configuration (Recommended)

Configure Firefox SOCKS Proxy

  • Run Firefox.
  • Click menu (☰) → Settings.
  • Scroll to Network Settings and click Settings.
  • Select Manual proxy configuration.
  • Enter 127.0.0.1 and port 5000 in the SOCKS Host field only.
  • Select SOCKS v5.
  • Important: Every other field must be blank for SOCKS.
  • Click OK, then OK again.

Recommendation: We recommend Firefox with the NoScript and uBlock Origin addons for your best protection with a SOCKS proxy.

🌐 Other Browser Configuration

Safari Configuration

Note: Safari uses system proxy settings and may have compatibility issues with SOCKS proxies. Firefox is strongly recommended.

  • If you must use Safari: Safari → Preferences → Advanced.
  • Click Change Settings next to Proxies.
  • In System Preferences → Network → Advanced → Proxies.
  • Check SOCKS Proxy.
  • Server: 127.0.0.1, Port: 5000.
  • Click OK and Apply.

Chrome Configuration

  • Chrome uses system proxy settings on macOS.
  • Follow the Safari system preferences steps above.
  • Alternatively, launch Chrome with command line flags: google-chrome --proxy-server="socks5://127.0.0.1:5000".

🍎 macOS-Specific Features

Terminal Enhancements

  • Background Connection: Use nohup to keep connection alive: nohup ssh -L 5000:127.0.0.1:1080 youraccount@yourassignedsocksserver &
  • SSH Config File: Create ~/.ssh/config for permanent settings: 
    Host cotse-socks
    Hostname yourassignedsocksserver
    User youraccount
    LocalForward 5000 127.0.0.1:1080
    ServerAliveInterval 60
  • Then connect with: ssh cotse-socks.

Automation Options

  • Automator Script: Create an app to launch SOCKS tunnel automatically.
  • LaunchAgent: Set up automatic connection on login.
  • Shell Alias: Add shortcuts to your .bash_profile or .zshrc.

Understanding SOCKS vs HTTP

  • SOCKS Proxy: Works at lower network level, supports more protocols.
  • Port 1080: Standard SOCKS port (vs HTTP ports 8888/8080/9999).
  • Application Support: Works with more applications beyond browsers.
  • SOCKS v5: Preferred version with authentication and UDP support.

🔧 Troubleshooting

Common macOS SOCKS proxy issues and solutions:

  • Connection Refused: Verify your SOCKS server hostname is correct.
  • Permission Denied: Check username is lowercase, password is case-sensitive.
  • Host Key Verification Failed: Remove old key with ssh-keygen -R hostname.
  • Terminal Window Closes: Connection dropped, restart the SSH command.
  • Port Already in Use: Kill existing connection with lsof -ti:5000 | xargs kill.
  • Browser Not Using Proxy: Verify SOCKS settings and restart browser.

macOS System Issues

  • Firewall Blocking: System Preferences → Security → Firewall, allow Terminal.
  • Network Changes: Wi-Fi switching may break connection, restart tunnel.
  • Sleep Mode: SOCKS tunnel may disconnect when Mac sleeps.
  • VPN Conflicts: Disable other VPN software while using SOCKS tunnel.
  • System Proxy Conflicts: Other proxy settings may interfere.

📞 Need Help?

If you need additional assistance with SOCKS proxy setup on macOS or encounter any issues not covered in this guide, please contact our support team at helpdesk@codamail.com.

We’re here to help ensure your SOCKS proxy works perfectly and keeps your Mac browsing secure and private.