Link on Windows

When running the Link Agent on a Windows machine, we recommend the following steps to ensure the most reliable Link Agent configuration.

Step 1: Install Java

The Link Agent runs on Java and requires Java 11 or newer to be installed on the machine. Download and install the Java 11 JDK for Windows. The .msi installer is usually the easiest option.

Configure Java

It may be necessary to set the JAVA_HOME environment variable if the installer did not do this. To confirm whether JAVA_HOME was correctly set as a system environment variable, take the following steps:

1. Click on the Windows Start button
2. In Search, search for and then select "Edit the system environment variables"
3. In System Properties, click on Environment Variables.

If the JAVA_HOME variable appears in the System variables section, skip ahead to the Verify Java configuration section. If JAVA_HOME is absent, follow next steps to add it to system environment variables:

1. In the System variables section, click on the New… button.
2. Enter JAVA_HOME as the variable name.
3. Click on the Browser Directory… button.
4. Navigate to the location where Java was installed. This path is usually under "C:\Program Files\Java".
5. Choose the directory starting with "jdk-". For example: "jdk-11.0.2"
6. Click on the OK button.

After adding the JAVA_HOME as a system environment variable, add Java to the system Path variable:

1. Click on the Path variable in System variables.
2. Click on the Edit… button.
3. Click on the New button.
4. Enter %JAVA_HOME%\bin.
5. Click OK to confirm changes to the `Path` variable.
6. Click OK on the Environment Variables and System Properties windows.

Verify Java configuration

To verify that Java is installed correctly, run the following command in a command prompt:

java -version

You should see output similar to the following message:

Note that the specific version of Java may differ depending on what the latest version was when you installed it.

Step 2: 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 in the mabl app:

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 3: Download the Link Agent

Download the Link Agent zip file from the networking page in the mabl app: Settings > Networking.

Step 4: Run the Link Agent

In a command prompt, navigate to the directory where you downloaded the Link Agent - link-agent.zip - and extract the archive using the following command:

To start up the Link Agent, provide the "Link Agent" API key and a Link Agent name as arguments:

Run the Link Agent as a Windows service

After confirming that the Link Agent is working, we recommend creating a Windows service for the Link Agent so that the Link Agent will continue running in the background even if you lock the screen or log out.

To run the Link Agent as a Windows service, take the following steps:

1. Save the full Link Agent command, including API key, Link Agent name, and any other parameters to a separate .bat script in a well-known location, such as C:\mabl\link-agent-wrapper.bat. The script should contain the absolute path to the Link Agent, as shown in the following example: C:\mabl\link-agent\link-agent\bin\link-agent -a <your-api-key-here> -n <your-link-agent-name-here>.
2. Open the command prompt as an administrator.
3. Run the following commands in the command prompt:

Create a service for the Link Agent using NSSM, substituting in the path where you have created your wrapper script, and then start the new service: