A Runner is a long-running browser agent that connects to your Refrain server and executes browser commands on its local machine. When the server dispatches a job, the runner receives the commands, executes them in a local browser, and sends results back.
There are two ways to run a Runner:
- Desktop App — a system tray application for Windows and macOS. Best for most users.
- CLI — a terminal command for headless servers and CI/CD environments.
Requires Team plan or higher. Runner API keys (rfr_ prefix) are generated in the Web Console.
Setup
Before starting a runner, register it in the Web Console:
Open the Web Console
Go to Settings > Runners in the Web Console.
Register a runner
Click Register Runner and give it a name (e.g., “Office PC”, “Staging Server”).
Copy the API key
Copy the generated API key (rfr_...). This key is shown only once.
Start the runner
Use the Desktop App or CLI (see below) to connect.
Desktop App
The Runner Desktop App runs in the system tray and stays connected in the background.
Download
Download the app from the Web Console (Settings > Runners > Download Runner App):
| Platform | Format |
|---|
| Windows | .exe (installer) |
| macOS | .dmg |
Getting started
- Install and launch the app
- Enter your Runner API key (
rfr_...) and server URL in the settings window
- The app connects automatically and appears in the system tray
- The runner is now ready to receive jobs from the server
The app starts automatically in the background. You can view status, change settings, or quit from the tray icon menu.
CLI
For headless servers, CI/CD pipelines, or scripted deployments, use the CLI runner.
Synopsis
npx @refrainai/cli runner -- \
--api-key <rfr_key> \
[options]
Required arguments
| Argument | Description |
|---|
--api-key <key> | Runner API key (must start with rfr_) |
Optional arguments
| Argument | Default | Description |
|---|
--name <name> | hostname | Runner display name shown in the Web Console |
Environment variables
| Variable | Description |
|---|
REFRAIN_RUNNER_API_KEY | Default for --api-key |
Examples
Basic usage
npx @refrainai/cli runner -- --api-key rfr_xxx
Named runner
npx @refrainai/cli runner -- \
--api-key rfr_xxx \
--name "staging-runner"
Using environment variables
export REFRAIN_RUNNER_API_KEY="rfr_xxx"
npx @refrainai/cli runner
How it works
Both the Desktop App and CLI runner operate the same way:
- The runner activates with the server and begins polling for commands
- When the server dispatches a browser command (from a job), the runner receives and executes it locally
- Results (including screenshots, downloads, and recordings) are sent back to the server
- A heartbeat is sent every 30 seconds to maintain the connection
- If the connection is lost, the runner reconnects automatically with exponential backoff
- On shutdown, the runner deactivates gracefully
