The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing


External Resources

More Info

Page tree
Skip to end of metadata
Go to start of metadata

PAGE DEPRECATED: Updated content located here.

Enterprise Plans Only

This feature is available for Enterprise plans only. For more information about other benefits that are included with Enterprise plans, check out our Pricing page.

Sauce Connect Proxy provides a secure tunnel for testing applications and websites that are on your local machine or behind a firewall, against devices and browsers in the Sauce Labs Real Device Cloud. The topics in Sauce Connect Proxy contain detailed information about security, network configurations for setting up Sauce Connect Proxy, and the Sauce Connect Command Line Reference. This topic describes special features of using Sauce Connect Proxy to test with real devices. 

Known Limitations

These are the known limitations of Sauce Connect Proxy for real device testing:

  • You must specify your username in all lower-case. For example, if your RDC username is SuperTester1, please specify supertester1 as the username when starting Sauce Connect

  • Testing with the address localhost (or the IP address is not supported with iOS devices and Sauce Connect Proxy due to an iOS restriction. To work around this, add an entry in the hosts file on the machine where you are running Sauce Connect Proxy with an entry for a dummy hostname (such as localtestsite) and the IP address Then if you make requests for localtestsite in your tests, these will be sent through the Sauce Connect tunnel to localhost, which is the machine where Sauce Connect Proxy is running.

Enabling Sauce Connect Proxy Access to Public Cloud Devices

Risk Advisory

Use of Sauce Connect tunnels to connect to devices in Sauce Labs’ public real device cloud (RDC), where unrelated users may access a shared pool of real devices, is an optional feature that involves tradeoffs between convenience and security. While we take multiple actions after a test session to delete installed mobile applications and erase memory, Sauce Labs does not factory reset devices in the public RDC between test sessions and these devices do not have anti-virus software installed on them.  It is possible that users of the public RDC may engage in malicious, careless or unsecure activity, and that sophisticated, persistent malware could therefore be present on any device in the public RDC.  Use of Sauce Connect tunnels to connect to devices the public RDC may only be undertaken with awareness of the risk of the potential presence of third party malware (i.e., virus, worm, Trojan horse, spyware or other malicious or unwanted software code) on any device in the public RDC, and based on the user’s determination that convenience improvements outweigh increased security risks.

By enabling Sauce Connect for Public Cloud, I acknowledge having read the foregoing risk advisory and I confirm, on my own behalf and on behalf of the organization associated with my Sauce Labs account, that I understand the risks associated with using Sauce Connect tunnels to connect to devices in Sauce Labs’ public real device cloud, elect to do so anyway, and assume all risk and responsibility for this decision.

If you want to allow your team members to have access to public cloud devices through Sauce Connect Proxy, you must enable this option in the team parent user. 

Admins Only

Only account owners or administrators can enable public cloud access for their user and team members, individual users cannot enable access for themselves. If you need to access public cloud devices with Sauce Connect Proxy, contact your Sauce Labs account administrator.

  1. Log into the TestObject web interface.
  2. Go to the Account Settings page and select Sauce Connect tab.
  3. Review the Sauce Connect for Public Cloud Risk Advisory and if approved select Allow Sauce Connect for Public Cloud

Selecting the Tunnel to Use

Sauce Connect Proxy can have multiple tunnels running simultaneously, as described in PAGE DEPRECATED: Using Sauce Connect Tunnel Identifiers. 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, providing a  --tunnel-identifer  to start a new tunnel with that identifier.

    ./sc -u <RDC_username> -k <RDC_Sauce_Connect_API_Key> -x <RDC_API_ENDPOINT> -i <Tunnel_Id>
  2. In your device testing script, specify the tunnel to use for the test in your desired capabilities, as show in this Java example:

    final DesiredCapabilities capabilities = new DesiredCapabilities();
    capabilities.setCapability("testobject_api_key", <RDC_API_Key>);
    capabilities.setCapability("deviceName", "Samsung_Galaxy_Note_5_real"); // Will only run on the specified device
    capabilities.setCapability("tunnelIdentifier", "sample-tunnel");
    final AndroidDriver driver = new AndroidDriver(new URL(""), capabilities);

Finding Your RDC Sauce Connect API Key

You need a Real Device Cloud (RDC) API key to start Sauce Connect Proxy for testing on real devices. This key is required only for using Sauce Connect Proxy with real devices. For emulator and simulator tests with Sauce Connect Proxy you only need to use your Sauce Labs authentication credentials. You can find your RDC API key in your RDC account information.

  1. Log in to your account at
  2. In your user profile menu, select Account Settings.
  3. Click Authentication.
  4. Copy the API key and use it for <RDC_Sauce_Connect_API_Key> in the command line when you start Sauce Connect Proxy.

Selecting a Real Device Testing Center

Sauce Labs has two data centers for real device testing, one in the United States, and another in Europe. You can specify which to use through the URL in the desired capabilities of your test script. In these two examples, the URL is set first for the data center in the United States, while in the second example uses the data center in Europe.

URL for US RDC Data Center
final AndroidDriver driver = new AndroidDriver(new URL(""), capabilities); 
URL for EU RDC Data Center
final AndroidDriver driver = new AndroidDriver(new URL(""), capabilities);