Using mabl Link

Learn how to integrate mabl Link into your tests to allow mabl to access private environments

The mabl Link feature allows plan and journey execution against test environments on private networks. This feature is useful for accessing: private test environments, development environments running on localhost, and ephemeral cloud environments accessed via VPC or AWS Direct Connect. Watch this short video to get started or follow along with the steps below.


1. Download the Link Agent

Navigate to Settings ⇒ Networking in the mabl UI, and download the Link Agent distribution in the format of your choice:

2. Retrieve the API key for your workspace

Navigate to Settings => APIs in the mabl UI, and copy your API key:


The Link Agent is a Java application. It requires a JVM that supports Java 9 or later. The Link Agent has been tested with both the OpenJDK and Hotspot JVMs. The Link Agent does not have any dependencies other than the JVM.

  • We recommend the Java 11 JDK for Linux, Windows, and MacOS

3. Execute the Link Agent

Copy the Link Agent archive to a machine that has access to the host you would like to run tests against, and then extract the archive to a convenient location.

Running the Link Agent on Windows

Please see the following documentation on setting up and configuring the Link Agent to run in Windows environments: Running the Link Agent on Windows

# Extract bzip2 tar:
tar xjf link-agent.tbz2

# Or extract zip:

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 2 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}$ .

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

cd link-agent

# Start the Link Agent as a foreground process
bin/link-agent --api-key fake-api-key --name qa-env-01

# Or you may wish to start the Link Agent in the background
# and keep it running even after you log out:
nohup bin/link-agent --api-key fake-api-key --name qa-env-01 &
cd link-agent

# NOTE: requires using the Java JDK (not JRE)

# Start the Link Agent as a foreground process
bin/link-agent --api-key fake-api-key --name qa-env-01

# Or you may wish to start the Link Agent in the background
# and keep it running even after you log out:
nohup bin/link-agent --api-key fake-api-key --name qa-env-01 &
cd link-agent

# Start the Link Agent as a foreground process
bin\link-agent.bat --api-key fake-api-key --name qa-env-01

4. Confirm that the Link Agent is able to connect to mabl

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, similar to this:

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.

Troubleshooting Agent Connectivity Issues

If you do not see any agents listed, verify that the agent process is still running on the host where you started it, and check the log file (logs/agent.log) for errors. If you are having trouble getting the agent to start, contact mabl support.

If you do see an agent listed, but it is not connected, first confirm that the name matches you name you chose when you started the agent. If the agent is not connected, wait a few minutes and see if the connection becomes established. It can sometimes take a few minutes to fully connect, especially the first time you start a new Link agent. If the agent does not connect after 10 minutes, contact mabl support.

5. Configure a mabl environment to use your Link Agent

Navigate to Configuration ⇒ Environments in the mabl UI, and either create a new environment or edit an existing environment.

Associating a Link Agent with an existing environment

When you associate a Link Agent with an environment, all plans associated with that environment will have their traffic routed through the selected Link Agent. It is usually a better idea to create a new dedicated environment for a Link Agent so that existing plans are not affected. One exception to this general rule is when all of your environments are private, and none of your plans can run successfully until a Link Agent has been configured.

Not seeing your Link Agent in the drop-down?

The Link Agent must be started up before it can be selected in the drop-down list.

The Link Agent can be enabled or disabled by toggling the Use link agent checkbox.

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.

URL is resolved by the Link Agent

The URL you enter will be resolved by the Link Agent (not within mabl's network) so you can use any URL that the host on which the Link Agent is running can resolve. This URL can include non-public FQDNs, private IP addresses, /etc/hosts entries, and even localhost!

7. Run the plan

Now run the plan you created in the prior step. When you view the journey output you should see messages indicating that mabl is searching for a Link Agent and that it found one, similar to the message below:

If you have not started a Link Agent, or the Link Agent has not finished connecting before the test started, you may see an error like the one below:

Using Docker?

See how easy it is to run the Link Agent inside a Docker Container here: