---
title: 'Configure TestingBot Tunnel: Config File and Environment Variables'
description: Configure TestingBot Tunnel with command-line flags, a --config file
  or TESTINGBOT_* environment variables. Precedence rules, file format and keeping
  credentials out of the process list.
source_url:
  html: https://testingbot.com/support/tunnel/configuration
  md: https://testingbot.com/support/tunnel/configuration.md
---

# Flags, files and environment

Tunnel options can be set three ways: on the command line, in a `--config` file, or as a `TESTINGBOT_*` environment variable. That lets a container or CI job be configured without assembling a long command line.

- Since v5.0 

## Three ways, one order

When an option is set in more than one place, the **command line** wins, then the **config file** , then the **environment**.

```bash
# these three are equivalent
java -jar testingbot-tunnel.jar --se-port 4446

echo "se-port = 4446" > tunnel.conf
java -jar testingbot-tunnel.jar --config tunnel.conf

TESTINGBOT_SE_PORT=4446 java -jar testingbot-tunnel.jar
```

The environment comes last because it is the most ambient of the three, and the least likely to be what someone meant when they also typed a flag or wrote a file.

## Config file

A properties file. Keys are the long option names without the leading dashes. Lines starting with `#` are comments.

```properties
# testingbot-tunnel.conf
# Run with: java -jar testingbot-tunnel.jar --config testingbot-tunnel.conf

tunnel-identifier = staging
se-port = 4445
metrics-port = 8003

# Upstream proxy: host:port (HTTP), http://host:port or socks5://host:port
proxy = corp-proxy.internal:8080

# Only reach these hosts; everything else gets 403
allow-hosts = staging.example.com,*.internal.example

# Domains to refuse (comma separated regular expressions).
# Backslashes must be doubled in this file.
fast-fail-regexps = .*\\.doubleclick\\.net,.*google-analytics\\.com

# Boolean options: true to enable, omit or false to leave off
shared = true
nobump = false
```

- Boolean options accept `true`, `yes`, `on` or `1`. Anything else, including `false`, leaves the option off.
- A boolean set to `false` in the file is not overridden by the environment, so `shared = false` stays off even if `TESTINGBOT_SHARED=true` is set.
- The file is read as a Java properties file, so a backslash is an escape character. Write a regular expression's `\.` as `\\.`, or it reaches the tunnel as a bare `.`.
- An unknown key stops the tunnel at startup rather than being ignored, so a typo does not silently drop a setting.
- Anything given explicitly on the command line still wins over the file.
- Run `--help` to list every option, or see the [CLI reference](https://testingbot.com/support/tunnel/commandline).

 When to use a file 

A file is the easiest way to manage long `--allow-hosts` or `--fast-fail-regexps` lists, to keep a tunnel's setup in version control, and to share one setup between developers. Keep credentials out of it: use the environment for those.

## Environment variables

Long options have a `TESTINGBOT_*` alias, derived from its name: upper-case it, replace dashes with underscores and prefix `TESTINGBOT_`. The few exceptions are listed below the table.

| Option | Environment variable |
| --- | --- |
| --se-port | `TESTINGBOT_SE_PORT` |
| --tunnel-identifier | `TESTINGBOT_TUNNEL_IDENTIFIER` |
| --allow-hosts | `TESTINGBOT_ALLOW_HOSTS` |
| --bind-address | `TESTINGBOT_BIND_ADDRESS` |
| --log-http | `TESTINGBOT_LOG_HTTP` |
| --shared | `TESTINGBOT_SHARED=true` |

A few options have no environment alias because they make no sense on every run: `--help`, `--version`, `--doctor`, `--ready` and `--config`. `TESTINGBOT_AUTH` is special: it takes a comma-separated list of `host:port:user:password` entries, one per `--auth`.

This is what makes the [Docker image](https://testingbot.com/support/tunnel/installation#docker) configurable from a compose file or a Kubernetes manifest:

```bash
docker run --rm \
  -e TESTINGBOT_KEY=... -e TESTINGBOT_SECRET=... \
  -e TESTINGBOT_TUNNEL_IDENTIFIER=ci-$BUILD_ID \
  -e TESTINGBOT_ALLOW_HOSTS=staging.example.com \
  testingbot/tunnel:5.0
```

## Where the tunnel reads your key and secret

- Positional arguments: `java -jar testingbot-tunnel.jar KEY SECRET`
- `client-key` and `client-secret` in a `--config` file
- The `TESTINGBOT_KEY` and `TESTINGBOT_SECRET` environment variables
- A `~/.testingbot` file containing `key:secret`

Get your key and secret from your [account page](https://testingbot.com/members/user/edit).

## Keeping credentials out of the process list

Anything on the command line is visible to other users of the machine in `ps`. Options that carry a secret are better set in the environment.

| Option | Environment variable | Format |
| --- | --- | --- |
| KEY SECRET | `TESTINGBOT_KEY`, `TESTINGBOT_SECRET` | your account credentials |
| --auth | `TESTINGBOT_AUTH` | `host:port:user:password`, comma-separated for several |
| --proxy-userpwd | `TESTINGBOT_PROXY_USERPWD` | `user:password` |
| --proxy-testingbot-userpwd | `TESTINGBOT_PROXY_TESTINGBOT_USERPWD` | `user:password` |
| --metrics-auth | `TESTINGBOT_METRICS_AUTH` | `user:password` |

 Positional credentials 

The positional `KEY SECRET` form is still supported, but it puts your secret in `ps` for as long as the tunnel runs. On a shared machine or CI runner, prefer `TESTINGBOT_KEY` / `TESTINGBOT_SECRET` or `~/.testingbot`. A flag always wins over the matching variable.

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