---
title: TestingBot Tunnel Quickstart - Run Your First Local Test
description: A 5-minute quickstart for TestingBot Tunnel. Download, start the tunnel,
  and run your first Selenium, Cypress, Playwright or Appium test against localhost.
source_url:
  html: https://testingbot.com/support/tunnel/quickstart
  md: https://testingbot.com/support/tunnel/quickstart.md
---

# Your first tunneled test in 5 minutes

This guide gets a Selenium, Cypress, Playwright, Puppeteer or Appium test running against your local development server. If you have not already, [create a free TestingBot account](https://testingbot.com/users/sign_up) before you start.

_TestingBot Tunnel architecture: your client running Selenium, Playwright or Puppeteer connects through an SSH-encrypted tunnel to the TestingBot grid of browsers and devices, with optional access to your staging or internal network_

## Prerequisites

- JAVA 11 or higher. Check with `java -version`.
- ACCOUNT A TestingBot account. The free trial is enough.
- CREDENTIALS Your TestingBot key and secret from [account settings](https://testingbot.com/members/user/edit).
- LOCAL SERVER Anything 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.

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

Prefer Docker or Maven? See the [installation guide](https://testingbot.com/support/tunnel/installation) 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.

```bash
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:

```log
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.

```diff
- 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.

[Java](https://testingbot.com#) [Python](https://testingbot.com#) [NodeJS](https://testingbot.com#) [Ruby](https://testingbot.com#) [C#](https://testingbot.com#)

```java
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();
```

```python
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()
```

```javascript
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();
```

```ruby
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
```

```csharp
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.

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

```bash
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`:

```bash
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](https://testingbot.com/support/tunnel/installation).

## Next steps

[Multiple tunnels](https://testingbot.com/support/tunnel/multiple)

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

[Upstream proxy](https://testingbot.com/support/tunnel/upstream-proxy)

Forward through a corporate or GeoIP proxy.

[Monitoring](https://testingbot.com/support/tunnel/monitoring)

Configure Prometheus and Grafana.

[Security model](https://testingbot.com/support/tunnel/security)

Review SSH encryption and credential handling.

[Troubleshooting](https://testingbot.com/support/tunnel/troubleshooting)

If something goes wrong, this is where to look.

[FAQ](https://testingbot.com/support/tunnel/faq)

Ports, devices, WebSockets and more.

### Looking for more help?

Have questions or need more information? Reach out via email or Slack.

[Email us](https://testingbot.com/contact/new) [Join our Slack](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)