qa CLI or run
the Connector Docker image on a network host.
Prerequisites
Configure the outbound firewall rules in Mo’s network access rules for the machine runningqa 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
Useqa 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:
staging.internal:8080, you can tunnel it without Docker:
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:
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
SetCONNECTOR_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:
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
Aqa 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.
Create the tunnel
Named tunnels need a recent
qa. Run qa upgrade, then check that qa tunnel start --help lists --name.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:
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:
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:
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:
Windows
Task Scheduler starts a PowerShell script that restarts the tunnel whenever it exits. Save this as%USERPROFILE%\qa-tunnel.ps1:
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:
%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:
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_PROXYfrom 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.