Private Network (Leapwork Connect)

Leapwork Connect lets browser sessions in Play reach applications that only exist inside your own network. You install a small connector on a machine inside that network. It dials out to Leapwork, so no inbound ports and no firewall changes are needed.

A workspace can have more than one connector, for example one per office or network. See Use more than one connector for adding others. The steps below describe installing a connector, and apply to each one you add.

A connector reaches nothing until you tell it what it may reach. That list is set on the connector machine, never from Play.

Prerequisites

  • Your plan includes Private Network. If it does not, the Get Leapwork Connect button is not shown.

  • You are the Subscription Owner or Administrator. Only they can generate an install command.

  • A machine inside the private network that can stay on, with outbound HTTPS to Leapwork.

  • Administrator (Windows) or root (Linux/macOS) access on that machine.

1. Generate the install command

Connectors belong to the workspace, not to a team. Every team in the workspace sees and shares the same connectors, and the install command is not tied to the team you generate it from. The dialog is simply reached from Team Settings, next to the environments that use it.

  1. In Play, open any team in the workspace.

  2. Open Team Settings.

  3. Go to the Environments section.

  4. Select Get Leapwork Connect.

  5. In the dialog, select Download connector. If the workspace already has a connector, the dialog first shows a Connector dropdown with an Add connector button next to it: select the button, give the connector a name, and continue.

This generates a single-use enrollment token embedded in the install command. Keep it private: anyone who runs it can connect that connector to your workspace. The token expires, and generating a new command for a connector invalidates the previous command for that same connector.

2. Choose the operating system

The dialog shows three tabs: Windows, Linux, and macOS. Select the tab matching the connector machine and use Copy to copy the command.

The command downloads the connector, unpacks it, and runs its install verb. install enrolls the machine, stores its credentials encrypted, and registers the connector as a background service that starts on boot:

OS

Runs as

Windows

Windows service Leapwork Connect (LocalSystem)

Linux

systemd unit leapwork-connect.service

macOS

launchd daemon com.leapwork.connect

3. Run the command elevated

Run the copied command on the connector machine, elevated. A non-elevated shell fails.

  • Windows: open PowerShell as Administrator and paste the command.

  • Linux / macOS: open a terminal and paste the command. It uses sudo -E, so you are prompted for your password. If you are already root, sudo is harmless and the command works unchanged.

Do not strip the -E from sudo. It preserves the enrollment token through sudo's environment reset, which is how the token reaches the connector without appearing in the process list.

When the install finishes, the dialog in Play changes to Connector connected. With several connectors, each one shows its own state in the Connector dropdown.

4. Set the allowed targets during install

Near the end, the install asks which targets Leapwork may reach through this connector:

── Allowed targets ─────────────────────────────────────────────
Which targets inside this network may Leapwork reach through this connector?
Comma-separated. Each entry is either:
    443                  a port — any host in this network on that port
    app.internal:8080    a specific host on a specific port
    192.0.0.1:443        a specific address on a specific port
Allowed targets:

Enter a comma-separated list, for example:

443, app.internal:8080

An entry is either:

  • a port - any host in the network on that port, or

  • a host:port or address:port - only that host on that port.

You can also paste a URL. https://app.internal/login is stored as app.internal:443: the scheme supplies the default port, an explicit port wins, and the path is dropped.

Before saving, the install shows the entries it will allow and asks you to confirm.

The allowlist is empty (disabled) by default. If you press Enter without typing anything, or the install is non-interactive (MDM, CI, scripted), nothing is allowed and the connector blocks all traffic until you add entries with the allowlist add command below. The install says so explicitly.

5. Manage the allowlist from the terminal

The allowlist can only be changed on the connector machine, using the allowlist verb. There is no config file, environment variable, or field in Play that can widen it. Each connector has its own allowlist, so run these commands on the machine of the connector you mean to change.

Every subcommand needs elevation, including show - the list lives in a directory restricted to SYSTEM and Administrators (Windows) or root (Linux/macOS).

Open a terminal in the connector's folder

The installer puts the connector in a fixed location. Change to it first, so the commands stay short:

Windows - in an Administrator PowerShell:

PowerShell
cd C:\ProgramData\LeapworkConnect

Linux:

Bash
cd /var/lib/leapwork-connect/bin

macOS:

Bash
cd "/Library/Application Support/LeapworkConnect/bin"

C:\ProgramData is hidden in File Explorer by default, but the path works in PowerShell as typed.

The commands

From that folder, the connector is .\Leapwork.Connect.Connector.exe on Windows and ./Leapwork.Connect.Connector on Linux and macOS:

Verb

What it does

show

Prints the targets this connector may reach. Prints Disabled when the list is empty. Read-only.

add

Allows the given targets, in addition to anything already allowed. Shows the normalized entries and asks you to confirm; add -y (or --yes) to skip the prompt.

remove

Stops allowing the given targets.

clear

Removes every rule. The connector blocks all traffic again. Takes no targets.

Windows (the shell is already elevated, so no sudo):

PowerShell
.\Leapwork.Connect.Connector.exe allowlist show
.\Leapwork.Connect.Connector.exe allowlist add "443, app.internal:8080"
.\Leapwork.Connect.Connector.exe allowlist remove "443"
.\Leapwork.Connect.Connector.exe allowlist clear

Linux and macOS (drop the sudo if you are already root):

Bash
sudo ./Leapwork.Connect.Connector allowlist show
sudo ./Leapwork.Connect.Connector allowlist add "443, app.internal:8080"
sudo ./Leapwork.Connect.Connector allowlist remove "443"
sudo ./Leapwork.Connect.Connector allowlist clear

Notes:

  • Entries can be passed as one quoted, comma-separated string or as separate arguments, and can be full http:// or https:// URLs.

  • add asks for confirmation because it widens what the connector can reach. The prompt is skipped with -y, and when no one is at a terminal (scripted runs).

  • A port must be 1-65535, and a host:port needs both parts. If any entry is invalid, nothing is changed.

  • A change restarts the connector service so it takes effect immediately. Browser sessions running through the connector at that moment are dropped.

6. Stop or uninstall the connector

Windows

To stop it temporarily (the connector stays installed and starts again on reboot):

  1. Press Win and search for Services.

  2. Find Leapwork Connect in the list.

  3. Right-click it and select Stop.

Right-click and select Start to run it again.

To remove it completely:

  1. Press Win and search for Add or Remove Programs.

  2. Find Leapwork Connect in the list.

  3. Select it, then select Uninstall, and approve the elevation prompt.

This stops and removes the service and deletes the connector's data directory, including its credentials and allowlist.

Linux

Bash
# Stop the systemd service temporarily
sudo systemctl stop leapwork-connect.service

# Start the systemd service again
sudo systemctl start leapwork-connect.service

# Remove the connector completely
sudo /var/lib/leapwork-connect/bin/Leapwork.Connect.Connector uninstall

macOS

Bash
# Stop the launchd daemon temporarily
sudo launchctl unload -w /Library/LaunchDaemons/com.leapwork.connect.plist

# Start the launchd daemon again after stopping it manually with unload
sudo launchctl load -w /Library/LaunchDaemons/com.leapwork.connect.plist

# Start the daemon after an automatic idle stop or a Disconnect from Play
# (the daemon is still loaded, so "load" does nothing)
sudo launchctl kickstart -k system/com.leapwork.connect

# Remove the connector and its daemon completely
sudo "/Library/Application Support/LeapworkConnect/bin/Leapwork.Connect.Connector" uninstall

If you are already root, drop the sudo.

uninstall unregisters the service or daemon and deletes the connector's install directory, including its credentials and allowlist. To connect that machine again afterwards, generate a new install command from Play.

From Play

In the Get Leapwork Connect dialog, pick the connector in the Connector dropdown (or select the status line if the workspace has only one) to open its details, where you can:

  • Rotate credentials - issues a fresh token and relay key, with no downtime.

  • Disconnect connector - the connector stops. Its credentials stay valid, but it does not reconnect on its own; start it again on the connector machine to restore access.

  • Revoke connector - invalidates the credentials, so that machine cannot reconnect at all. For the primary connector, generate a new command and re-enroll to restore access. Any other connector is removed from the list, so to use that machine again, add it as a new connector.

None of these take effect instantly. The connector reports in on a heartbeat every 30 seconds, and each of these actions waits for that heartbeat, so allow 30-60 seconds before the change is visible. The dialog keeps showing the action as pending until it lands. Revoke sits at the longer end: the connector shuts down after its second rejected heartbeat, so around 60 seconds.

Automatic stop when idle

You start the connector; Play decides when to stop it. An open tunnel is a live path into your private network and costs relay time, so it is not kept up while nothing is using it.

This is tracked per connector: a connector stops when nothing is using it, even if another connector in the workspace is busy.

Play counts what is currently using the connector:

  • an interactive or preview browser session on a private environment, counted from connect to disconnect;

  • a run list that touches a private environment, counted for the whole run list - so a list of private, public, public, private test cases does not tear the tunnel down in the middle. A run list that uses several connectors holds each of them for the whole run.

When that count reaches zero, a stop is armed but not sent yet. It waits a 10-minute grace period, so a run started shortly after the previous one finishes still finds the connector up. Anything that starts using the connector during the grace period cancels the pending stop and resets the window. Once the grace has elapsed, the connector shuts down on its next heartbeat.

After an automatic stop:

  • The connector stays installed and its credentials stay valid. Nothing needs re-enrolling.

  • It is left stopped on purpose. Only a crash is auto-restarted, and an idle shutdown is a clean exit.

  • Start it again when you next need private-network access, the same way as starting it after a manual stop above. It also comes back on its own the next time the machine reboots.

7. Read the connector's logs

Each connector writes a rolling log file to a Logs folder inside its install directory, on its own machine:

OS

Log folder

Windows

C:\ProgramData\LeapworkConnect\Logs

Linux

/var/lib/leapwork-connect/Logs

macOS

/Library/Application Support/LeapworkConnect/Logs

Files are named connector-<date>.log - for example connector-20260827.log. A new file starts on the first line written each day, so an idle connector adds nothing. The connector keeps the last 31 files and caps each at 5 MB, so the folder cannot grow without bound; a very busy day rolls into connector-20260827_001.log and so on. Reading them does not need elevation; a re-install keeps them, an uninstall deletes them.

What is in them

Every line is <timestamp with UTC offset> [<level>] pid:<process> <source> <message>. Each relay connection is numbered (#41), so its lines can be followed even when connections overlap.

What you will see

Level

When

Enrolled and persisted connector state for tenant …

INF

Install, once enrollment succeeds

Enrollment failed: <status> <body>

FTL

The token was rejected or the server was unreachable

Azure Relay listener opening on sb://… Target allowlist: …

INF

Each time the tunnel comes up - includes the allowlist in force

Azure Relay listener online.

INF

The tunnel is ready for traffic

#41 to app.internal:8080 opened — dialed 10.0.0.5:8080

INF

A request arrived and the target was reached, with the address actually dialled

#41 to app.internal:8080 closed after 1.4s — 812 bytes to the target, 40219 back

INF

That connection finished, with how much data moved each way

#42 to app.internal:9090 refused — not in the connector's allowed targets

WRN

The allowlist blocked it

#43 to db.internal:5432 dropped — host did not resolve

WRN

DNS inside your network has no answer for that host

#44 to app.internal:8080 dropped — dial timed out after 00:00:10

WRN

Nothing answered on that host and port

#45 to app.internal:8080 dropped — target connect failed for resolved addresses: …

WRN

The target actively refused the connection

#46 refused — resolves only to blocked (link-local/cloud-metadata) addresses

WRN

The host resolved to an address the connector will never dial

Tunnel exited after 42s. Reconnecting in 00:00:04

WRN

The tunnel dropped; the reconnect backoff is shown

Heartbeat unauthorized (401)

WRN

The connector was revoked, or its credentials are stale

Adopted rotated credentials

INF

A credential rotation from Play landed

Leapwork Connect connector stopped.

INF

Clean shutdown, including the idle auto-stop

A successful request produces the opened and closed pair. That pairing is what most questions turn on: no opened line means the request never got past the allowlist or DNS, while opened with 0 bytes back means the connector reached your application and your application said nothing.

Why one person generates so many connections

The numbers climb quickly, and that is expected - they are not one per user or one per test case. Each numbered line is a single TCP connection through the tunnel, and a browser opens a great many: Chromium keeps several sockets open per origin and dials every origin a page touches, so one page load alone can be dozens. For plain http:// targets it is one connection per request, because each request is sent and closed individually rather than reused. A single test case reaching one internal site can therefore fill hundreds of lines, all from one person. What matters is the target in each line, not the count.

When something throws, the full stack trace and any inner exceptions are written under the message, so a failure can be diagnosed from the file alone.

The file holds the connector's own events only. Lines from .NET and the operating-system hosting layer are left out unless they are a warning or worse, so the log stays a readable account of what the connector did rather than framework narration.

The log records hostnames, ports and addresses, never tokens or relay keys.

Route an environment through the connector

Installing the connector does not by itself send any traffic through it. Environments are set up per team, while connectors are shared across the workspace. In Team Settings → Environments, edit an environment and tick Private. Test cases using that environment then reach its URL through the connector, subject to the allowlist. The URL of a private environment must use http:// or https://.

If your workspace has more than one connector, a connector dropdown appears next to the Private tick. Pick the connector that can reach that environment's network. An environment that doesn't pick one uses the primary connector. If the chosen connector is unavailable when a test runs, the run error names that connector so you know which one to start or re-enroll.

Use more than one connector

A workspace can have several connectors, for example one per office or network. In Team Settings → Environments, click Get Leapwork Connect:

  • With no connector yet, the dialog goes straight to the install command.

  • Once a connector exists, a Connector dropdown lists each one with its state (connected, offline or not enrolled). Pick one to see its status, rotate its credentials, disconnect it, revoke it, or re-enroll it. Select the Add connector button next to the dropdown, enter a name such as "Staging network", and generate its install command. A name is required once the workspace already has a connector.

  • The connector the workspace already had becomes the primary. It keeps its credentials and stays connected through the upgrade; nothing needs re-enrolling.

Each connector is independent: its own credentials, allowlist, status, logs and auto-stop. Install each one on a different machine, since a machine runs a single connector. Revoking one never affects the others.

If a run fails to reach a private URL, run allowlist show on the connector machine first. An empty list, or a list missing that host and port, blocks the request.