Setup guide

SSH Tunnel Setup for macOS

Complete guide to configuring SSH tunneling 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 SSH access), username, and password to connect to our secure SSH proxy servers.

Important: All SSH proxy servers are under the cotse.net domain. The codamail.com domain is exclusively for email services. SSH 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 SSH tunnel.

Accessing Terminal

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

🔐 Step 2: Choose Your SSH Tunnel Command

Pick one of three filtering levels. Replace youraccount with your username and yourassignedsshserver with your server hostname.

Port 8888 — Unfiltered (Recommended)

ssh -L 5000:127.0.0.1:8888 youraccount@yourassignedsshserver

Best for: Advanced users who want speed and control. You handle your own filtering, with basic header changes for privacy protection.

Port 8080 — Filtered (Maximum Privacy)

ssh -L 5000:127.0.0.1:8080 youraccount@yourassignedsshserver

Best for: Users wanting maximum privacy. Routes through Privoxy for enhanced safety, but may be slower.

Port 9999 — Pass-through (Fastest)

ssh -L 5000:127.0.0.1:9999 youraccount@yourassignedsshserver

Best for: Users needing minimal interference. Only changes your IP address, no other modifications. Fastest option.

🚀 Step 3: Establish SSH Connection

First Connection

  • Paste your chosen command into Terminal and press Enter.
  • On first connection, you’ll see a host key verification prompt similar to: 
    The authenticity of host 'express1.cotse.net (67.159.26.65)' can't be established.
RSA key fingerprint is SHA256:example_fingerprint_here.
Are you sure you want to continue connecting (yes/no)?
  • Type yes and press Enter to accept the server key.
  • Enter your password when prompted (typing will not be visible).
  • Keep the Terminal window open. This maintains your tunnel.

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

🌐 Browser Configuration

Firefox Configuration (Strongly Recommended)

  • Open Firefox.
  • Click menu (☰) → Settings.
  • Scroll to Network Settings and click Settings.
  • Select Manual proxy configuration.
  • In HTTP Proxy enter: 127.0.0.1.
  • In Port enter: 5000.
  • Select Use proxy server for all protocols.
  • Click OK.

Chrome Configuration

  • Open Chrome.
  • Go to Settings → Advanced → System.
  • Click Open your computer’s proxy settings.
  • In macOS System Preferences, go to Network.
  • Select your active connection → Advanced → Proxies.
  • Check Web Proxy (HTTP).
  • Server: 127.0.0.1, Port: 5000.
  • Click OK and Apply.

Safari Configuration (Not Recommended)

Warning: Safari has difficulty rendering pages when user agent strings are masked (which our proxies do for privacy). Use Firefox instead for best compatibility.

  • If you must use Safari: Safari → Preferences → Advanced.
  • Click Change Settings next to Proxies.
  • Follow the Chrome system preferences steps above.
  • Note: Facebook and some other sites may not work with Safari on ports 8888 or 8080.

🍎 macOS-Specific Features

Terminal Enhancements

  • Background Connection: Use nohup to keep connection alive: nohup ssh -L 5000:127.0.0.1:8888 youraccount@yourassignedsshserver &
  • SSH Config File: Create ~/.ssh/config for permanent settings.
  • Keychain Integration: Store SSH keys in macOS Keychain for passwordless login.

Automation Options

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

Recommended Browser Extensions

  • Firefox: NoScript, uBlock Origin, HTTPS Everywhere.
  • Chrome: uBlock Origin, Privacy Badger, Ghostery.
  • Port 8888: Best balance of speed and configurable privacy.

🔧 Troubleshooting

Common macOS-specific issues and solutions:

  • Connection Refused: Verify your SSH 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.
  • Slow Performance: Try port 9999 for fastest speed.

macOS System Issues

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

📞 Need Help?

If you need additional assistance with SSH tunnel 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 SSH tunnel works perfectly and keeps your Mac browsing secure and private.