---
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.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

- JAVA 11 or higher (Java 17 LTS recommended). Verify with `java -version`.
- NETWORK Outbound access to `*.testingbot.com` on ports 443 and 22.
- CREDENTIALS A 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.

```bash
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:

```bash
shasum testingbot-tunnel.jar
# expected: 42b7af652d0dc795d8fc3a6aba0c4a430c36166d
```

## Docker

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

```bash
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:

```bash
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.

```xml
<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.

```bash
npm install --save-dev testingbot-tunnel-launcher
```

```javascript
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:

```yaml
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.

```bash
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.

### 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)