lightpanda-browser

Lightpanda Browser — 高速ヘッドレス自動化

バックエンドエンジンとして Lightpanda を使用し、CDP（Chrome DevTools Protocol）経由で agent-browser CLI を通じて制御するヘッドレスブラウザー自動化です。

agent-browser よりこちらを使う場合：

Lightpanda を使う	agent-browser（Chromium）を使う
ウェブスクレイピング／データ抽出	スクリーンショット、PDF、ビジュアルテスト
フォームの自動化／送信	動画の録画／ビジュアルデバッグ
API レスポンスの検査	CSS レイアウトの検証
DOM の走査／コンテンツの解析	モバイル端末のエミュレーション（iOS）
RAM が限られた CI 環境	ブラウザー拡張機能の完全なサポート
大量の並列セッション	完全なレンダリングが必要なサイト

利用のきっかけ：

• 「lightpanda」「軽量ブラウザー」「高速ヘッドレス」
• 「低メモリでスクレイピング」「ヘッドレススクレイピング」
• 「レンダリングなしのブラウザー」「DOM 専用ブラウザー」
• 「高速なブラウザー自動化」「効率的なスクレイピング」
• 「lightpanda は chromium より速い？」「メモリ使用量が少ないヘッドレスブラウザーはどれ？」
• 「chromium を使わずにスクレイピングするには？」「RAM をあまり使わずにブラウザーを実行できる？」
• ビジュアル出力が不要なブラウザータスク全般

---

前提条件

Lightpanda をインストールする

# macOS (Apple Silicon)
curl -fsSL https://github.com/nichochar/install-lightpanda/raw/main/install.sh | bash

# Or build from source
git clone https://github.com/lightpanda-io/browser.git
cd browser && zig build -Doptimize=ReleaseSafe

agent-browser をインストールする（まだインストールされていない場合）

brew install agent-browser

インストールを確認する

lightpanda --version
agent-browser --version

---

基本的なワークフロー

各セッションは次のライフサイクルに従います。

1. Start Lightpanda daemon (CDP server)
2. Connect agent-browser via --cdp
3. Navigate, snapshot, interact
4. Stop daemon when done

ステップ 1 — Lightpanda を起動する

# Start Lightpanda CDP server on port 9222 (background)
lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!

# Wait for CDP to be ready
sleep 1

ステップ 2 — 接続して自動化する

# All agent-browser commands work via --cdp flag
agent-browser --cdp 9222 open https://example.com
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "search query"
agent-browser --cdp 9222 click @e2
agent-browser --cdp 9222 snapshot -i  # Re-snapshot after navigation

ステップ 3 — クリーンアップする

agent-browser --cdp 9222 close
kill $LIGHTPANDA_PID 2>/dev/null

---

サポートされているコマンド

以下のコマンドはすべて agent-browser --cdp <port> <command> として実行します。

ナビゲーション

agent-browser --cdp 9222 open <url>
agent-browser --cdp 9222 back
agent-browser --cdp 9222 forward
agent-browser --cdp 9222 reload
agent-browser --cdp 9222 close

スナップショット（DOM 分析）

agent-browser --cdp 9222 snapshot -i         # Interactive elements with refs
agent-browser --cdp 9222 snapshot -i -C      # Include cursor-interactive elements
agent-browser --cdp 9222 snapshot -s "#main"  # Scope to CSS selector
agent-browser --cdp 9222 snapshot -i --json   # JSON output for parsing

操作（スナップショットの @refs を使用）

agent-browser --cdp 9222 click @e1
agent-browser --cdp 9222 dblclick @e1
agent-browser --cdp 9222 fill @e2 "text"
agent-browser --cdp 9222 type @e2 "text"
agent-browser --cdp 9222 press Enter
agent-browser --cdp 9222 select @e1 "option"
agent-browser --cdp 9222 check @e1
agent-browser --cdp 9222 hover @e1
agent-browser --cdp 9222 scroll down 500
agent-browser --cdp 9222 drag @e1 @e2
agent-browser --cdp 9222 upload @e1 file.pdf

情報の取得

agent-browser --cdp 9222 get text @e1        # Element text
agent-browser --cdp 9222 get html @e1        # innerHTML
agent-browser --cdp 9222 get value @e1       # Input value
agent-browser --cdp 9222 get attr @e1 href   # Attribute
agent-browser --cdp 9222 get title           # Page title
agent-browser --cdp 9222 get url             # Current URL
agent-browser --cdp 9222 get count ".item"   # Count elements

待機

agent-browser --cdp 9222 wait @e1                     # Wait for element
agent-browser --cdp 9222 wait 2000                    # Wait milliseconds
agent-browser --cdp 9222 wait --text "Success"        # Wait for text
agent-browser --cdp 9222 wait --url "**/dashboard"    # Wait for URL
agent-browser --cdp 9222 wait --load networkidle      # Wait for network idle
agent-browser --cdp 9222 wait --fn "window.ready"     # Wait for JS condition

Cookie とストレージ

agent-browser --cdp 9222 cookies
agent-browser --cdp 9222 cookies set name value
agent-browser --cdp 9222 cookies clear
agent-browser --cdp 9222 storage local
agent-browser --cdp 9222 storage local set key value

ネットワークインターセプト

agent-browser --cdp 9222 network route <url>              # Intercept
agent-browser --cdp 9222 network route <url> --abort      # Block
agent-browser --cdp 9222 network route <url> --body '{}'  # Mock response
agent-browser --cdp 9222 network requests                 # View tracked
agent-browser --cdp 9222 network requests --filter api    # Filter

JavaScript の実行

agent-browser --cdp 9222 eval "document.title"
agent-browser --cdp 9222 eval -b "<base64>"
cat script.js | agent-browser --cdp 9222 eval --stdin

セマンティックロケーター

agent-browser --cdp 9222 find text "Sign In" click
agent-browser --cdp 9222 find label "Email" fill "[email protected]"
agent-browser --cdp 9222 find role button click --name "Submit"
agent-browser --cdp 9222 find testid "submit-btn" click

タブ

agent-browser --cdp 9222 tab                 # List tabs
agent-browser --cdp 9222 tab new [url]       # New tab
agent-browser --cdp 9222 tab 2               # Switch tab
agent-browser --cdp 9222 tab close           # Close tab

フレーム

agent-browser --cdp 9222 frame "#iframe"     # Enter iframe
agent-browser --cdp 9222 frame main          # Back to main

状態管理

agent-browser --cdp 9222 state save auth.json    # Save session state
agent-browser --cdp 9222 state load auth.json    # Restore session state

---

サポートされていないコマンド

Lightpanda にはレンダリングエンジンがありません。以下のコマンドは失敗するか、空の出力を返します。

コマンド	理由	代替手段
screenshot	ビジュアルレンダリングがない	コンテンツには get text／get html を使用します
pdf	CSS レイアウトエンジンがない	get html を使って外部で変換します
record start/stop	録画できるビジュアル出力がない	ネットワークリクエストのログを使用します
highlight	ビジュアルレンダリングがない	要素を特定するには snapshot -i を使用します
set device	ビューポートのエミュレーションがない	set headers でユーザーエージェントを設定します
set media	CSS メディアクエリをサポートしていない	N/A
get styles	計算済みスタイルがない	生の HTML／CSS を解析します
get box	レイアウトを計算しない	N/A
is visible	可視性を計算しない	代わりに DOM の存在を確認します

---

よく使われるパターン

大量のスクレイピング

# Start Lightpanda — uses ~60MB vs ~550MB for Chromium
lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

URLS=("https://site.com/page/1" "https://site.com/page/2" "https://site.com/page/3")
for url in "${URLS[@]}"; do
  agent-browser --cdp 9222 open "$url"
  agent-browser --cdp 9222 wait --load networkidle
  agent-browser --cdp 9222 get text body >> output.txt
  echo "---" >> output.txt
done

kill $LIGHTPANDA_PID 2>/dev/null

フォームの自動化

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

agent-browser --cdp 9222 open https://example.com/form
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "Jane Doe"
agent-browser --cdp 9222 fill @e2 "[email protected]"
agent-browser --cdp 9222 select @e3 "California"
agent-browser --cdp 9222 check @e4
agent-browser --cdp 9222 click @e5
agent-browser --cdp 9222 wait --load networkidle
agent-browser --cdp 9222 snapshot -i  # Verify result

kill $LIGHTPANDA_PID 2>/dev/null

認証済みセッション

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

# Login and save state
agent-browser --cdp 9222 open https://app.example.com/login
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "$USERNAME"
agent-browser --cdp 9222 fill @e2 "$PASSWORD"
agent-browser --cdp 9222 click @e3
agent-browser --cdp 9222 wait --url "**/dashboard"
agent-browser --cdp 9222 state save auth.json

# Reuse state later (new session)
agent-browser --cdp 9222 state load auth.json
agent-browser --cdp 9222 open https://app.example.com/dashboard
agent-browser --cdp 9222 snapshot -i

kill $LIGHTPANDA_PID 2>/dev/null

API レスポンスの検査

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

# Intercept API calls
agent-browser --cdp 9222 open https://app.example.com
agent-browser --cdp 9222 network requests --filter "/api/"

# Or mock API responses for testing
agent-browser --cdp 9222 network route "**/api/users" --body '{"users": []}'
agent-browser --cdp 9222 open https://app.example.com/users
agent-browser --cdp 9222 snapshot -i

kill $LIGHTPANDA_PID 2>/dev/null

異なるポートでの並列セッション

# Launch multiple Lightpanda instances for true parallelism
lightpanda serve --host 127.0.0.1 --port 9222 &
PID1=$!
lightpanda serve --host 127.0.0.1 --port 9223 &
PID2=$!
sleep 1

agent-browser --cdp 9222 open https://site-a.com &
agent-browser --cdp 9223 open https://site-b.com &
wait

agent-browser --cdp 9222 get text body > site-a.txt
agent-browser --cdp 9223 get text body > site-b.txt

kill $PID1 $PID2 2>/dev/null

---

環境変数

LIGHTPANDA_HOST="127.0.0.1"    # Bind address (default: 127.0.0.1)
LIGHTPANDA_PORT="9222"          # CDP port (default: 9222)

---

トラブルシューティング

Lightpanda が起動しない

# Check if port is in use
lsof -i :9222
# Kill existing process
kill $(lsof -t -i :9222) 2>/dev/null

CDP 接続が拒否される

# Verify Lightpanda is listening
curl -s http://127.0.0.1:9222/json/version
# Expected: JSON with browser info

「not supported」というエラーが表示されてコマンドが失敗する

Lightpanda はベータ版です。CDP メソッドがまだ実装されていない場合は、次の手順を実行してください。

1. Lightpanda のステータスページで、サポートされている API を確認します
2. 該当する操作では、agent-browser（Chromium）に切り替えます
3. https://github.com/lightpanda-io/browser/issues に問題を報告します

JavaScript の実行エラー

Lightpanda は V8 を使用していますが、すべての Web API が実装されているわけではありません。eval が失敗する場合は、次の手順を実行してください。

1. その API が Lightpanda のサポート機能に記載されているか確認します
2. 複雑な JavaScript の代わりに、よりシンプルな DOM 操作（get text、get html）を使用します

---

パフォーマンスのベンチマーク

Lightpanda と Chromium の選択に役立つ参考値です。一般的なスクレイピングのワークロードで測定しています。

指標	Lightpanda	Chromium (Playwright)	該当する場面
ページあたりのメモリ使用量	~60MB	~550MB	並列セッション、CI ランナー、リソースが限られた環境
コールドスタート	<100ms	~2s	短時間で終了するスクリプト、サーバーレス、高頻度の呼び出し
DOM のみのページ読み込み	~50ms	~300ms	大量のスクレイピング（数百ページでは差が積み重なります）
バイナリサイズ	~15MB	~300MB	Docker イメージ、CI キャッシュ、ディスク容量が限られたホスト
JS の実行（V8）	同等	同等	違いなし — 同じエンジンを使用
ページ全体のレンダリング	該当なし	~500ms	Lightpanda ではレンダリングできません — Chromium を使用します

選択の目安

シナリオ	推奨
10 ページ未満で、スクリーンショットが必要	Chromium — オーバーヘッドは無視できる程度です
10～100 ページで、テキスト抽出のみ	Lightpanda — RAM を 5～50GB 節約できます
100 ページ以上で、並列セッションを使用	Lightpanda — Chromium はメモリ制限に達します
RAM が 2GB に制限された CI	Lightpanda — Chromium では 3 ページのところ、30 ページ以上に対応できます
ビジュアルリグレッションテスト	Chromium — Lightpanda では画像を生成できません
フォーム送信とレスポンスの検証	どちらでも可 — Lightpanda のほうが高速ですが、どちらも動作します

---

調整時のルール

1. agent-browser のコマンドを実行する前に、必ず Lightpanda を起動します。 デーモンが起動していないと CDP 接続はエラーを出さずに失敗します — 続行する前に curl -sf http://127.0.0.1:9222/json/version で確認してください。
2. ナビゲーションのたびにスナップショットを取り直します。 ページが変わると Refs（@e1、@e2）は無効になります — これは Lightpanda 固有ではなく、agent-browser から引き継いだ仕様です。
3. コンテンツ抽出には eval より get text を優先します。 Lightpanda の Web API 対応範囲は不完全です — document.querySelector は動作しますが、複雑な API（IntersectionObserver、getComputedStyle）は動作しません。
4. 並列セッションには --session ではなく、個別のポートを使用します。 Lightpanda のインスタンスはシングルスレッドです — 複数のポートを使用すると真の並列処理が可能になり、--session は 1 つのインスタンス上で多重化します。
5. Chromium への切り替えは、明示的に行い、暗黙に行わないでください。 コマンドが「not supported」で失敗した場合は、その操作では agent-browser（--cdp フラグなし）に切り替えます。エラーを再試行したり、抑制したりしないでください。
6. 終了時にデーモンを停止します。 スクリプトで trap cleanup EXIT を使用し、Lightpanda のプロセスが残ってポート 9222 を消費しないようにします。
7. アップグレード前に Lightpanda のリリースノートを確認します。 ベータ版ソフトウェアのため、CDP メソッドの対応状況はバージョン間で変わります。更新後に、既知のページで agent-browser --cdp 9222 snapshot -i を実行し、スモークテストを行ってください。

---

詳細ドキュメント

参照	使用するタイミング
references/commands.md	CDP フラグの使用方法を含む、すべてのコマンドリファレンス
references/lightpanda-setup.md	インストール、設定、ソースからのビルド
references/compatibility.md	対応・非対応の CDP メソッドと Web API

すぐに使えるテンプレート

テンプレート	説明
templates/scrape-session.sh	デーモンの起動、ページのスクレイピング、クリーンアップ
templates/form-submit.sh	バリデーションを伴うフォーム入力と送信
templates/parallel-extract.sh	複数ポートでの並列データ抽出