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, the application that creates the secure tunnel between your network and the mabl cloud.
Before you start
Choose where to install the Link Agent. We recommend an always-on server or VM in your network that can reach the applications you want to test. Check it against the Link Agent requirements, and see Sizing and scaling Link Agents for how much CPU and memory to give it.
If you only want to route your own cloud runs through your computer, you don't need to install anything or create a key. Start a personal Link tunnel from the mabl Desktop App or the mabl CLI instead.
Step 1: Get a Link Agent API key
The Link Agent needs a "Link Agent" API key. The key decides who owns the tunnel:
- A workspace key creates a tunnel that only that workspace can use. To create one, go to Settings > APIs, click + Create API key, choose the Link Agent type, and give the key a name. Only workspace owners can create API keys.
- A company key creates a tunnel that every workspace in your company can use. Account admins create company keys in the company dashboard. See Company-scoped Link tunnels.
Step 2: Install the Link Agent
Install the Link Agent on a machine that can reach the applications you want to test. Choose the installation that fits the host:
| Host | Installation |
|---|---|
| Windows | The Windows installer installs the Link Agent as a Windows service, with its own Java runtime, and asks for your tunnels and proxy as it installs. |
| Linux or macOS | The Linux and macOS installer installs the Link Agent as a service that starts at boot and asks for your tunnels and proxy as it installs. |
| A container platform | The Docker image includes everything the Link Agent needs. For Kubernetes, see Running mabl Link on Kubernetes. |
| A computer with the mabl CLI | Run the Link Agent from the mabl CLI, without Java. Best for trying mabl Link or for short-lived tunnels. |
The installers keep a Link Agent running with no further work on your part, because they register it with the operating system's service manager so that it starts at boot and restarts if it stops.
Install from the archive
To run the Link Agent without a service, download the zip or tar.bz2 archive from Settings > Networking, copy it to the host, and extract it:
# Extract the tar.bz2 archive:
tar xjf link-agent.tbz2
# Or extract the zip archive:
unzip link-agent.zip
Running the Link Agent from the archive requires Java 11 or later. The archive also contains the Linux and macOS installer, install.sh, if you decide to install it as a service later.
Step 3: Run the Link Agent
The installers ask for your tunnels while they install, and start the Link Agent for you. To run it from the archive, open a terminal in the extracted directory and start it with your API key and a tunnel name:
- API key: the "Link Agent" API key from step 1.
-
Name: the tunnel name, between 1 and 24 characters long, using lowercase letters, numbers, and dashes. As a regular expression, the name must match
^[a-z0-9-]{1,24}$.
# Run the Link Agent in the foreground
bin/link-agent --api-key {your-api-key} --name qa-env-01
# Run the Link Agent with a configuration file
bin/link-agent --config /path/to/config.yaml
Use a configuration file
A Link Agent configuration file keeps your API key off the command line and lets one agent serve several tunnels. The Link Agent watches the file while it runs, so you can add or remove tunnels and change proxy settings without restarting it. To turn off watching, start the agent with --no-config-reload.
A tunnel keeps its identity for as long as you start agents with the same name, and multiple agents with the same name share the tunnel's traffic. See High availability configuration.
Support for HTTP forward proxies
If your network requires it, configure the Link Agent to use an HTTP forward proxy, including proxies that need basic authentication and proxy auto-configuration (PAC). When the Link Agent has no proxy settings of its own, it follows the proxy configuration of its host operating system.
Step 4: Confirm the Link Agent is connected
After starting the Link Agent, go to the networking page in the mabl app: Settings > Networking. For a company tunnel, open the Networking page of the company dashboard instead.
The Link Agent appears in the Link Agents table. While it starts, its Status moves through steps such as Initializing agent, Announcing, and Securing tunnel. Within a minute or two, it should show Connected.
The Endpoint column shows how the agent reaches mabl: QUIC or WSS for Link 3.0, and Legacy while your account still uses the legacy Link protocol. If the column shows a warning that the agent can't reach mabl, check the outgoing traffic requirements.
If the Link Agent doesn't connect, see Troubleshooting issues with mabl Link.
Next steps
- Configure your tests to run over mabl Link.
- Record who maintains the agent, and learn how to update and drain it, in Maintaining and updating Link Agents.