Link Agent setup

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.

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:

1. Go to the APIs page: Settings > APIs.
2. Click on + Create API key.
3. For Type of API key, select "Link Agent". 
4. Give the API key a name.

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:

1. Download your preferred distribution - zip or tar.bz2 - from the networking page in the mabl app: Settings > Networking. 
2. Copy the file archive to the machine where you want to run the Link Agent. 
3. Extract the file archive to a convenient location.

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

# Or extract zip:
unzip link-agent.zip

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

Next steps

When the Link Agent is installed and running, configure your tests to run over mabl Link.