Install in four flavours

Pick the flavour that fits your environment best. The single-file JAR is the simplest and works everywhere with Java 11+. 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

JAVA11 or higher (Java 17 LTS recommended). Verify with java -version.
NETWORKOutbound access to *.testingbot.com on ports 443 and 22.
CREDENTIALSA TestingBot key and secret from account settings.

JAR

The JAR is the canonical distribution. One file, no daemon, no service to install.

curl -O https://testingbot.com/downloads/testingbot-tunnel.zip
unzip testingbot-tunnel.zip
cd testingbot-tunnel
java -jar testingbot-tunnel.jar TESTINGBOT_KEY TESTINGBOT_SECRET

Verify the download checksum before running:

shasum testingbot-tunnel.jar
# expected: 42b7af652d0dc795d8fc3a6aba0c4a430c36166d

Docker

The official image is published as testingbot/tunnel on Docker Hub and supports both amd64 and arm64.

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 ports explicitly:

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

Maven

Add the tunnel as a dependency to your pom.xml and start it from a JUnit or TestNG fixture.

<dependency>
  <groupId>com.testingbot</groupId>
  <artifactId>TestingBotTunnel</artifactId>
  <version>4.7</version>
</dependency>

NodeJS launcher

For npm-based projects, use the testingbot-tunnel-launcher package to start and stop the tunnel programmatically. The launcher handles downloading the right JAR for your platform.

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

If all checks pass, continue with the quickstart. If anything fails, the troubleshooting guide covers the most common causes.