agent-browser-google-chrome-linux

agent-browser を使ってユーザーの認証済み Chrome を操作する（Linux）

agent-browser

インストールされていない場合は、最初に一度だけインストールします。

npm i -g agent-browser

agent-browser install は実行しないでください。ユーザーセッションのないテスト用 Chromium がダウンロードされ、このスキルの目的が損なわれます。

agent-browser のコマンドを実行する前に、CLI から実際のワークフローの内容を読み込んでください。

agent-browser skills get core             # workflows, common patterns, troubleshooting
agent-browser skills get core --full      # include full command reference and templates

CLI がインストール済みバージョンに常に一致するスキルの内容を提供するため、手順が古くなることはありません。

主な制約

セキュリティ上の理由から、Chrome はデフォルトの user-data-dir（~/.config/google-chrome）でのリモートデバッグを拒否します。/tmp/chrome.log に次のエラーが表示されます。

DevTools remote debugging requires a non-default data directory. Specify this using --user-data-dir.

解決方法： ユーザーのプロファイルをデフォルト以外のディレクトリにコピーし、Chrome をすべて終了してから、コピーしたプロファイルでデバッグポートを指定して起動し、CDP 経由で agent-browser に接続します。

ステップ 0：正しい DISPLAY を見つける

Linux の環境は人それぞれ異なります。Chrome を起動する前に、ユーザーのデスクトップセッションが実行されている X ディスプレイを見つけてください。

# Option A: check what the user's shell already has
echo $DISPLAY

# Option B: scan running processes for an X display
ps aux | grep -oP 'DISPLAY=\S+' | sort -u

# Option C: list /tmp/.X11-unix sockets (each one is a display)
ls /tmp/.X11-unix/
# X0 → :0, X1 → :1, etc.

# Option D: look at who's logged into the X session
who | grep '(:[0-9]'

一般的な値は :0、:1、:10 です。見つかった値を使い、以下の手順にある DISPLAY=:1 を置き換えてください。Kasm/VNC 環境では通常 :1 ですが、まず確認してください。

echo $DISPLAY が何かを返す場合は、それが正しい値です。空の場合は、X 転送なしの SSH セッションである可能性が高いため、X11-unix ソケットを確認するか、ユーザーに確認してください。

手順（毎回、順番に実行）

セットアップ全体を進める前に、Chrome がデバッグポート付きですでに実行されているか確認してください。実行されていれば、そのまま接続に進めます。

# Quick check: is port 9222 already listening?
curl -s -m 2 http://127.0.0.1:9222/json/version | head -2

{"Browser": "Chrome/... という応答が返された場合、Chrome はリモートデバッグが有効な状態です。以下の「検証」セクションにあるワンライナーを実行してください。サインインページではなく対象サイトが表示された場合は完了です。残りの手順はスキップしてください。

ポートがリッスンしていない場合、またはサインインページが表示された場合は、以下の手順をすべて実行してください。

# 1. Kill ALL Chrome processes (any leftover holds the SingletonLock)
pkill -9 -f 'google-chrome\|/opt/google/chrome/chrome'
sleep 3
pgrep -af chrome | grep -v 'crashpad\|chrome-devtools\|grep'  # confirm empty

# 2. Verify the user's session is fresh in their profile
ls -la ~/.config/google-chrome/Default/Cookies   # check mtime is recent

# 3. Copy profile to a non-default location, strip the lock files
rm -rf /tmp/chrome-debug-profile
cp -a ~/.config/google-chrome /tmp/chrome-debug-profile
rm -f /tmp/chrome-debug-profile/Singleton{Lock,Cookie,Socket}

# 4. Launch Chrome with debug port on the display the user can see
#    Replace :1 with the DISPLAY value you found in Step 0
DISPLAY=:1 nohup google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug-profile \
  --no-sandbox --no-first-run --no-default-browser-check \
  'https://target-url-to-load-immediately' \
  >/tmp/chrome.log 2>&1 &
disown

# 5. Confirm port is listening (3-7s after launch)
sleep 6
curl -s -m 3 http://127.0.0.1:9222/json/version | head -2
# Expect: {"Browser": "Chrome/...

# 6. Connect agent-browser to the running Chrome
agent-browser --session <name> connect 9222
agent-browser --session <name> get url   # sanity check

ここからは、agent-browser --session <name> ... コマンドを実行するたびに、ユーザーから見える同じ Chrome ウィンドウが操作されます。

各フラグが重要な理由

フラグ	理由
DISPLAY=:1	ユーザーのセッションが実行されている X ディスプレイを指定します。ステップ 0 で正しい値を見つけてください
--remote-debugging-port=9222	agent-browser が接続する CDP エンドポイントです
--user-data-dir=/tmp/chrome-debug-profile	Chrome の「デフォルト以外のデータディレクトリ」というルールに必要です
--no-sandbox	多くのコンテナー／コーダー環境で必要です（SUID サンドボックスを利用できないため）
--no-first-run --no-default-browser-check	初回表示を妨げるウェルカムダイアログをスキップします
disown	親シェルが終了してもバックグラウンドジョブを存続させます

注意点

1. /tmp はセッション間で消去されます。 Coder／サンドボックス環境では、/tmp がクリーンアップされることがあります。前回の使用時と比べて /tmp/chrome-debug-profile の容量が大幅に小さくなっている場合（例：168M → 59M）、セッションが破損しています。~/.config/google-chrome からコピーし直してください。

2. ユーザーは、まずどこかでサインインしている必要があります。 ~/.config/google-chrome からのコピーが機能するのは、ユーザーがそこで有効なセッションを持っている場合だけです。Cookie の有効期限が切れているか、無効になっている場合は、先へ進めないサインインページが表示されます。まず通常の Chrome で再認証してもらってから、コピーし直してください。

3. Chrome のインスタンスが複数あっても、デバッグポートが複数になるわけではありません。 ユーザーが（フラグを付けずに）別の google-chrome を実行すると、既存のインスタンスに参加します。ポートにバインドするのは、--remote-debugging-port を指定した最初のインスタンスだけです。必ず先に pkill を実行してください。

4. 古い singleton ファイルが起動を妨げます。 cp -a の後は、コピー先から必ず rm -f Singleton{Lock,Cookie,Socket} を実行してください。実行しないと Chrome は起動を拒否します。

5. デバッグ用 Chrome からログインしようとしないでください。 自動ログインをブロックするサイト（MFA のプロンプト、CAPTCHA、OAuth フロー、ヘッドレスブラウザーの検出など）は、ここでもブロックされます。この手順では、ユーザーが通常の Chrome ですでに確立したセッションを利用することで、こうした問題を完全に回避します。

6. agent-browser が消えることがあります。 agent-browser は npm でグローバルにインストールされるため、nvm や /tmp のクリーンアップで削除されることがあります。npm i -g agent-browser で再インストールして（約5秒）、もう一度 connect 9222 を実行してください。Chrome のセッションは独立して維持されます。

7. agent-browser install は実行しないでください。 agent-browser install は、ユーザープロファイルや Cookie のない、テスト用の Chromium バイナリを別途ダウンロードします。必ずシステムの google-chrome バイナリを使用してください。

8. 最初のページが空白または読み込み中になります。 Chrome は起動後、CDP が応答するまで3～7秒かかります。接続する前に、必ず sleep 6 を実行してから curl /json/version を実行してください。

検証

起動後、すべての手順が機能していることを確認します。

agent-browser --session <name> connect 9222 && \
  agent-browser --session <name> get url

• 対象サイトの実際の URL が表示される → 接続できています。
• サインインページまたは認証ページが表示される → コピーしたセッションが古いか、有効期限切れです。通常の Chrome で再認証してもらってから、コピーし直してください。

使用しない場合

対象サイトで認証が不要な場合は、プロファイルのコピーを省略し、新しい空のプロファイルで起動してください。

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/fresh-chrome --no-sandbox &

ユーザーのプロファイルをコピーする手順が必要なのは、MFA、CAPTCHA、OAuth フロー、サインインページでのヘッドレスブラウザー検出などにより、ログインを自動化できないサイトに限られます。