The AutoTestX Agent

Record, Pick element and Watch need a browser the tester can see. A hosted server has no screen, and usually cannot reach applications behind the company VPN. The AutoTestX Agent is a small program for Windows and macOS that opens those browsers on the tester’s own computer.

How it works

The agent connects out to the server over one secure WebSocket (/api/agent/connect). No firewall change is needed. It works wherever the web application does.
When the tester chooses Record, Pick or Watch, the server asks the agent to start the tester’s own browser with a throwaway profile, and drives it remotely: Microsoft Edge on Windows (Chrome as a fallback), Google Chrome on a Mac (Edge as a fallback).
The browser runs on the tester’s machine, inside their network and VPN, so it can reach internal applications.
Each tester pairs their own account. A computer is listed under Profile → Your computers, where it can be disconnected.

Whether the agent is used is set on the server with ATX_VISIBLE_BROWSER: agent (hosted), local (the server’s own screen) or auto (the agent if connected, otherwise local). See Configuration.

For testers: installing on Windows

In AutoTestX choose Record (or Watch, or Pick). If no agent is connected, the dialog shows Set up the AutoTestX Agent with a download button (AutoTestX-Agent.exe, about 80 MB). It is also under Profile → Your computers.
Run the downloaded file. It installs itself for your Windows user only (no administrator rights), starts at sign-in, and appears in Settings → Apps for removal.
A page opens in your browser asking you to Allow this computer. You must be signed in to AutoTestX there. Approve it.
The AutoTestX dialog continues by itself once the agent connects.

From then on the agent starts silently when you sign in to Windows.

If the agent is installed but not running, the dialog says Your AutoTestX Agent is not running. Start AutoTestX Agent from the Start menu, or sign out of Windows and back in. Check that you are on the VPN.

Unsigned installer: unless your administrator signs it, SmartScreen or endpoint protection may warn about or block the file. Ask your administrator.

For testers: installing on a Mac

In AutoTestX choose Record (or Watch, or Pick), or open Profile → Your computers. On a Mac the dialog shows a Terminal command instead of a download (choose Using a Mac instead? if it shows the Windows steps):
Terminal window
```
curl -fsSL https://app.example.com/api/agent/install-mac.sh | sh
```
Open Terminal (Applications → Utilities), paste the command and press Return. It downloads the agent for your Mac’s processor (Apple silicon or Intel) and installs it for your Mac user only in ~/Applications/AutoTestX Agent.app (no administrator password). It starts at login from then on; macOS shows a Background item added notice for it.
A page opens asking you to Allow this computer. Approve it, as on Windows.

If the agent is installed but not running, open AutoTestX Agent from Spotlight (⌘ Space), or log out and back in.

Why a Terminal command? Until the Mac agent is signed with an Apple Developer ID and notarized, macOS refuses to open it when it is downloaded through a browser. A file fetched with curl is not marked as downloaded, so it runs. The script is plain text: open the link in a browser to read what it does.

To remove it:

~/Applications/AutoTestX\ Agent.app/Contents/MacOS/autotestx-agent --uninstall

Several people on one computer

One agent can serve several AutoTestX members on the same computer account, each in their own browser, e.g. one in Edge and one in Chrome:

AutoTestX-Agent.exe --add-user --browser "C:\Program Files\Google\Chrome\Application\chrome.exe"

On a Mac, --browser takes the app: --browser "/Applications/Microsoft Edge.app".

The approval page opens in that browser, so it must be signed in to AutoTestX as the member being added. Revoking one member leaves the others connected.

Command-line options

Command	Does
`AutoTestX-Agent.exe` (Mac: `autotestx-agent` inside the app)	Install (first run), pair, then stay connected
`--uninstall`	Remove the agent and its pairing on the server
`--server <url>`	Use another server than the one built in
`--browser <exe>`	Use this browser instead of Edge / Chrome
`--add-user [--browser <exe>]`	Pair one more member on this computer
`--no-open`	Log the approval link instead of opening it
`--verbose`	Also log to the console
`--version`	Print the version and exit

If the agent is already running, a command is handed to the running copy.

Files

Path	Contents
`%LOCALAPPDATA%\AutoTestX\agent.log`	Log. Look here first when something does not work.
`%LOCALAPPDATA%\AutoTestX\agent.json`	Pairings (one per member)
`~/Library/Logs/AutoTestX/agent.log`	Log, on a Mac
`~/Library/Application Support/AutoTestX/agent.json`	Pairings, on a Mac
`~/Library/LaunchAgents/com.autotestx.agent.plist`	Starts the agent at login, on a Mac

For administrators: building the installer

The installer embeds node.exe, so it must be built on Windows:

npm run build:agent -- --server https://autotestx.example.com

It writes packages/agent/dist/AutoTestX-Agent.exe, which the server offers at /api/agent/download (path set by ATX_AGENT_EXE). npm run deploy builds, optionally signs (ATX_AGENT_SIGN_SCRIPT), and uploads it automatically.

The Mac agent

The Mac agent is built on a Mac, by the Mac agent GitHub workflow (.github/workflows/agent-mac.yml; run it from the Actions tab with the server’s address). It writes, as the agent-mac artifact:

File
`AutoTestX-Agent-mac-arm64.tar.gz`	The app for Apple silicon
`AutoTestX-Agent-mac-x64.tar.gz`	The app for Intel Macs
`install-mac.sh`	The install script, with the server’s address in it

Unzip the artifact into packages/agent/dist-mac and npm run deploy uploads it too. It refuses a build made for another server. The server offers the files at /api/agent/install-mac.sh and /api/agent/download/mac-<arch> from ATX_AGENT_MAC_DIR. These two routes need no sign-in, because curl has none. They contain only the server’s address, and an agent can do nothing until a signed-in member approves it. On a Mac you can also build it yourself: node packages/agent/build-mac.mjs --server https://autotestx.example.com.

To run the agent from source while developing (Windows or Mac):

npm run dev:agent -- --server http://127.0.0.1:4100 --verbose

Security

The agent only connects out. It opens no listening port.
Pairing uses a device-approval flow in a browser where the tester is already signed in. No password is ever typed into the agent.
The agent authenticates in the first WebSocket message. An unauthenticated connection is upgraded (101) and then closed, which is expected.
Each browser it opens uses a fresh, throwaway profile: no cookies, history or saved passwords from the tester’s normal browsing.