---
title: Install TestingBot Tunnel - JAR, Docker, Maven, NodeJS
description: Install TestingBot Tunnel using the JAR archive, the official Docker
  image, the Maven artifact or the NodeJS launcher. Covers Java prerequisites and
  verification.
source_url:
  html: https://testingbot.com/support/tunnel/installation
  md: https://testingbot.com/support/tunnel/installation/index.md
---
# 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](https://testingbot.com/members/user/edit).

## 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](https://github.com/testingbot/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](https://testingbot.com/support/integrations/ci-cd/github-actions). Source: [testingbot-tunnel-action](https://github.com/testingbot/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](https://testingbot.com/support/tunnel/quickstart). If anything fails, the [troubleshooting guide](https://testingbot.com/support/tunnel/troubleshooting) covers the most common causes.

Was this page helpful? Yes No 

## Looking for More Help?

Have questions or need more information?   
 You can reach us via the following channels:

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