Link on Windows

The Windows installer, link-agent.msi, installs the mabl Link Agent as a Windows service that starts on its own after every reboot with nobody signed in. It includes its own Java runtime, and it asks for your tunnels and proxy while it installs. This article explains how to install the Link Agent on Windows, change its configuration later, install it without dialogs, and move to it from an earlier installation.

Step 1: Download the installer

Download the Windows installer from the networking page in the mabl app: Settings > Networking.

Step 2: Run the installer

Run link-agent.msi and follow the dialogs:

1. Application folder. Choose where to install the program files. The default is C:\Program Files\mabl\Link Agent.
2. Configuration and data folder. Choose where the agent keeps its configuration, logs, and updates. The default is C:\ProgramData\mabl\link-agent. Choose a location with room to spare, and a path without spaces.
3. Tunnels. Enter a tunnel name and API key for each tunnel the agent should serve. Click Add another tunnel for more rows. Tunnel names are up to 24 lowercase letters, digits, and hyphens.
4. Proxy. Choose how the agent should reach the internet:
   • Automatic: follow the proxy settings Windows itself uses, including a PAC script if one is configured.
   • Manual: enter the proxy address and port, which traffic goes through it, optional credentials, and destinations to reach directly.
   • PAC: enter the URL of your proxy auto-configuration script.
   • None: always connect directly. Choose this when the machine has a proxy configured that the agent should not use.
   • Do not change the proxy configuration: keep whatever the configuration file already says.
5. Starting the agent. Leave Start the mabl Link Agent service now selected to start the agent when the installer finishes. The dialog also shows where the configuration file and log files are.

If you don't have a tunnel name and API key yet, choose Skip guided configuration. The agent can't start without a tunnel, so add one to the configuration file later, or run the installer again to be asked for it.

For more about proxy choices, see Forward proxies for mabl Link traffic.

Step 3: Validate the Link connection is live

After the service starts, go to the networking page in the mabl app: Settings > Networking. Within a minute or two of starting, the Link Agent appears in the Agents table with a Connected status.

If the agent doesn't appear, see Troubleshooting issues with mabl Link.

Where the agent keeps its files

With the default folders, the agent uses these locations:

File Explorer hides C:\ProgramData by default. Paste the path into the address bar to open it.

Change the configuration

The Link Agent watches its configuration file and applies changes while it runs, so you don't need to restart the service after you edit it. You can add or remove tunnels, change proxy settings, and add connection filters this way.

To be asked for tunnels and proxy settings again, run the installer again. On a machine where the agent is already installed, it offers these choices:

• Install this version: replace the installed version with the one in this installer.
• Change configuration: choose Tunnels and API keys, Proxy configuration, or both, and answer the same questions as the first install. Everything else in the configuration file is kept, but comments are not.
• Open configuration folder and Open log folder
• Uninstall: remove the service. Your configuration and logs are left in place.

Updates

The installed agent keeps itself up to date. It installs each update beside the running version and restarts into it, and keeps the previous version so that you can roll back. See Maintaining and updating Link Agents.

Install without dialogs

Every answer the installer asks for can also be given on the command line, for scripted installs or device management tools such as Microsoft Intune. Run msiexec from an elevated command prompt:

msiexec /i link-agent.msi /qn TUNNELNAME1={tunnel-name} APIKEY1={api-key} PROXYCHOICE=auto STARTSERVICE=1

A silent install doesn't start the service unless you pass STARTSERVICE=1.

Migrating from an earlier installation

Before the Windows installer was available, the Link Agent ran from the zip archive, either from a command prompt or as a service set up with a tool such as NSSM. You can replace any of these installations with the installer and keep using your existing configuration.

Step 1: Stop the old agent

Stop the old agent so that it doesn't run alongside the new one:

• From a command prompt: press Ctrl-C, or close the command prompt.
• As an NSSM service: stop and remove the service, as described in Remove an NSSM service.
• Some other way, such as a scheduled task: stop the agent, and turn off whatever starts it so that it doesn't start again after a reboot.

Step 2: Install and bring your configuration across

Run link-agent.msi, and bring your tunnels across in one of two ways. To see how the old agent was started, look at the command you ran, or at the wrapper script your service runs, such as C:\mabl\link-agent-wrapper.bat.

• Reuse your configuration file. If the old agent was started with a configuration file, this keeps every setting in it, not only its tunnels.

  1. When the installer asks for tunnels, choose Skip guided configuration, and finish the install.
  2. Copy your existing configuration file over C:\ProgramData\mabl\link-agent\config\config.yaml, or config\config.yaml in the data folder you chose.
  3. Start the service from Services, or with sc start MablLinkAgent in an elevated command prompt. Without guided configuration, the installer doesn't start it for you.

  If your configuration file is in JSON format, run the installer from an elevated command prompt with msiexec /i link-agent.msi CONFIGFILE=config.json, and copy the file to config\config.json instead.

• Enter the tunnels again. If the old agent was started with its API key and tunnel name on the command line (-a and -n, or --api-key and --name) rather than with a configuration file, or it serves only a few tunnels, enter the same tunnel names and API keys in the installer, and choose the same proxy settings. The installer starts the service when it finishes.

Step 3: Confirm and clean up

Confirm on Settings > Networking that the agent is connected. Then delete the old Link Agent folder, and any wrapper script you used to start it.

Remove an NSSM service

From an elevated command prompt, stop and remove the old service. Use the service name you gave it in NSSM, which is LinkAgent in the earlier setup instructions:

nssm stop LinkAgent
nssm remove LinkAgent confirm

Run from the zip archive

You can also run the Link Agent from the zip archive without installing a service, for example to try it out. The archive requires Java 11 or later on the machine. Download the zip archive from Settings > Networking, extract it, and run the agent from a command prompt:

powershell.exe -NoP -NonI -Command "Expand-Archive link-agent.zip"
bin\link-agent --api-key {your-api-key} --name {tunnel-name}

The agent runs until you close the command prompt or press Ctrl-C. For an agent that keeps running after you sign out, use the Windows installer.

Next steps

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