Skip to main content
Mo runs in a hosted browser. Use a tunnel when the app you want to test is on your machine or a private network. You can start one with the qa CLI or run the Connector Docker image on a network host.
Tunneling is in alpha. Behavior may change, and performance is not guaranteed.

Prerequisites

Configure the outbound firewall rules in Mo’s network access rules for the machine running qa tunnel or the Connector container. Tunnels require outbound TCP 443 to both the Momentic API server and Browser Fleet, and currently connect through West US 3. The machine also needs DNS resolution and network access to the target app. You don’t need to open an inbound port on your network for a tunnel.

Tunnel with the CLI

Use qa tunnel when the app is reachable from the machine running the CLI. Start the tunnel for the exact address Mo will open, then pass its ID to qa start:
The address can also be a private hostname or IP address. For example, if your machine can reach staging.internal:8080, you can tunnel it without Docker:
You can also pass an HTTP or HTTPS URL with an explicit port, such as http://localhost:3000/cart. The CLI preserves the scheme, hostname, and port. The tunnel covers that destination, not just the URL path. Quote a wildcard to tunnel subdomains on a specific port:
This matches nested subdomains, including api.team.staging.internal, but not staging.internal. Add the bare domain separately if needed. The tunnel machine resolves each hostname. Paths and query strings need no separate entries. Keep the tunnel running until the session finishes, then stop it with qa tunnel stop "$tunnel_id". Pass more addresses to qa tunnel start if the flow needs them. The qa tunnel reference covers foreground mode and listing tunnels. To keep a tunnel online across crashes and reboots, run it under a service manager. See keep a tunnel running.

Run the Connector with Docker

For a VM that can reach an internal app, run the Connector container there. The Connector needs outbound access to Momentic and does not open an inbound port on your network. Get the Connector image from Momentic before starting.

Start the Connector

Set CONNECTOR_IMAGE to the image reference Momentic gave you, and set MOMENTIC_API_KEY to your organization’s API key. This example lets Mo open https://app.internal.example through a Connector named internal-poc:
browserAddress is the host and port Mo opens. target is the host and port the Connector reaches on your network. Set scheme to http or https to match the app. On a Linux host, --network host lets the Connector reach services bound to the host’s loopback address. Keep the state volume so the Connector retains its identity across restarts. Check docker logs momentic-connector to confirm enrollment succeeds. Then start a Mo session with the Connector name:
See install the CLI for installation and sign-in.

Select a Connector in the app

In the composer’s session settings, choose it under Connector. Each entry shows Online, Offline, Unknown, or Outdated. None is selected by default, and Mo rejects a Connector that’s no longer available.

Keep a tunnel running

A qa tunnel runs as long as its process does. To keep one online across crashes and reboots, give it a name and let your operating system’s service manager restart it. The service resumes the same named tunnel after a restart.
On a host that can run Docker, the Connector Docker image with --restart unless-stopped does the same job with less setup.

Create the tunnel

Named tunnels need a recent qa. Run qa upgrade, then check that qa tunnel start --help lists --name.
Sign in with qa login, then create the tunnel once in a terminal. Replace localhost:3000 with your app’s address and checkout-dev with a name for the tunnel:
When the ready summary appears, press Ctrl+C. The tunnel goes offline but isn’t revoked, and qa tunnel list shows it as offline. The service below reuses the saved identity and doesn’t need an API key.

Linux

Run the tunnel as a systemd user service. Save this as ~/.config/systemd/user/qa-tunnel.service, with the absolute path that command -v qa prints:
If you installed qa with npm, it runs on Node.js, which the service can’t find through your shell’s PATH. Add a line under [Service] with the directory that dirname "$(command -v node)" prints:
Start it, and let it start at boot without a login:
Read the logs with journalctl --user -u qa-tunnel.service.

macOS

Run the tunnel as a launchd agent. Save this as ~/Library/LaunchAgents/ai.momentic.qa-tunnel.plist, with the absolute path that command -v qa prints:
Load it:
A launchd agent runs while you’re logged in to the Mac and starts again when you log in.

Windows

Task Scheduler starts a PowerShell script that restarts the tunnel whenever it exits. Save this as %USERPROFILE%\qa-tunnel.ps1:
On Windows Server 2016, replace qa.cmd and qa with npx.cmd --yes @momentic/qa-node throughout this page, including the check and stop commands. See Windows Server 2016. Then register the script with Task Scheduler. Pick the block for how the machine is used. On a machine that runs without anyone logged in, such as a server, run this in an elevated PowerShell. The task starts at boot:
The account needs the Log on as a batch job right, which administrators have. On a machine that you’re logged in to, run this in PowerShell. The task starts when you log in:
The script writes to %USERPROFILE%\qa-tunnel.log.

Check and stop the tunnel

qa tunnel stop checkout-dev disconnects the local host and keeps its saved identity. Disable any supervisor first so it does not restart the host. Check the tunnel from any terminal on the machine:
To stop it for good, remove the service first so it doesn’t restart the tunnel, then revoke it:

Notes

  • To share tunnels between accounts on one machine, use --config-dir, for example --config-dir "C:\ProgramData\Momentic\tunnels" on Windows. Use the same directory in your supervisor and terminal commands.
  • Multiple tunnel IDs can run at once and share a state directory. Each tunnel ID has one running process.
  • To change addresses without restarting the service, use qa tunnel update. Pass the full address list; omitted addresses are removed.
  • The service doesn’t inherit proxy variables such as HTTPS_PROXY from your shell. If the machine needs a proxy to reach Momentic, set it in the service definition.
  • The machine needs the tunnel network access whenever the service runs.