> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# runner

> Connect a remote browser runner to the Refrain server via the Desktop App or CLI.

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.

<Note>
  Requires Team plan or higher. Runner API keys (`rfr_` prefix) are generated in the Web Console.
</Note>

## Setup

Before starting a runner, register it in the Web Console:

<Steps>
  <Step title="Open the Web Console">
    Go to **Settings > Runners** in the Web Console.
  </Step>

  <Step title="Register a runner">
    Click **Register Runner** and give it a name (e.g., "Office PC", "Staging Server").
  </Step>

  <Step title="Copy the API key">
    Copy the generated API key (`rfr_...`). This key is shown only once.
  </Step>

  <Step title="Start the runner">
    Use the Desktop App or CLI (see below) to connect.
  </Step>
</Steps>

## 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

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

```bash theme={null}
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

```bash theme={null}
npx @refrainai/cli runner -- --api-key rfr_xxx
```

#### Named runner

```bash theme={null}
npx @refrainai/cli runner -- \
  --api-key rfr_xxx \
  --name "staging-runner"
```

#### Using environment variables

```bash theme={null}
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:

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