Install the tunnel
Pick the flavour that fits your environment best. The single-file JAR works everywhere with Java 17+. The standalone builds for Linux, macOS and Windows need no Java at all. Docker is the easiest way to run the tunnel in CI. The Maven artifact and NodeJS launcher let you embed the tunnel in your existing build tooling.
Before you install
-
Java17 or higher for the JAR. Verify with
java -version. Not needed for the standalone builds or Docker. -
NetworkOutbound access to
*.testingbot.comon ports 443 and 22. - CredentialsA TestingBot key and secret from account settings.
JAR
One file, no daemon, no service to install. Runs on any OS with Java 17 or newer.
curl -O https://testingbot.com/downloads/testingbot-tunnel.zip
unzip testingbot-tunnel.zip
java -jar testingbot-tunnel.jar TESTINGBOT_KEY TESTINGBOT_SECRET
Verify the download checksum before running:
echo "6423dfde0b9206e93fc7ff443c8f87ab90dbbe8d452ffbb77a9bee100ed6f76e testingbot-tunnel.jar" | sha256sum -c -
On macOS, use shasum -a 256 -c - instead of sha256sum -c -. Both print testingbot-tunnel.jar: OK when the file matches.
Standalone builds
Self-contained archives for Linux, macOS and Windows that bundle a trimmed Java runtime. Unpack and run, nothing else to install. Each archive has a .sha256 file next to it on the GitHub release.
Linux and macOS:
curl -LO https://github.com/testingbot/Testingbot-Tunnel/releases/download/v5.2/testingbot-tunnel-linux-x64.tar.gz
curl -LO https://github.com/testingbot/Testingbot-Tunnel/releases/download/v5.2/testingbot-tunnel-linux-x64.tar.gz.sha256
sha256sum -c testingbot-tunnel-linux-x64.tar.gz.sha256 # macOS: shasum -a 256 -c
tar -xzf testingbot-tunnel-linux-x64.tar.gz
./testingbot-tunnel-linux-x64/bin/testingbot-tunnel TESTINGBOT_KEY TESTINGBOT_SECRET
Windows (PowerShell):
Invoke-WebRequest -OutFile testingbot-tunnel-windows-x64.zip https://github.com/testingbot/Testingbot-Tunnel/releases/download/v5.2/testingbot-tunnel-windows-x64.zip
Expand-Archive testingbot-tunnel-windows-x64.zip -DestinationPath .
.\testingbot-tunnel-windows-x64\bin\testingbot-tunnel.cmd TESTINGBOT_KEY TESTINGBOT_SECRET
The launcher takes exactly the same options as the JAR, so every example in these docs works by replacing java -jar testingbot-tunnel.jar with bin/testingbot-tunnel.
Docker
The official image is published as testingbot/tunnel on Docker Hub and supports both amd64 and arm64.
docker pull testingbot/tunnel:5.2
docker run --rm -it \
--network host \
-e TESTINGBOT_BIND_ADDRESS=127.0.0.1 \
-e TESTINGBOT_KEY=your_key \
-e TESTINGBOT_SECRET=your_secret \
testingbot/tunnel:5.2
The image listens on every interface inside the container, so that published ports work. With --network host the container shares your machine's interfaces, which is why the command above sets TESTINGBOT_BIND_ADDRESS=127.0.0.1: the Selenium relay carries your credentials and should not be reachable from your network.
--network host only works fully on Linux. On macOS and Windows, publish the ports explicitly, on the loopback address:
docker run --rm -it \
-p 127.0.0.1:4445:4445 -p 127.0.0.1:8087:8087 -p 127.0.0.1:8003:8003 \
-e TESTINGBOT_KEY=$TESTINGBOT_KEY \
-e TESTINGBOT_SECRET=$TESTINGBOT_SECRET \
testingbot/tunnel:5.2
Almost every tunnel option can be passed as a TESTINGBOT_* environment variable, see configuration. The image has a built-in health check, see health checks.
Maven
Add the tunnel as a dependency to your pom.xml and start it from a JUnit or TestNG fixture. See embedding for the API.
<dependency>
<groupId>com.testingbot</groupId>
<artifactId>TestingBotTunnel</artifactId>
<version>5.2</version>
</dependency>
NodeJS launcher
For npm-based projects, use the testingbot-tunnel-launcher package to start and stop the tunnel programmatically. The launcher downloads the tunnel JAR and runs it with your local java, so it needs Java 17 or newer on your PATH.
npm install --save-dev testingbot-tunnel-launcher
const testingbotTunnel = require("testingbot-tunnel-launcher");
testingbotTunnel({
apiKey: process.env.TESTINGBOT_KEY,
apiSecret: process.env.TESTINGBOT_SECRET,
}, (err, tunnel) => {
if (err) throw err;
// your tests here
tunnel.close(() => console.log("tunnel closed"));
});
Source on GitHub: testingbot-tunnel-launcher.
GitHub Action
If your tests run in GitHub Actions, the official testingbot/testingbot-tunnel-action handles the entire tunnel lifecycle for you. It pulls the latest Docker image, starts the tunnel before your test step, waits for the ready signal, and tears it down when the workflow ends.
Add it as a step in your workflow, before the step that runs your tests:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: testingbot/testingbot-tunnel-action@v1
with:
key: ${{ secrets.TB_KEY }}
secret: ${{ secrets.TB_SECRET }}
tunnelIdentifier: github-action-tunnel
- name: Run tests
run: npm test
env:
TB_KEY: ${{ secrets.TB_KEY }}
TB_SECRET: ${{ secrets.TB_SECRET }}
The action supports every tunnel flag as a workflow input: tunnelIdentifier, noBump, noCache, proxy, extraHeaders, fastFailRegexps and more. It also uploads the tunnel log as a workflow artifact by default for easy debugging.
Full reference and example workflows: GitHub Actions integration guide. Source: testingbot-tunnel-action.
Sanity check with --doctor
Once the tunnel is installed, run the built-in health check. It verifies that the required local ports are free, that outbound connectivity to TestingBot works, and that your credentials are valid.
java -jar testingbot-tunnel.jar --doctor
Pass the same options you normally start the tunnel with: --doctor checks the configuration it is given, including upstream proxies, Kerberos and any --cacert-file.
If all checks pass, continue with the quickstart. If anything fails, the troubleshooting guide covers the most common causes.