0% Complete


Before taking this lesson

Make sure you are comfortable with the following lessons:

Learning Objectives 🧠

By the end of this you will:

  • Learn what mabl Link is and when it should be used
  • Understand the high level steps to set up mabl Link
  • Obtain necessary documentation links to complete the mabl link setup

Why is it important?

  • Mabl link is a secure way to access your private environments. Customers use mabl Link to establish a secure tunnel between their private network and the mabl cloud so that they can run tests in the mabl cloud against internal environments.
  • Mabl link highlights:
    • Highly secure tunneling solution
    • Quick and easy setup with automatic updates for the agent
    • Support for https traffic and http forward proxies
    • Elegant architecture that doesn’t require firewall changes in many cases
    • No need to allowlist a broad range of IPs, just a single domain name
    • High availability by design - just setup multiple agents with the same name
    • No need for VPN client or server

What is it?

  • mabl Link consists of two main components — Link Agent and Link Service — that are responsible for establishing a secure outgoing (egress) connection from your network to the mabl cloud. The Link Agent is a small Java-based application that is responsible for creating the secure tunnel to the mabl cloud. It can be installed using Docker or a Java-based distribution package. The below diagram illustrates how it works:

How do I set it up?

Below are the high level steps to setting up a Link Agent. Refer to the documentation links at the end of this guide for further details.

Step 1: Retrieve the API key for your workspace

In order to use the mabl Link agent you will need a mabl API key. To obtain a copy of your API key, navigate to Settings --> APIs in the mabl app. Click to Create New Key, choose Link Agent, input a name and click Create.

Step 2: Download and install the Link Agent

Navigate to Settings → Networking and download your preferred distribution package. We recommend using Docker if you can as it is the simplest and easiest to maintain.

Step 3: Run the Link Agent

If using Docker or setting up the agent on Windows, please refer to the respective Docker or Windows instructions.

If using a Java-based archive for the Link Agent, please copy it to a machine that has access to the application environment (host) that you would like to run tests against, and then extract the file archive to a convenient location.

In a terminal, enter the link agent directory that was extracted from the archive, and then execute the Link Agent. The Link Agent requires two parameters to be passed on the command-line:

  • --api-key <your-api-key>
  • --name <valid-agent-name>

The API key is the key that you copied in Step 1 above. The name is an identifier of your choice that you will use later to identify this agent. The name must consist only of lowercase letters, numbers, and hyphens, and it cannot be longer than 24 characters in length. Expressed as a regular expression, the name must conform to ^[a-z0-9-]{1,24}$ .

The agent will connect to a generated DNS name of the form <host>.link.mabl.com where the <host> component is generated based on the --name argument passed at startup and will never change as long as the agent is started using the same name. IT security teams can allowlist/permitlist that individual FQDN or the wildcard *.link.mabl.com.

An example of a valid Link Agent start-up command is:

Step 4: Validate the Link connection is live

After starting the Link Agent (see Step 3 above), return to the mabl UI and navigate to Settings ⇒ Networking. Under the mabl Link Agents heading you should see an entry with the agent you just started. Initially you should see a message indicating that the tunnel is initializing. Within the next couple of minutes the Link Agent should become Connected and show state Ready within a couple of minutes of starting it up.

Step 5: Configure a mabl environment to use the Link Agent

Navigate to Configuration --> Environments in the mabl UI, and either create a new environment or edit an existing environment. You can disable/enable the agent by toggling the Use link agent checkbox. Note that the agent must be started before it can appear in this configuration drop-down menu

Step 6: Associate the link-enabled environment with a plan

In order to route traffic through the Link Agent, the environment you created in Step 5 must be associated with a plan. Either create a new plan or edit an existing plan in the mabl UI, and select the environment you created in Step 5.

Step 7: Run the test plan over Link

Now run the plan you created in the prior step. When you view the test run results for that plan you should see messages indicating that mabl searches for and finds an active Link Agent, similar to the message below:

When the Link Agent is not started or has not finished connecting before the test run started, you may see an error like the one below:

Whitelisting IPs

Traffic from mabl originates through a fixed set of IP addresses. Instead of using mabl Link, network administrators can set up firewall rules (allowlist, permitlist) to allow access to non-public testing and production environments.

To identify the IP addresses, navigate to Settings → Networking.



We have invested significant engineering effort into making it simple and secure to benefit from running tests in the cloud against app environments on private networks through the setup and use of a mabl Link Agent.

Helpful Documentation Links:

If your team has any questions or needs assistance with setting up mabl Link, please reach out via In-App Chat!


Was this helpful?

Take this 2 minute survey to let us know how we can make mablU better!