メインコンテンツへスキップ
Runner は、Refrain サーバーに接続してローカルマシン上でブラウザコマンドを実行する常駐エージェントです。サーバーがジョブを送信すると、Runner がコマンドを受信し、ローカルブラウザで実行して結果を返送します。 Runner の起動方法は 2 つあります：
  • デスクトップアプリ — Windows / macOS 向けのシステムトレイアプリ。ほとんどのユーザーにおすすめです。
  • CLI — ヘッドレスサーバーや CI/CD 環境向けのターミナルコマンド。
Team プラン以上が必要です。Runner API キー（rfr_ プレフィックス）は Web コンソールで生成します。

​
セットアップ

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

Web コンソールを開く

Web コンソールの 設定 > Runners を開きます。
2

Runner を登録

Runner を登録 をクリックし、名前を付けます（例：「オフィス PC」「ステージングサーバー」）。
3

API キーをコピー

生成された API キー（rfr_...）をコピーします。このキーは一度だけ表示されます。
4

Runner を起動

デスクトップアプリまたは CLI（下記参照）で接続します。

​
デスクトップアプリ

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

​
ダウンロード

Web コンソール（設定 > Runners > Runner アプリをダウンロード）からダウンロードできます：
プラットフォーム形式
Windows.exe（インストーラー）
macOS.dmg

​
使い方

  1. アプリをインストールして起動します
  2. 設定ウィンドウで Runner API キー（rfr_...）とサーバー URL を入力します
  3. アプリが自動的に接続し、システムトレイに表示されます
  4. Runner がサーバーからのジョブを受け付ける準備が整いました
アプリはバックグラウンドで自動起動します。トレイアイコンのメニューからステータスの確認、設定変更、終了ができます。

​
CLI

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

​
概要

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 のデフォルト値

​
使用例

​
基本的な使い方

npx @refrainai/cli runner -- --api-key rfr_xxx

​
名前付き Runner

npx @refrainai/cli runner -- \
  --api-key rfr_xxx \
  --name "staging-runner"

​
環境変数を使用

export REFRAIN_RUNNER_API_KEY="rfr_xxx"

npx @refrainai/cli runner

​
動作の仕組み

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