You can run a Link Agent from the mabl CLI, without Java and without a separate download. Use it to try mabl Link, to bring up a tunnel for a short task, or to run a personal Link tunnel from a terminal. This article explains how to start a Link Agent with the CLI and how to manage Link Agents from the command line.
For a Link Agent that runs around the clock and starts with its host, use the Windows installer, the Linux and macOS installer, or the Docker image instead. See Link Agent setup.
Before you start
- Install the mabl CLI, version 2.135.0 or later.
- Sign in with
mabl auth login, or activate an API key withmabl auth activate-key. To start a personal tunnel, you must sign in with your own account. - Make sure the computer is on a supported platform and can reach the addresses in Link Agent requirements.
Start a Link Agent
There are three ways to start a Link Agent from the CLI, depending on what you want it to serve:
- Name a tunnel on the command line to serve one workspace or company tunnel.
- Pass a configuration file to serve several tunnels, or to set proxy and connection filter options.
- Start a personal tunnel to route your own cloud runs through this computer.
Whichever way you start it, the first time the agent runs it downloads the component that runs the tunnel and keeps it for later runs. When the tunnel is ready, the CLI prints a line like this:
Tunnel qa-env-01 is connected to mabl. Press Ctrl-C to stop.
The agent runs until you stop it. Press Ctrl-C to stop it: the agent lets in-flight connections finish, then exits, so tests running through it are not cut off.
Name a tunnel on the command line
To serve a workspace tunnel, give the tunnel a name:
mabl link-agents start --tunnel qa-env-01
The agent serves the tunnel for your default workspace. To use a different workspace, add --workspace-id {workspace-id}. To serve a company tunnel instead, add --company-id {company-id}.
Use a configuration file
The CLI accepts the same configuration file format as the other Link Agent installations, so you can define tunnels, proxy settings, and connection filters in a file on this computer and pass it with --config instead of typing options each time. A personal tunnel doesn't use a configuration file, and --config can't be combined with --personal.
mabl link-agents start --config /path/to/config.yaml
A configuration file can list several tunnels, and one agent serves all of them. The agent uses the API key in the file instead of your CLI sign-in. Options on the command line take precedence over the file. The agent watches the file while it runs, so you can add or remove tunnels without restarting it.
The CLI's Link Agent supports the mabl, all, upstream, and none proxy modes. It does not support proxy auto-configuration (PAC) or following the operating system's proxy settings. If your network needs either one, use one of the other installations.
Start a personal tunnel
To route your own cloud runs through this computer, start a personal tunnel:
mabl link-agents start --personal
A personal tunnel is identified by your computer, so it takes no tunnel name and can't be combined with --tunnel, --workspace-id, --company-id, or --config.
You can also start a personal tunnel from the mabl Desktop App, with no terminal:
- From the mabl app menu bar, go to Edit > Link tunnels
- In the Personal tunnel tab, click ON. See Start a personal tunnel from the mabl Desktop App.
Whether you start a personal tunnel from the CLI or the mabl Desktop App, a workspace owner must first allow personal tunnels. See Personal Link tunnels.
Options
| Option | Description |
|---|---|
--tunnel {name} |
The tunnel to serve. Names are 1 to 24 characters of lowercase letters, numbers, and dashes. |
--workspace-id, -w
|
The workspace that owns the tunnel. Defaults to your configured workspace. |
--company-id |
Serve a company tunnel instead of a workspace tunnel. |
--config, -c
|
Path to a Link Agent configuration file, in YAML or JSON. |
--personal |
Serve your personal tunnel. Requires mabl auth login. |
--no-auto-update |
Keep the current version of the tunnel component instead of installing updates as they are published. |
--debug |
Log more detail, for diagnosing a tunnel that won't connect or keeps dropping. |
For every option, see the mabl CLI command reference.
Find the logs
The agent writes its logs to files as well as to the terminal, and prints the log directory when it starts. The directory holds a link-agent log for the agent and a link-worker log for each tunnel it serves. Include both when you contact mabl about a tunnel.
Manage Link Agents from the command line
The CLI also manages Link Agents however they were installed:
| Command | What it does |
|---|---|
mabl link-agents list |
List the Link Agents that have checked in recently, with their status, host, and version. |
mabl link-agents maintenance start {id} |
Put an agent into maintenance mode: it stops accepting new connections and lets current ones finish. Add --drain-timeout {seconds} to limit how long it waits. |
mabl link-agents maintenance end {id} |
Take an agent out of maintenance mode. |
mabl link-agents terminate {id} |
Shut down a Link Agent. |
Get an agent's ID from mabl link-agents list or from Settings > Networking. For when to use maintenance mode, see Maintaining and updating Link Agents.
To check that a tunnel can reach a service in your network, use the mabl link-agents test commands. See Testing and diagnosing Link connections.