Set up Katalon Tunnel with Docker and Kubernetes

Last updated: June 2026

This guide shows you how to set up and deploy the Katalon Tunnel Client in containerized and orchestrated environments. Choose the option that fits your infrastructure:

• Option 1: Pass credentials as environment variables for CI/CD pipelines
• Option 2: Mount a tunnelconfig file for persistent or shared team deployments
• Option 3: Use the Helm chart to run the tunnel as a Kubernetes workload.

Prerequisites

• Docker installed on your machine:
  • If you follow Option 2: Install Docker Compose
  • If you follow Option 3: Install Helm 3.x and a Kubernetes cluster
• A valid Katalon account with API key access.
• Network access to the tunnel outbound endpoints. See: Network configuration for Test Execution - Cloud.

Option 1: Environment variables (CI/CD)

Pass credentials directly as environment variables at runtime. This is the recommended approach for CI/CD pipelines and automated workflows where you don't want to manage a config file.

docker run --rm \
    -e KATALON_USERNAME=john.doe@katalon.com \
    -e KATALON_API_KEY=xxx-e777-436a-xxx-xxx \
    -e KATALON_ACCOUNT_ID=xxxx-285e-549f-806c-xxx \
    -e KATALON_ORGANIZATION_ID=12345678 \
    katalonstudio/katalon-tunnel:latest

Environment variables reference

Variable	Required	Description
KATALON_API_KEY	Yes	Your Katalon API key for authentication
KATALON_USERNAME	Yes	Your Katalon account email address
KATALON_ORGANIZATION_ID	Yes	The numeric ID of your Katalon organization
KATALON_ACCOUNT_ID	Yes	Account identifier (UUID). Used when KATALON_GROUP is not set
KATALON_GROUP	Optional	Group identifier (UUID). Takes precedence over KATALON_ACCOUNT_ID when specified
RELAY_PROTOCOL	Optional	Relay protocol. Defaults to quic (UDP, port 2345). Set to http2 to fall back to HTTP/2 over port 443 — useful when UDP is blocked by a firewall

Option 2: Configuration file with Docker Compose

Before you start

• Make sure you have installed Docker Compose.

Use a tunnelconfig file when you want consistent credentials across a team, or when running the tunnel as a persistent background service on a server.

Step 1: Obtain the tunnelconfig file

Follow the Set up Katalon Tunnel instructions to generate your pre-filled tunnelconfig file from Katalon True Platform.

Alternatively, create a plain text file named tunnelconfig manually with the following content, replacing placeholder values with your own:

allow_hosts = []
api_key = '<your-api-key>'
group = '<your-account-uuid>'
inactive_tunnel_timeout = 0
organization_id = <your-organization-id-number>
private_tunnel = false
server = 'https://tunnel-manager.katalon.com'
tenant = 'TestOps'
username = '<email-owns-the-api-key>'

[internal-proxy]
url = 'socks5h://corporate-proxy:1080'
username = ''
password = ''

tunnelconfig field reference

Field	Description
api_key	Your Katalon API key
group	Your account UUID
organization_id	Your numeric organization ID
username	The email address associated with the API key
inactive_tunnel_timeout	Seconds before an idle tunnel is closed (0 = never)
private_tunnel	Set to true to restrict tunnel access to your account only
server	Tunnel manager endpoint — do not change
tenant	Always TestOps
[internal-proxy]	Optional — fill in if your network requires a corporate proxy

Step 2: Create docker-compose.yaml

Create a docker-compose.yaml in the same directory as your tunnelconfig file:

services:
  katalon-tunnel:
    image: katalonstudio/katalon-tunnel:latest
    restart: unless-stopped
    environment:
      - RELAY_PROTOCOL=http2
    volumes:
      - /path/to/tunnelconfig:/opt/katalon/tunnelconfig

Replace /path/to/tunnelconfig with the absolute path to your tunnelconfig file on the host machine.

Alternatively, run the container directly with the file mounted:

docker run --rm \
    -v /path/to/tunnelconfig:/opt/katalon/tunnelconfig \
    katalonstudio/katalon-tunnel:latest

Step 3: Start the tunnel

• Start the tunnel:

  docker compose up -d

• Verify the container is running:

  docker compose ps

• View live logs to confirm the tunnel connected successfully:

  docker compose logs -f

• Stop the tunnel:

  docker compose down

Option 3: Helm chart (Kubernetes)

Before you start

• Make sure you have installed Helm 3.x and a Kubernetes cluster.

Use the Helm chart to deploy the Katalon Tunnel Client into a Kubernetes cluster. This is the recommended approach for teams already running workloads on Kubernetes.

Step 1: Add the Helm repository

helm repo add katalon-tunnel https://raw.githubusercontent.com/katalon-studio/katalon-proxy-tunnel-client/refs/heads/release
helm repo update

Step 2: Install the chart

Using --set flags

Pass credentials directly on the install command:

helm install katalon-tunnel katalon/katalon-tunnel \
  --set tunnel.username="<your-email>" \
  --set tunnel.apiKey="<your-api-key>" \
  --set tunnel.accountId="<your-account-uuid>" \
  --set tunnel.organizationId=<your-org-id>

Using a values.yaml file

Create a values.yaml file:

tunnel:
  username: "<your-email>"
  apiKey: "<your-api-key>"
  accountId: "<your-account-uuid>"
  organizationId: <your-org-id>
  group: "<optional-tunnel-group>"

Then install into a namespace:

helm install -n <namespace> katalon-tunnel katalon/katalon-tunnel -f values.yaml

Upgrade and uninstall

Upgrade an existing release:

helm upgrade -n <namespace> katalon-tunnel katalon/katalon-tunnel -f values.yaml

Uninstall:

helm uninstall -n <namespace> katalon-tunnel

Available image tags

Tag	Description
latest	Latest stable release
1.0.1	Latest stable release

Browse all available tags on Docker Hub.

Troubleshooting

Symptom	Possible cause	Resolution
Container exits immediately	Invalid or missing tunnelconfig	Verify the file path and field values
Authentication error in logs	Incorrect api_key or username	Re-check credentials in the Katalon True Platform
Cannot reach tunnel endpoints	Firewall blocking outbound traffic	Allow outbound HTTPS/H2 to the three endpoints listed in Prerequisites
Proxy connection failure	Incorrect [internal-proxy] settings	Verify proxy URL, username, and password