With mabl Link, you can run tests in the mabl cloud against internal environments such as staging and localhost. This article explains how to install and run the mabl Link Agent, which is a small Java-based application responsible for creating the secure tunnel to the mabl cloud.
Identify where to install the mabl Link agent. We recommend installing it on a persistent Linux server or VM in your network. For more details, see the article on Link Agent requirements
Step 1: Retrieve the API key for your workspace
To start up the Link Agent, you need a mabl API key. If a "Link Agent" API key does not already exist for your workspace, take the following steps to create one:
- Go to the APIs page: Settings > APIs.
- Click on + Create API key.
- For Type of API key, select "Link Agent".
- Give the API key a name.
Only workspace owners can create API keys.
Step 2: Install the Link Agent
Install the Link Agent on a machine that has access to the application environment (host) that you want to run tests against.
We recommend installing the Link Agent with Docker for greater portability and ease of use. To continue the Link Agent setup process using Docker, skip over to the Link with Docker article for complete instructions.
Alternatively, install the Link Agent using a Java-based distribution package:
- Download your preferred distribution - zip or tar.bz2 - from the networking page in the mabl app: Settings > Networking.
- Copy the file archive to the machine where you want to run the Link Agent.
- Extract the file archive to a convenient location.
# Extract bzip2 tar:
tar xjf link-agent.tbz2
# Or extract zip:
unzip link-agent.zip
Additional options for installing and running the Link Agent include:
- Link with systemd: install and run the Link Agent as a systemd service.
- Link on Kubernetes: for those who intend to run mabl Link on a Kubernetes cluster.
- Link on Windows: install and run the Link Agent on a Windows machine.
Step 3: Run the Link Agent
In a terminal, enter the Link Agent directory that was extracted from the archive, and execute the Link Agent. Running the Link Agent requires two parameters:
- API key: use the value of the "Link Agent" API key you created in step 1
- Name: create a name between 1 and 24 characters long that consists of lowercase letters, numbers, and dashes. Expressed as a regular expression, the name must conform to ^[a-z0-9-]{1,24}$ .
You can pass these values as command-line arguments or by using a JSON or YAML configuration file. For more information on Link Agent configuration files, check out this article.
The following code block shows examples of Link Agent startup commands:
# Run the Link Agent as a foreground process
bin/link-agent --api-key fake-api-key --name qa-env-01
# Run the Link Agent by using a JSON configuration file
bin/link-agent --config /path/to/config.json
# Run 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 &
The Link Agent will connect to a generated DNS name of the form <host>.link.mabl.com
. The <host>
component is generated based on the --name
argument passed at startup and will never change as long as the Link Agent starts up with the same name.
Support for HTTP forward proxies
If your network requires it, you can configure the Link Agent to use an HTTP forward proxy, including support for basic proxy auth. Link Agents also support Proxy Auto-Configuration (PAC).
Step 4: Validate the Link connection is live
After starting the Link Agent, return to the networking page in the mabl app: Settings > Networking. The Link Agent appears in the Link Agents section with an "Initializing" status when starting up. Within a couple minutes of starting up, the Link Agent should show a "Connected" status.
A Link Agent with a connected status
If you experience issues setting up the Link Agent, see our troubleshooting guide.
Next steps
When the Link Agent is installed and running, configure your tests to run over mabl Link.