Skip to main content

Specialized Environment Setups

What You'll Need#

Sauce Connect Docker Container Setup#

As an alternative to downloading and installing the SC Client, you can leverage Docker containers to manage Sauce Connect Proxy tunnels. Our Docker image maintained by the Sauce Labs Open Source Program Office.

Here are some benefits/use cases:

  • If you want to run Sauce Connect Proxy as part of a Dockerized CI.
  • If you'd prefer to manage Docker image tags instead of Sauce Connect Proxy versions.
  • If your setup involves several instances running on the same system, Docker would simplify Sauce Connect Proxy port management.

Running the SC Docker Image#

  1. Before running the container, you'll need to pull the Sauce Connect Proxy Docker Image from the Docker Hub. This will always pull the latest version of Sauce Connect Proxy.
    $ docker pull saucelabs/sauce-connect
    • Or - if you do want to use specific SC version - you can specify that as a tag:
      $ docker pull saucelabs/sauce-connect:4.7.1
  2. To run the Sauce Connect Proxy Docker image, execute the below script, which will also set your Sauce Labs username and access key as environment variables.
    $ export SAUCE_USERNAME="my-user"$ export SAUCE_ACCESS_KEY="my-access-key"docker run \    -e SAUCE_USERNAME=${SAUCE_USERNAME} \    -e SAUCE_ACCESS_KEY=${SAUCE_ACCESS_KEY} \    -it saucelabs/sauce-connect

If desired, you can specify any additional SC CLI arguments here.

If your tests are using localhost addresses, you should also set --network="host" as an argument in the above script. Otherwise Sauce Connect within the Docker container will not be able to access your local services in the host machine.

Running the SC Docker Image with a CI/CD Pipeline#

If you want to run this Docker image as part of your CI/CD pipeline, you can run the following steps:

  1. Create a file to ensure we only continue our pipeline.
  2. Once Sauce Connect is fully connected, we need a simple shell script that waits for Sauce Connect to be ready:
    until [ -f /tmp/sc.ready ]do    sleep 5doneecho "SC ready"1. exit2. Pull docker image$ docker pull saucelabs/sauce-connect
  3. Start Sauce Connect using the script below. It is important that you mount a temp folder here so that can detect when Sauce Connect has launched. Also, make sure that you set --network="host" to allow Sauce Connect to access your app in the host machine. This script also sets your Sauce Labs username and access key as environment variables.
    $ docker run \    -e SAUCE_USERNAME=${SAUCE_USERNAME} \    -e SAUCE_ACCESS_KEY=${SAUCE_ACCESS_KEY} \    -v /tmp:/tmp \    --network="host" \    -t saucelabs/sauce-connect:latest \    -f /tmp/sc.ready \    -i some-identifier --detach  $ ./

For additional help, contact Sauce Labs Support or create a GitHub Issue from the Stack Overflow GitHub Repository.

Real Device Cloud Setup#

Real Device Cloud on Sauce Labs offers public and private mobile devices for users looking to expedite automated and live testing for their mobile apps. You can run a high volume of tests across a broad range of real devices without compromising performance, quality, or reliability.

With Sauce Connect Proxy, you’ll have a secure tunnel for testing apps and websites on your local machine (or behind a firewall) against devices and browsers in the Sauce Labs Real Device Cloud.

Security Considerations#

Restricting Tunnel Deployment to Organization Admins#

If you'd like to restrict Sauce Connect Proxy tunnel deployment to organization admins only, follow the steps in Security Settings to only allow organization admins to start Sauce Connect Proxy tunnels.

Testing with Public Devices#

In order to begin running tests on public devices using Sauce Connect Proxy or IPSec VPN, your organization admin must enable this option in their settings. Follow the steps in Security Settings to enable Sauce Connect Proxy/VPN for public cloud devices.

Once the setting is enabled, all users across your organization can run live and automated tests on public devices over Sauce Connect Proxy or IPSec VPN. Each time you initiate a test, you'll see a temporary pop-up alert window with a reminder that the utilization of a trusted Sauce Connect Proxy or IPSec VPN connection combined with RDC public real device tests may not be compliant with your organization's network policy.

Testing Mobile Devices Against localhost#

Testing with the address localhost (or the IP address is not supported with iOS or Android real devices in Sauce Connect Proxy.

To work around this, you'll need to edit your hosts file on the machine on which you are running Sauce Connect Proxy. Add an entry for a dummy hostname (such as localtestsite) and the IP address Requests for localtestsite in your tests will then be sent through your Sauce Connect Proxy tunnel to localhost, which is the machine on which you are running Sauce Connect Proxy.

For tips on editing your hosts file, see How To Edit Hosts File In Linux, Windows, or Mac.

SSL Bumping#

While rare, there are some test cases that will require you to disable SSL Bumping when using Sauce Connect Proxy in order to avoid certificate issues. For more information, see SSL Certificate Bumping.

Selecting the Tunnel to Use#

Sauce Connect Proxy can have multiple tunnels running simultaneously, as described in High Availability Setup. You can select which tunnel to use in a real device test in the same way as you would any other type of automated test.

  1. Start Sauce Command Proxy from the command line, using the -u (--user), -k (--api-key), -r (--region), and --tunnel-name flags.


    In this example, we'll set our credentials (username/access key) as environment variables, start a tunnel in US West Data Center and name the tunnel rdc-on-sauce-tunnel-us.

    ./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -r us-west --tunnel-name rdc-on-sauce-tunnel-us
  2. In your device testing script, specify the tunnel name with tunnelName in your capabilities, as shown in this Java example:

final DesiredCapabilities capabilities = new DesiredCapabilities();    capabilities.setCapability("username", System.getenv("SAUCE_USERNAME"));    capabilities.setCapability("accessKey", System.getenv("SAUCE_ACCESS_KEY"));    capabilities.setCapability("platformName", "Android");    capabilities.setCapability("platformVersion,"  "81.0");    capabilities.setCapability("deviceName", "Samsung_Galaxy_Note_5_real"); // Will only run on the specified device    capabilities.setCapability("tunnelName", "rdc-on-sauce-tunnel-us");final AndroidDriver driver = new AndroidDriver(new URL(""), capabilities);

Selecting the Right Data Center Endpoint#

By default, Sauce Labs will automatically connect you to the main US-West-1 Data Center. For information on Sauce Connect Proxy endpoints, see the Sauce Connect Proxy CLI documentation and Data Center Endpoints.

At present, real device testing is supported in the following data centers:

  • US West Data Center (us-west)
  • EU Central Data Center (eu-central)

Once you establish a Sauce Connect Proxy tunnel for real device testing, you can also use it for virtual devices (and vice versa).

OnDemand Endpoint Examples for Driver Setup#

To ensure you're testing against the correct data center, you'll need to add the correct OnDemand endpoint when you instantiate a MobileDriver in your automated test:

Driver Setup for US Data Center (Java)

final AndroidDriver driver = new AndroidDriver(new URL(""), capabilities);

Headless Setup#

Sauce Headless is a lightweight infrastructure that allows developers to run early pipeline component tests and sanity checks at scale. It is a container-based architecture for the Virtual Machines that host our headless browsers.

At present, Sauce Headless testing is supported in the following data centers:

  • US East Data Center (us-east)

Example of starting Sauce Connect Proxy in conjunction with your Sauce Headless tests:

./sc -u $SAUCE_USERNAME     -k $SAUCE_ACCESS_KEY \     -r us-east \     --tunnel-name {TUNNEL_NAME}

API Testing Setup#

See API Testing with Sauce Connect Proxy to learn how to start a tunnel for API Testing. It requires the use of a YAML config file.

This setup has a unique endpoint, Currently, only the US-West region is supported.

More Information#