Agent Setup
The FlowGuard agent is a small program you install on a computer that can reach your application. It runs your test flows in a real browser, and it can read your code on that computer to suggest flows. You install it once from the FlowGuard app. After that it connects to your workspace by itself.
Before you start
- A FlowGuard workspace. Sign up if you don’t have one yet.
- A computer for the agent: Windows with administrator rights, a Mac with an Apple chip (M1 or later), or any computer that runs Docker. A Linux installer is coming soon.
- You don’t need to install .NET or a browser first. The agent brings what it needs and downloads its browser the first time it runs a flow.
Install the agent
- In FlowGuard, open Agents (under Operations in the menu) and click Enrol agent.
- Choose the type of computer and give the agent a name.
- The app shows an install command with a one-time token already filled in. The token works once, and it stops working after the time you chose (from 1 hour to 7 days).
- Copy the command and run it on the agent computer, as described below.
- The app shows Connected when the agent has signed in.
Windows. Open PowerShell as administrator. The app offers two ways. The first downloads the signed installer (an .msi file) and gives you a line to run in the folder where you saved it. The second downloads and runs the installer in one line:
1iwr -useb https://download.flowguardians.com/agent/install-windows.ps1 | iex; Install-FlowGuardAgent -Tenant '<your workspace>' -Token '<token from the app>'macOS. Open Terminal and run the command as the user who will run the tests. The agent runs while that user is signed in.
1curl -fsSL https://download.flowguardians.com/agent/install-macos.sh | bash -s -- --tenant '<your workspace>' --token '<token from the app>'Docker. The app gives you a docker-compose.yml file. Save it on the computer and run docker compose up -d in the same folder.
The agent’s key
When the installer runs, it trades the one-time token for the agent’s own key and saves the key in a file on that computer. You never need to copy or type this key. The commands the app shows you read it from that file.
| Computer | Where the key is saved |
|---|---|
| Windows | C:\ProgramData\FlowGuard\agent-key (only administrators can read it) |
| macOS | ~/Library/Application Support/FlowGuard/agent-key |
Run flows
Once connected, the agent runs in the background and waits for work. When you start a run in the FlowGuard app, the agent picks it up, runs each step in a browser, and sends back screenshots and results. There is nothing to type on the agent computer.
To watch a single flow run on your own screen, open the flow in the editor and click Test Run. The app shows a command for your computer type. Run it on the agent computer: on Windows in PowerShell as administrator, on macOS as the user who installed the agent.
Scan your code
The agent can read your code on the agent computer and run two scans. The map scan uploads your .ts, .cs and .razor files, plus the names of your .csproj project files, and FlowGuard reads them to draw the Application Map, without AI. The flow scan sends a list of your file names and the first part of up to 20 files to the AI, which suggests test flows. Neither scan reads settings files such as appsettings.json or environment.ts.
Both scans leave out a git worktree (a second checkout of a repository on another branch) when its repository is also in the folder you scan. To leave out other folders, such as an old copy of a project, list them one per line in a file named .flowguardignore in that folder. The agent prints every folder it left out and why.
Open the application in FlowGuard, go to Codebase Analysis, click Update analysis, choose the scan under Local agent and copy its command. It already holds your application and workspace. Change the --path line to the folder that holds your code. On Windows the flow scan looks like this; the map scan is the same command with --mode graph-scan:
1& "C:\Program Files\FlowGuard Agent\current\FlowGuard.Agent.exe" `2 --mode scan `3 --path C:\path\to\your\codebase `4 --app-id <application id> `5 --api-url https://api.flowguardians.com `6 --tenant <your workspace>On macOS the first line reads the agent’s key from its file:
1FLOWGUARD_API_KEY="$(cat "$HOME/Library/Application Support/FlowGuard/agent-key")" \2 /usr/local/flowguard-agent/current/FlowGuard.Agent \3 --mode scan \4 --path /path/to/your/codebase \5 --app-id <application id> \6 --api-url https://api.flowguardians.com \7 --tenant <your workspace>You can also analyze code without the agent: in the same window, give FlowGuard the address of your repository and it reads the code in the cloud. See Codebase Analysis.
If the app never shows Connected
Restart the agent on its computer, then wait a minute:
- Windows (PowerShell as administrator):
Get-Service FlowGuardAgent | Restart-Service - macOS:
launchctl unload ~/Library/LaunchAgents/com.flowguardians.agent.plist && launchctl load -w ~/Library/LaunchAgents/com.flowguardians.agent.plist - Docker:
docker compose restart
If the token has run out, start again from Enrol agent to get a new one.