Run Katalon Test Cloud tests against a private or IP-whitelisted environment with Katalon Tunnel

This guide is for teams whose QA or UAT environment sits behind IP whitelisting or a private network, and who want business or QA users to run tests without installing anything on their own machines.

Is this you?

  • Your QA or UAT application is only reachable through IP whitelisting or a private network. It isn’t open to the public internet.
  • A small automation team keeps the test scripts in a shared repository (Bitbucket, GitHub, GitLab, or Azure Repos). A bigger group of business or QA users only needs to run tests that already exist.
  • You don’t want each of those users to install Katalon Studio or do any local setup just to start a test.
  • You’d rather not buy and maintain your own machines for running tests.
  • You already have Katalon Test Cloud session licenses, or you’re open to getting them.

How it works

Tests run on Katalon’s cloud infrastructure. One tunnel, set up once on one machine inside your network, lets that cloud execution reach your private environment.

Business and QA users (browser only)
   → Katalon True Platform (Katalon TestOps) (trigger the run, see the report)
   → Katalon Test Cloud (where the tests run)
   → Katalon Tunnel (1 machine in your network, set up once)
   → Your private QA / UAT environment (IP-whitelisted)

Users never touch the tunnel. It runs on that one machine and connects the cloud to your private network in the background.

What this solves

“We don’t want every user to install or set up a tunnel.”
The tunnel is set up once, on one machine your admin controls. Business users never see it. They log in to True Platform in their browser and click Run. Setting up the tunnel is a one-time job for one person, not a step for every user.

“Our QA/UAT environment is IP-restricted. Can the cloud even reach it?”
Yes. Traffic from Test Cloud goes through the tunnel machine, so it reaches your environment as if it came from inside your network. Only the tunnel machine needs to be inside your whitelist, not each test run.

“We don’t want to install Katalon Studio on every laptop.”
Nothing is installed on business users’ machines. Your automation engineers maintain the scripts in your repository and connect it to True Platform once. After that, users only work in the browser.

“We want results, logs, and reports in one place.”
Every test run, whoever started it, reports into the same True Platform project. You review pass and fail results, history, and trends in one place.

Who does what

Who What they do Where How often
Account or System Admin Download and start the Katalon Tunnel client with a generated config command One machine inside your network that can reach the QA/UAT app Once (restart it if the machine reboots)
IT or network team Allow outbound HTTPS and QUIC from that machine to the tunnel server domains Corporate firewall or proxy settings Once
Automation engineer Connect the script repository to the True Platform project, and refresh it after merges True Platform project settings After every merge
Anyone running a test Create and run an automated test run, turn on Private/Local Testing, and pick the tunnel True Platform, in the browser Each run

Video walkthrough: Setting up Katalon Tunnel step by step

Capacity and licensing

Test Cloud uses session-based licensing. The number of sessions you have is the maximum number of test runs that can run at the same time. If someone starts a run when all sessions are busy, the run waits in a queue and starts when a session is free. It doesn’t fail.

Before you plan parallel runs, check how many Test Cloud sessions your account has under Account Settings > License Utilization. That number is your limit for runs at the same time, however many people are starting tests.

If you need more runs at the same time than that, your options depend on what your account already has:

  • Buy more Test Cloud sessions.
  • If your account also has Katalon Runtime Engine (KRE) licenses, run the extra tests through a self-hosted Katalon Agent instead.

Each option has its own license type and session count. Check the number that applies to your account before you assume either one gives you more room.

When several people share sessions, anyone on the team can check availability at cloud.katalon.com. The Home page shows how many sessions are free and how many are in use. A quick look before you click Run means two people won’t compete for the same session without knowing, and it explains why a run is waiting in the queue.

Trade-offs

What works well

  • There’s nothing to set up or patch. Katalon manages the machines that run your tests.
  • You can grow by adding session licenses, with no hardware to plan for.
  • It’s the fastest way to get a pilot running: one tunnel and no servers.

What to know before you start

  • The number of sessions you’ve bought limits how many tests run in parallel.
  • The tunnel machine has to stay on and connected while tests run.
  • If you regularly need more than your session count, that means extra license cost.

This is usually the easier place to start when:

  • You want to test the full flow (start a run, execute, get a report) with the least setup.
  • The number of runs you need at the same time, now or soon, fits within the Test Cloud sessions you already have.
  • You’d rather not plan, patch, or look after your own test machine.

This describes a general setup pattern. Exact steps, screens, and license terms can vary by account and Katalon version.


Setting this up? Reply below with where you are (tunnel, firewall rules, repository, or running tests) and what you’re seeing. Please leave out internal hostnames, IP addresses, and tunnel config commands.

Tunnel is awesome but it struggles in the private url in the vpn protected environment