Prerequisites

JAVA11 or higher. Check with java -version.
ACCOUNTA TestingBot account. The free trial is enough.
CREDENTIALSYour TestingBot key and secret from account settings.
LOCAL SERVERAnything that responds on a local port, e.g. localhost:3000.

Download the tunnel

Download the latest JAR and unzip it. Place testingbot-tunnel.jar anywhere on your PATH, or run it from the unzipped folder.

curl -O https://testingbot.com/downloads/testingbot-tunnel.zip
unzip testingbot-tunnel.zip
cd testingbot-tunnel

Prefer Docker or Maven? See the installation guide for every install method.

Start the tunnel

Pass your TestingBot key and secret. You can also export them as environment variables so they never appear in your shell history.

java -jar testingbot-tunnel.jar TESTINGBOT_KEY TESTINGBOT_SECRET

You will see log output as the tunnel provisions a dedicated VM in the TestingBot cloud and opens an SSH-encrypted channel. After 30 to 60 seconds, you will see:

You may start your tests

The tunnel is now listening on localhost:4445 for your Selenium and Appium clients.

Run your first test

Change the hub URL in your test runner from the public TestingBot hub to your local tunnel endpoint. That is the only change required.

- https://hub.testingbot.com/wd/hub
+ http://localhost:4445/wd/hub

Run your tests as you normally would, and the cloud browser will reach your localhost via the tunnel.

Language examples

The same first test in five common languages. Each one points the WebDriver at the local tunnel hub.

DesiredCapabilities caps = new DesiredCapabilities();
caps.setCapability("browserName", "chrome");
caps.setCapability("platformName", "WIN11");

WebDriver driver = new RemoteWebDriver(
  new URL("http://KEY:SECRET@localhost:4445/wd/hub"),
  caps);

driver.get("http://localhost:3000");
System.out.println(driver.getTitle());
driver.quit();

from selenium import webdriver

options = webdriver.ChromeOptions()
options.set_capability("platformName", "WIN11")

driver = webdriver.Remote(
    command_executor="http://KEY:SECRET@localhost:4445/wd/hub",
    options=options,
)
driver.get("http://localhost:3000")
print(driver.title)
driver.quit()

const { remote } = require("webdriverio");

const browser = await remote({
  hostname: "localhost",
  port: 4445,
  path: "/wd/hub",
  user: "KEY",
  key: "SECRET",
  capabilities: { browserName: "chrome", platformName: "WIN11" },
});

await browser.url("http://localhost:3000");
console.log(await browser.getTitle());
await browser.deleteSession();

require "selenium-webdriver"

caps = Selenium::WebDriver::Remote::Capabilities.new
caps["browserName"] = "chrome"
caps["platformName"] = "WIN11"

driver = Selenium::WebDriver.for(:remote,
  url: "http://KEY:SECRET@localhost:4445/wd/hub",
  capabilities: caps)

driver.navigate.to "http://localhost:3000"
puts driver.title
driver.quit

var options = new ChromeOptions();
options.AddAdditionalCapability("platformName", "WIN11", true);

IWebDriver driver = new RemoteWebDriver(
  new Uri("http://KEY:SECRET@localhost:4445/wd/hub"),
  options);

driver.Navigate().GoToUrl("http://localhost:3000");
Console.WriteLine(driver.Title);
driver.Quit();

Run with Docker

Prefer not to install Java locally? The official testingbot/tunnel image on Docker Hub bundles everything you need. It supports both amd64 and arm64 and is the easiest way to run the tunnel from CI or a containerised dev environment.

Pull the image from Docker Hub.
Start the tunnel, passing your TestingBot key and secret as environment variables.
Point your tests at http://localhost:4445/wd/hub, exactly the same as the JAR version.

docker pull testingbot/tunnel

docker run --rm -it \
  --network host \
  -e TESTINGBOT_KEY=YOUR_KEY \
  -e TESTINGBOT_SECRET=YOUR_SECRET \
  testingbot/tunnel

--network host only works fully on Linux. On macOS and Windows, expose the ports explicitly so your tests can reach the tunnel on localhost:4445:

docker run --rm -it \
  -p 4445:4445 -p 8087:8087 -p 8003:8003 \
  -e TESTINGBOT_KEY=$TESTINGBOT_KEY \
  -e TESTINGBOT_SECRET=$TESTINGBOT_SECRET \
  testingbot/tunnel

Once the container prints You may start your tests, the tunnel is ready. Stop it gracefully with Ctrl+C. For Compose, Maven and the NodeJS launcher, see the installation guide.

Next steps

Multiple tunnels

Add identifiers to run more than one tunnel at a time.

Upstream proxy

Forward through a corporate or GeoIP proxy.

Monitoring

Configure Prometheus and Grafana.

Security model

Review SSH encryption and credential handling.

Troubleshooting

If something goes wrong, this is where to look.

FAQ

Ports, devices, WebSockets and more.