Sauce Labs is quickly starting to dominate the world of Selenium Grid and Continuous Integration management. Sauce has a ton of awesome features, one of the most important ones is Sauce Connect (SC).


What Is Sauce Connect?

  • Allows testing of internal web sites and applications
  • Secure connection between Sauce Labs and your internal network
  • Alternative to Whitelisting or VPN connection
  • SC is a gateway between 2 networks

How does a Sauce Connect architecture look?

Sauce Labs Architecture. (

What do you need to know about how Sauce Connect works?

  • Uses port 443 to send outbound traffic to * and * Port 443 must be open on the server that runs SC and traffic must communicate with these two domains.
  • Port 443 is the only port that needs to be opened

Quick start – dirty version

  1. Download the latest version of Sauce Connect
  2. Unzip the package
  3. Open command line of where SC lives
  4. Run command

Mac or Linux


With environment variables set:

bin/sc -u $SAUCE_USERNAME - $SAUCE_ACCESS_KEY -i tunnelName


If you have your username and password stored in environment variables in Windows, you can run from Powershell command line:


Quick start – recommended

This is the better approach to getting started with sauce connect because it’s always useful to supply a tunnel identifier. It will be helpful for your test automation and there is no reason not to supply the tunnel identifier.

Mac or Linux

bin/sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY -i YourTunnelName


If you have your username and password stored in environment variables in Windows, you can run from Powershell command line:

.\bin\sc.exe -i YourTunnelName

Performance requirements

  • 2GB and 1 core on a Linux VM for every 100 sessions
  • 8GB and 2 cores on a Windows VM for every 100 sessions

More stringent requirements are here from Sauce Labs

High availability sauce connect tunnel

This feature is great if you want to run more than 200 jobs in parallel. What will happen is that you can have multiple tunnels running with the same tunnel identifier.

Prior to setting up tunnels in high availability mode, make sure that you can run a single tunnel without any issues. Resolving issues with a single tunnel is easier than trying to resolve issues in HA mode.


  • Use one tunnel on one VM for 100 concurrent sessions
  • You don’t need a load balancer with multiple virtual machines. Sauce Connect will round robin your requests automatically.
  • 2 GB RAM with 1 core per Sauce Connect instance

Step by step instructions

Download the latest version of Sauce Connect.

Unzip the Sauce Connect.

1. Start 1st tunnel

2. Start 2nd tunnel

3. Now in you will have 2 tunnels running with the same tunnel identifier.

How to monitor your Sauce Connect tunnels to see if they’re up?

You can get stats about the sauce connect by hitting your localhost and getting back a JSON response.

  1. Go to your Sauce Connect VM
  2. Hit url: http://localhost:8888/debug/vars
  3. kgp.Connected indicates if the client is connected to the Sauce Connect back-end. This field can be used for monitoring tunnel health.


You do not need to pass in the user name or the key if you have them stored in environment variables.

Awesome docs from Sauce Labs on high availability tunnels

Creating lean tests to run on Sauce Labs

  1. Use the -D, –direct-domains flag to bypass specific urls and send them directly through the internet instead of Sauce Connect
  2. Use -F, fastfailregexps flag to remove any resources in your application that are not necessary, such as advertisements or images
  3. Keep your test automation code, your Sauce Connect instances, and your software under test as close as possible to reduce the number of network hops
  4. Decrease the amount of chatter from your tests. Every Selenium command is a web request that has to travel over the internet. Get text, get displayed, find element.
  5. Turn off automatic screenshots, video, and network capturing for your tests

Excellent, in-depth documentation from Sauce

Working with environment variables

Running Sauce Connect with environment variables

Mac/Linux command to run Sauce Connect using environment variable values


This will run Sauce Connect with the values that you have stored in the two environment variables: $SAUCE_USERNAME, $SAUCE_ACCESS_KEY

Windows command to run Sauce Connect using environment variable values

Setting Sauce Connect environment variables




However, this will only set the environment variables for the session. To have them permanently saved, add them to your bash_profile

cd ~/
//create a new file
touch .bash_profile
//edit in text pad
open -e .bash_profile
//add environment variables for permanent storage
export SAUCE_USERNAME="your sauce user name"
export SAUCE_ACCESS_KEY="your access key"

Don’t forget to restart your computer afterwards

How to start 2 tunnels on the same machine

Make sure that each tunnel gets a unique port. The first one will default to 4445. The second tunnel that you start will mandate a:

-P to set a new port,

–logfile to point to a new logfile,

and –pidfile to point to a new .pid file.

See the example below:

Tunnel 1: 
bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -i NikolaysTunnel 

Tunnel 2: 
bin/sc -i my-tun2 --pidfile --logfile sc2.log -P 4446

More on this topic can be found on the excellent docs from Sauce Labs.

How to figure out which tunnel you are using?

If you are interested to learn which Sauce Connect tunnel you are using from the User Interface, you can figure it out like this:

1. Go to your account and login

2. Go to Tunnels in your dashboard

3. You will see a list of tunnels. Each tunnel will have a tunnel identifier that looks like this:

tunnel id
tunnel id

4. You can use the ID and check your Sauce Connect server to see where this tunnel is running. For example, I can see this in my Powershell console. If the IDs match, I know that I found the server where my Sauce Connect is running.

sauce tunnel id in posh
sauce tunnel id in posh

Sauce Connect and RDC

Start Sauce Connect


.\bin\sc.exe -i NikolaysTunnel -u nikolay-a -k CD7874C45DF24FDF9 -x ht

Running Multiple Tunnels on the Same VM

Helpful Docs from Sauce

Sauce connect setup and teardown process

Sauce Connect proxy FAQs

Sauce Connect command line reference

High availability tunnels