Secure tunnel for local and staging tests

A free, open-source secure proxy that lets you run Selenium, Cypress, Playwright, Puppeteer and Appium tests against localhost, staging servers or any environment behind a firewall or VPN. No IP whitelisting required.

v5.0
Open Source
Free for every plan
Java 17+ or standalone

java -jar testingbot-tunnel.jar TESTINGBOT_KEY TESTINGBOT_SECRET bash

Download v5.0 5-minute quickstart View source on GitHub

Released: 2026-10-02
License: MIT
SHA-256 (zip): e0306bc1bf495f5836a9939b18b7c9ba768b28ce49b9de969e3b140423ad0090
Maven: com.testingbot:TestingBotTunnel:5.0
Docker: docker pull testingbot/tunnel:5.0
Source: github.com/testingbot/Testingbot-Tunnel

What is TestingBot Tunnel?

A Java application that proxies HTTP, HTTPS and WebSocket traffic between your network and the TestingBot browser and device grid.

When the tunnel is running, every request your test makes to localhost:4445/wd/hub is forwarded over an SSH-encrypted channel to a dedicated VM in the TestingBot cloud. That VM then routes browser traffic back through the tunnel to your local server, so the cloud browser can reach pages on your laptop, your CI runner or your private staging environment without any firewall or IP-whitelisting changes.

At a glance

Encryption: SSH
Protocols: HTTP/1, /2, /3, WS, SSE
Outbound ports: 443 + 22
Architecture: Java 17, standalone builds

Quickstart

Most teams have the tunnel running in under 5 minutes. The steps below use the JAR and assume Java 17+ is installed. No Java? Use a self-contained build. For Docker, Maven and the NodeJS launcher, see the installation guide.

Download the tunnel JAR

One file, no daemon, no service to install. The JAR runs everywhere Java 17+ runs.

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

Start the tunnel with your credentials

Wait for the message You may start your tests. The tunnel provisions a dedicated VM in the TestingBot cloud and opens an SSH-encrypted channel.

java -jar testingbot-tunnel.jar TESTINGBOT_KEY TESTINGBOT_SECRET

Point your tests at the local tunnel

That is the only change required. All Selenium, Appium, Playwright and Cypress capabilities work the same.

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

Need more detail? Read the extended quickstart guide with language-specific examples.

Downloads

Version 5.0, released 2026-10-02. The JAR needs Java 17 or newer. The self-contained builds bundle a trimmed Java runtime, so nothing has to be installed. Upgrading from 4.x? Read what changes in 5.0 first.

Platform	Download	Size	SHA-256
Any OS with Java 17+	`testingbot-tunnel.zip`	7.2 MB	`e0306bc1bf495f5836a9939b18b7c9ba768b28ce49b9de969e3b140423ad0090`
Linux x64	`testingbot-tunnel-linux-x64.tar.gz`	31.1 MB	`88f4edcd4b88f174bdc89074ef2f24176dc4dfcff625f12fea0ea84748f47030`
Linux arm64	`testingbot-tunnel-linux-arm64.tar.gz`	30.8 MB	`a8a5e591799e5acbbd706a84f05259e0a79716a1bdae17d725da1a8fbc0cefb1`
macOS Apple silicon	`testingbot-tunnel-macos-arm64.tar.gz`	27.3 MB	`ae796c03b6ba8e332a9cc36035f4354afa456da4a35688d96e5986b58cbb93cf`
macOS Intel	`testingbot-tunnel-macos-x64.tar.gz`	28.1 MB	`193720f150388b145cce8ddcc18ffb6b21a27b0d8a12d5f8e6f9b30f53f0fb72`
Windows x64	`testingbot-tunnel-windows-x64.zip`	28.9 MB	`7c6f1150e0732e4e20e4fcb63d75784f33c1f69aeb99366db6c584b4a190b67a`

Self-contained builds unpack to a folder with a bin/testingbot-tunnel launcher (bin\testingbot-tunnel.cmd on Windows) that takes the same options as the JAR. The macOS builds are signed and notarized.

tar -xzf testingbot-tunnel-macos-arm64.tar.gz
./testingbot-tunnel-macos-arm64/bin/testingbot-tunnel --version

Also available as

Docker: testingbot/tunnel:5.0
Maven Central: com.testingbot:TestingBotTunnel:5.0
Every file with its .sha256 on the GitHub release

Key features

Fast

Static caching and compression keep round-trip latency low. See monitoring.

Secure

SSH-encrypted channel, dedicated ephemeral VM, automatic teardown. Security model.

Robust

HTTP/1, /2, /3, WebSockets and SSE. Built for parallel workloads. Troubleshoot.

Simple

Single JAR, standalone binary or Docker image. Ready in under a minute. Installation.

Documentation

Focused guides covering everything from your first test to production monitoring.

Quickstart

Run your first test through the tunnel in 5 minutes.

Installation

JAR, standalone builds, Docker, Maven, NodeJS.

Upgrading to 5.0

Java 17, loopback listeners, quieter logs.

Configuration

Config files and TESTINGBOT_* variables.

CLI reference

Every flag, every environment variable.

Examples

Headers, identifiers, basic auth, custom DNS.

Multiple tunnels

Parallel test setups using tunnel identifiers.

Upstream proxy

HTTP and SOCKS5 proxies, PAC files.

Authentication

Basic auth and Kerberos for sites and proxies.

Traffic rules

Allow-lists, fast-fail, localhost policy, DNS.

SSL bumping

Certificates, --nobump and corporate CAs.

Header rewriting

Add, replace or remove HTTP headers.

Security

SSH encryption, dedicated VMs, certificates.

Health checks

/readyz, Docker and Kubernetes probes.

Logging

HTTP logs, JSON output, request IDs.

Monitoring

Prometheus metrics, Grafana dashboards.

Embedding (Java)

Start and stop the tunnel from your tests.

Troubleshooting

Ports, SSL bumping, slow speeds, disconnects.

FAQ

Common questions about ports, devices, WS.

Changelog

Release notes and version history.

Source on GitHub

Open-source project, MIT licensed.

System requirements

Java17+, or none with a standalone build
RAM4 GB minimum
CPU2 cores
OSWindows / macOS / Linux / BSD

Outbound only

The tunnel needs outbound port 443 (HTTPS) and 22 (SSH) to *.testingbot.com. No inbound ports required.

For heavy parallel testing, scale CPU and RAM with concurrent sessions, or run multiple tunnels.

Graceful shutdown

Stop the tunnel cleanly so the cloud can deregister your VM and free your tunnel slot.

Option 1

Press Ctrl+C

In the terminal that runs the tunnel.

Option 2

Delete the PID file

~/.testingbot-tunnel.pid

Option 3

Send a signal

kill -SIGUSR1 <pid>

Stopping a tunnel

Stop a running tunnel from your terminal, the dashboard or the API, for example when a CI job exited without cleaning up.

CLI

Press Ctrl+C

Or use any of the graceful shutdown options above.

Dashboard

Tunnels page, Stop button

Open /members/tunnels and click Stop on the tunnel's row.

API

DELETE /v1/tunnel/{id}

Get the id from GET /v1/tunnel/list. See the API reference.

Who can stop a tunnel

On a team, every member can see all of the team's tunnels. A tunnel can be stopped by:

the person who started it (the tunnel's Owner column),
the team owner,
any team member with the Admin role.

The same rule applies to the dashboard and the API. Other members see the tunnel but no Stop button.

Tunnel clients

Launch and stop the tunnel programmatically from your test runner or CI pipeline.

Two official launchers handle the tunnel lifecycle so you do not have to manage the JAR yourself:

NodeJS: testingbot-tunnel-launcher — start and stop the tunnel from any npm-based test runner.
GitHub Actions: testingbot-tunnel-action — drop-in workflow step that boots the tunnel before your tests and tears it down after. See the GitHub Actions guide.

The tunnel also ships as a Docker image and as a Maven dependency. See the installation guide for all options.