--- title: TestingBot Tunnel - Secure Local Testing for Selenium, Cypress, Playwright description: TestingBot Tunnel is a free, open-source secure proxy that lets you run automated and manual tests against localhost or staging environments. Java 11+, Docker and Maven supported. source_url: html: https://testingbot.com/support/tunnel md: https://testingbot.com/support/tunnel.md --- # 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. - v4.8 - Open Source - Free for every plan - Java 11+ `java -jar testingbot-tunnel.jar TESTINGBOT_KEY TESTINGBOT_SECRET` bash [Download v4.8](https://testingbot.com/downloads/testingbot-tunnel.zip) [5-minute quickstart](https://testingbot.com/support/tunnel/quickstart) [View source on GitHub](https://github.com/testingbot/Testingbot-Tunnel) - **Released:** 2026-05-19 - **License:** MIT - **SHA1:** `31c2552b42ecc3642d90c398935255bd6abacbf3` - **Maven:** `com.testingbot:TestingBotTunnel:4.8` - **Docker:** `docker pull testingbot/tunnel` - **Source:** [`github.com/testingbot/Testingbot-Tunnel`](https://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. _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_ 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 ## Quickstart Most teams have the tunnel running in under 5 minutes. The steps below assume Java 11+ is already installed. For Docker, Maven and the NodeJS launcher, see the [installation guide](https://testingbot.com/support/tunnel/installation). 01 Download the tunnel JAR One file, no daemon, no service to install. The JAR is the canonical distribution and runs everywhere Java 11+ runs. ```bash curl -O https://testingbot.com/downloads/testingbot-tunnel.zip unzip testingbot-tunnel.zip ``` 02 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. ```bash java -jar testingbot-tunnel.jar TESTINGBOT_KEY TESTINGBOT_SECRET ``` 03 Point your tests at the local tunnel That is the only change required. All Selenium, Appium, Playwright and Cypress capabilities work the same. ```diff - https://hub.testingbot.com/wd/hub + http://localhost:4445/wd/hub ``` Need more detail? Read the [extended quickstart guide](https://testingbot.com/support/tunnel/quickstart) with language-specific examples. ## Key features Fast Static caching and compression keep round-trip latency low. [See monitoring](https://testingbot.com/support/tunnel/monitoring). Secure SSH-encrypted channel, dedicated ephemeral VM, automatic teardown. [Security model](https://testingbot.com/support/tunnel/security). Robust HTTP/1, /2, /3, WebSockets and SSE. Built for parallel workloads. [Troubleshoot](https://testingbot.com/support/tunnel/troubleshooting). Simple Single JAR or Docker image. Ready in under a minute. [Installation](https://testingbot.com/support/tunnel/installation). ## Documentation Eleven focused guides covering everything from your first test to production monitoring. [Quickstart](https://testingbot.com/support/tunnel/quickstart) Run your first test through the tunnel in 5 minutes. [Installation](https://testingbot.com/support/tunnel/installation) JAR, Docker, Maven and the NodeJS launcher. [CLI reference](https://testingbot.com/support/tunnel/commandline) Every flag, every environment variable. [Examples](https://testingbot.com/support/tunnel/examples) Headers, identifiers, basic auth, custom DNS. [Multiple tunnels](https://testingbot.com/support/tunnel/multiple) Parallel test setups using tunnel identifiers. [Upstream proxy](https://testingbot.com/support/tunnel/upstream-proxy) GeoIP, corporate proxies and PAC files. [Security](https://testingbot.com/support/tunnel/security) SSH encryption, dedicated VMs, certificates. [Monitoring](https://testingbot.com/support/tunnel/monitoring) Prometheus metrics, Grafana dashboards. [Troubleshooting](https://testingbot.com/support/tunnel/troubleshooting) Ports, SSL bumping, slow speeds, disconnects. [FAQ](https://testingbot.com/support/tunnel/faq) Common questions about ports, devices, WS. [Changelog](https://testingbot.com/support/tunnel/changelog) Release notes and version history. [Source on GitHub](https://github.com/testingbot/Testingbot-Tunnel) Open-source project, MIT licensed. ## System requirements - Java 11+ (17 LTS recommended) - RAM 4 GB minimum - CPU 2 cores - OS Windows / 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](https://testingbot.com/support/tunnel/multiple). ## 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 ` ## 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](https://github.com/testingbot/testingbot-tunnel-launcher) — start and stop the tunnel from any npm-based test runner. - **GitHub Actions:** [testingbot-tunnel-action](https://github.com/testingbot/testingbot-tunnel-action) — drop-in workflow step that boots the tunnel before your tests and tears it down after. See the [GitHub Actions guide](https://testingbot.com/support/integrations/ci-cd/github-actions). The tunnel also ships as a Docker image and as a Maven dependency. See the [installation guide](https://testingbot.com/support/tunnel/installation) for all options. [![TestingBot Tunnel architecture diagram](https://testingbot.com/assets/tunnel-diagram-small-af64aa8c1e0d3558a0cc730b3b7cc827264e9af90173acb7627cff04054e1d89.jpg)](https://testingbot.com/assets/tunnel-diagram.png "How the TestingBot Tunnel works") ### 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)