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

> デスクトップアプリまたは CLI で、リモートブラウザ Runner を Refrain サーバーに接続します。

Runner は、Refrain サーバーに接続してローカルマシン上でブラウザコマンドを実行する常駐エージェントです。サーバーがジョブを送信すると、Runner がコマンドを受信し、ローカルブラウザで実行して結果を返送します。

Runner の起動方法は 2 つあります：

* **デスクトップアプリ** — Windows / macOS 向けのシステムトレイアプリ。ほとんどのユーザーにおすすめです。
* **CLI** — ヘッドレスサーバーや CI/CD 環境向けのターミナルコマンド。

<Note>
  Team プラン以上が必要です。Runner API キー（`rfr_` プレフィックス）は Web コンソールで生成します。
</Note>

## セットアップ

Runner を起動する前に、Web コンソールで登録します：

<Steps>
  <Step title="Web コンソールを開く">
    Web コンソールの **設定 > Runners** を開きます。
  </Step>

  <Step title="Runner を登録">
    **Runner を登録** をクリックし、名前を付けます（例：「オフィス PC」「ステージングサーバー」）。
  </Step>

  <Step title="API キーをコピー">
    生成された API キー（`rfr_...`）をコピーします。このキーは一度だけ表示されます。
  </Step>

  <Step title="Runner を起動">
    デスクトップアプリまたは CLI（下記参照）で接続します。
  </Step>
</Steps>

## デスクトップアプリ

Runner デスクトップアプリはシステムトレイに常駐し、バックグラウンドで接続を維持します。

### ダウンロード

Web コンソール（**設定 > Runners > Runner アプリをダウンロード**）からダウンロードできます：

| プラットフォーム | 形式              |
| -------- | --------------- |
| Windows  | `.exe`（インストーラー） |
| macOS    | `.dmg`          |

### 使い方

1. アプリをインストールして起動します
2. 設定ウィンドウで Runner API キー（`rfr_...`）とサーバー URL を入力します
3. アプリが自動的に接続し、システムトレイに表示されます
4. Runner がサーバーからのジョブを受け付ける準備が整いました

アプリはバックグラウンドで自動起動します。トレイアイコンのメニューからステータスの確認、設定変更、終了ができます。

## CLI

ヘッドレスサーバー、CI/CD パイプライン、スクリプトによるデプロイでは CLI Runner を使用します。

### 概要

```bash theme={null}
npx @refrainai/cli runner -- \
  --api-key <rfr_key> \
  [options]
```

### 必須引数

| 引数                | 説明                                |
| ----------------- | --------------------------------- |
| `--api-key <key>` | Runner API キー（`rfr_` で始まる必要があります） |

### オプション引数

| 引数              | デフォルト | 説明                          |
| --------------- | ----- | --------------------------- |
| `--name <name>` | ホスト名  | Web コンソールに表示される Runner の表示名 |

### 環境変数

| 変数                       | 説明                  |
| ------------------------ | ------------------- |
| `REFRAIN_RUNNER_API_KEY` | `--api-key` のデフォルト値 |

### 使用例

#### 基本的な使い方

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

#### 名前付き Runner

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

#### 環境変数を使用

```bash theme={null}
export REFRAIN_RUNNER_API_KEY="rfr_xxx"

npx @refrainai/cli runner
```

## 動作の仕組み

デスクトップアプリと CLI Runner は同じ仕組みで動作します：

1. Runner はサーバーに対してアクティベーションを行い、コマンドのポーリングを開始します
2. サーバーがジョブからブラウザコマンドを送信すると、Runner がそれを受信しローカルで実行します
3. 実行結果（スクリーンショット、ダウンロード、録画を含む）はサーバーに返送されます
4. 接続を維持するため、30 秒ごとにハートビートを送信します
5. 接続が切断された場合、指数バックオフで自動的に再接続します
6. シャットダウン時、Runner はグレースフルに非アクティブ化されます