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.
Settings ⇒ Networking in the mabl UI, and download the Link Agent distribution in the format of your choice:
Settings => APIs in the mabl UI, and copy your API key:
Minimum recommended hardware
The Link Agent will run in many different hardware configurations. Though there are no strict minimum requirements, we recommend at least:
- 1 vCPU
- 1GB RAM
- 2GB storage
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: unzip link-agent.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:
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
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
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.
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.
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, and
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:
See how easy it is to run the Link Agent inside a Docker Container here: