Skip to main content
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:
1

Open the Web Console

Go to Settings > Runners in the Web Console.
2

Register a runner

Click Register Runner and give it a name (e.g., “Office PC”, “Staging Server”).
3

Copy the API key

Copy the generated API key (rfr_...). This key is shown only once.
4

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):

​
Getting started

  1. Install and launch the app
  2. Enter your Runner API key (rfr_...) and server URL in the settings window
  3. The app connects automatically and appears in the system tray
  4. 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

​
Required arguments

​
Optional arguments

​
Environment variables

​
Examples

​
Basic usage

​
Named runner

​
Using environment variables

​
How it works

Both the Desktop App and CLI runner operate the same way:
  1. The runner activates with the server and begins polling for commands
  2. When the server dispatches a browser command (from a job), the runner receives and executes it locally
  3. Results (including screenshots, downloads, and recordings) are sent back to the server
  4. A heartbeat is sent every 30 seconds to maintain the connection
  5. If the connection is lost, the runner reconnects automatically with exponential backoff
  6. On shutdown, the runner deactivates gracefully