Skip to main content

Migrating from legacy Link to Link 3.0

Molly Exten
  • Updated

Link 3.0 replaces the legacy mabl Link protocol with a faster, more reliable tunnel, and the legacy Link service shuts down on March 15, 2027. This article is for teams that run Link Agents today. It walks through upgrading your agents, opening your firewall to the new endpoints, and moving your cloud test traffic to Link 3.0, so that your tests keep reaching your private environments after the legacy service is gone. For what Link 3.0 adds, see the mabl Link 3.0 release note.

What happens on March 15, 2027

On March 15, 2027, mabl shuts down the legacy Link service. After that date:

  • Link Agents older than version 3.0 stop working.
  • A Link Agent on version 3.0 or later keeps working only if your account has already moved to the Link 3.0 protocol. If it hasn't, mabl can no longer route cloud test traffic to it.

Complete the steps in this article before that date. The move happens one account at a time, and you control when each step starts.

What carries over

Moving to Link 3.0 does not change how you configure your tests:

  • Tunnel names stay the same. Environments, database connections, and deployment events that name a tunnel keep working without edits.
  • API keys stay the same. Your existing "Link Agent" API keys work with Link 3.0.
  • Configuration files keep working, including proxy settings, PAC settings, and connection filters.
  • High availability works the same way: multiple agents with the same tunnel name share the traffic.

A few things do change:

  • Firewall rules. Link 3.0 connects to fixed endpoints instead of a host name generated for each agent. See Open your firewall to Link 3.0.
  • Supported platforms. Link 3.0 runs on Linux (x86-64 and arm64), macOS on Apple silicon, and Windows on x86-64. See the callout below if an agent runs anywhere else.
  • Memory. Until your account finishes migrating, each agent carries both the legacy tunnel and the Link 3.0 tunnel. See Sizing and scaling Link Agents.
  • System proxy settings. A Link Agent without proxy settings of its own now follows the proxy configuration of its host operating system, including a PAC script. If the host has a proxy configured that the agent should not use, set proxyMode to none in the configuration file.
  • Retired options. The --connections and --max-connection-attempts (-r) options, and the connections and maxConnectionAttempts configuration settings, only apply to the legacy protocol. Link 3.0 ignores them, and a future release will remove them.

The migration has three phases. First you prepare your agents and network. Then mabl turns on Link 3.0 for your account while your cloud runs keep using legacy Link, so that you can confirm every agent connects. Finally, mabl moves your cloud runs to Link 3.0 and retires the legacy protocol.

Agents on Intel Macs, Windows on ARM, or Alpine Linux on arm64

Legacy Link Agents run anywhere Java runs, but Link 3.0 does not support Macs with Intel processors, Windows on ARM, or Alpine Linux on arm64. An agent on one of these hosts keeps working over the legacy protocol only, and stops working when legacy Link shuts down. Plan to move it to a supported host, or for arm64 containers to the Ubuntu variant of the Docker image, as part of your migration.

Go to Settings > Networking and review the Link Agents table:

  1. Note the Version of each agent. Every agent must run version 3.0 or later.
  2. Confirm that each agent's host is on a supported platform and has enough memory for the tunnels it serves while it carries both protocols. See Sizing and scaling Link Agents.
  3. If your company has Link Agents in more than one workspace, repeat the check in each workspace.

Allow outgoing connections from every Link Agent host to api.mabl.com on TCP port 443 and to one of the two Link 3.0 tunnel endpoints:

  • mabl-wss.link.mabl.com on TCP port 443, the WSS endpoint, for networks that send outgoing traffic through an HTTP proxy or block UDP. Most networks use this endpoint.
  • mabl-quic.link.mabl.com on UDP port 443, the QUIC endpoint, for hosts that reach mabl without a proxy. QUIC is faster, and the Link Agent uses it when it can.

The tunnel needs only one of the two. For the full list, including the optional update path, see Link Agent requirements.

If your allowlist already includes *.link.mabl.com, it covers both endpoints. Keep *.link.mabl.com in place until the migration is complete, because your agents use it for the legacy tunnel in the meantime.

Upgrade every Link Agent to version 3.0 or later. How you upgrade depends on how the agent was installed:

  • Agents installed from the zip or tar.bz2 archive, with automatic updates on, install the latest version when they start. Restart each agent, then confirm on Settings > Networking that it reports version 3.0 or later.
  • Agents with automatic updates turned off (disableAutoUpdates: true) need a manual upgrade. Download the latest version from Settings > Networking and install it in place of the old one, keeping your configuration file.
  • Docker and Kubernetes agents need the version 3 image. Pull mablhq/link-agent:3, or pin a variant with mablhq/link-agent:3-alpine or mablhq/link-agent:3-ubuntu, and restart the container. On arm64 hosts, such as Apple silicon Macs and ARM cloud instances, you must use mablhq/link-agent:3-ubuntu, because the default Alpine image is published for x86-64 only. See Link with Docker.
  • Windows agents can move to the Windows installer, which runs the agent as a Windows service and includes its own Java runtime. See Link on Windows, which also covers replacing a service you set up with NSSM.

After the upgrade, each agent still connects over the legacy protocol only. It starts using Link 3.0 once mabl turns it on for your account in the next step.

When every agent runs version 3.0 or later and your firewall allows the new endpoints, contact mabl and ask to turn on Link 3.0 for your account. Reach out through whoever you usually work with at mabl, such as your customer success manager, TAM, or mabl support.

Once Link 3.0 is on, each Link Agent connects over both protocols, with no restart needed. Your cloud test runs keep using the legacy tunnel during this phase, so turning on Link 3.0 does not change how your tests run.

Go to Settings > Networking and check the Endpoint column of the Link Agents table. Each agent lists the endpoints it uses:

  • QUIC or WSS means the agent is connected over Link 3.0.
  • Legacy means the agent is connected over the legacy protocol, which it keeps doing until the migration is complete.

Every agent should show QUIC or WSS in use alongside Legacy. If an agent shows a warning that it cannot reach mabl over UDP or TCP, its host can't reach the Link 3.0 endpoints. Review your firewall rules and any proxy settings for that host, then check again. For more help, see Troubleshooting issues with mabl Link.

When every agent is connected over Link 3.0, let mabl know. mabl then moves your account's cloud test runs to Link 3.0. Your environments and tunnel names don't change.

After the switch, run the plans that depend on mabl Link and confirm that they pass as before. Until the legacy protocol is retired in the next step, mabl can move your cloud runs back to legacy Link if you run into a problem, so report anything unexpected to mabl.

Retire the legacy protocol

Once your tests have run reliably over Link 3.0, mabl turns off the legacy protocol for your account. Your Link Agents close their legacy connections, and the Endpoint column no longer lists Legacy.

After migrating

With the migration complete:

  • You can remove {host}.link.mabl.com entries from your allowlist. If your allowlist uses *.link.mabl.com, you can replace it with the endpoint your agents use, unless mabl has placed your company on dedicated Link infrastructure.
  • Each Link Agent needs less memory, because it no longer carries the legacy tunnel. See Sizing and scaling Link Agents.
  • Link Agents connect faster when they start and after a network interruption.

Link 3.0 also brings capabilities that legacy Link does not support:

Once your agents are on Link 3.0, you can also replace workspace tunnels that reach the same network with one tunnel that every workspace in your company shares. See Moving workspace tunnels to a company tunnel.