> ## Documentation Index
> Fetch the complete documentation index at: https://student-213fb9fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ブラウザサンドボックス

> ブラウザサンドボックスセッションを起動し、agent-browser、API、CLI、SDK、MCP 経由で Python、JavaScript、bash をリモート実行できます。

Firecrawl Browser Sandbox は、エージェントに安全でフルマネージドなブラウザー環境を提供します。ローカルでのセットアップは不要で、Chromium のインストールやドライバーの互換性問題も発生しません。agent-browser と Playwright はあらかじめインストール済みです。各セッションは分離された破棄可能なサンドボックス内で実行され、インフラを管理することなくスケールします。

[API](/ja/api-reference/endpoint/browser-create)、[CLI](/ja/sdks/cli#browser)（Bash / agent-browser、Python、Node）、[Node SDK](/ja/sdks/node#browser)、[Python SDK](/ja/sdks/python#browser)、[Vercel AI SDK](/ja/developer-guides/llm-sdks-and-frameworks/vercel-ai-sdk)、および [MCP Server](/ja/mcp-server) 経由で利用できます。

AI コーディングエージェント（Claude Code、Codex、Open Code、Cursor など）にブラウザー対応を追加するには、Firecrawl スキルをインストールします：

```bash theme={null}
npx -y firecrawl-cli@latest init --all --browser
```

また、上記の手順で Firecrawl CLI を自分でインストールすることも、エージェントにインストールを任せることもできます。

```bash theme={null}
npm install -g firecrawl-cli
```

<div id="quick-start">
  ## クイックスタート
</div>

セッションを作成し、コードを実行して終了します。

<CodeGroup>
  ```js Node theme={null}
  // npm install @mendable/firecrawl-js
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  // 1. セッションを起動
  const session = await firecrawl.browser();
  console.log(session.cdpUrl); // wss://cdp-proxy.firecrawl.dev/cdp/...

  // 2. Execute code
  const result = await firecrawl.browserExecute(session.id, {
    code: `
      await page.goto("https://news.ycombinator.com");
      const title = await page.title();
      console.log(title);
    `,
    language: "node",
  });
  console.log(result.result); // "Hacker News"

  // 3. Close
  await firecrawl.deleteBrowser(session.id);
  ```

  ```python Python theme={null}
  # pip install firecrawl
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  # 1. セッションを起動
  session = app.browser()
  print(session.cdp_url)  # wss://cdp-proxy.firecrawl.dev/cdp/...

  # 2. Execute code
  result = app.browser_execute(
      session.id,
      code='await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
      language="python",
  )
  print(result.result)  # "Hacker News"

  # 3. Close
  app.delete_browser(session.id)
  ```

  ```bash CLI theme={null}
  # Install the Firecrawl CLI
  npm install -g firecrawl-cli

  # 省略形 - セッションを自動起動、"execute"不要
  firecrawl browser "open https://news.ycombinator.com"
  firecrawl browser "snapshot"
  firecrawl browser "scrape"

  # Close when done
  firecrawl browser close
  ```

  ```bash cURL theme={null}
  # 1. セッションを起動
  curl -X POST "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json"

  # 2. Execute code
  curl -X POST "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID/execute" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "await page.goto(\"https://news.ycombinator.com\")\ntitle = await page.title()\nprint(title)"
    }'

  # 3. Close
  curl -X DELETE "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"
  ```
</CodeGroup>

* **ドライバーのインストール不要** - Chromium バイナリ不要、`playwright install` 不要、ドライバー互換性の問題なし
* **Python、JavaScript、Bash 対応** - API、CLI、または SDK 経由でコードを送信して結果を取得。3 つの言語すべてがサンドボックス環境上でリモート実行されます
* **agent-browser** - 40 以上のコマンドがプリインストール済みの CLI。AI エージェントは Playwright コードではなくシンプルな bash コマンドを書くことで操作できます
* **Playwright ロード済み** - サンドボックス環境には Playwright がプリインストール済み。必要であればエージェントは Playwright コードを記述することもできます
* **CDP へのアクセス** - 完全な制御が必要なときは、独自の Playwright インスタンスを WebSocket 経由で接続可能
* **ライブビュー** - 埋め込み可能なストリーム URL を使って、セッションをリアルタイムで監視可能
* **インタラクティブ ライブビュー** - 埋め込み可能なインタラクティブなストリームを通じて、ユーザーがブラウザを直接操作できるようにします

<div id="launch-a-session">
  ## セッションを開始する
</div>

セッションID、CDP URL、ライブビューのURLを返します。

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const session = await firecrawl.browser({
    ttl: 120,
    activityTtl: 60,
  });

  console.log(session.id);
  console.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...
  console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  session = app.browser(
      ttl=120,
      activity_ttl=60,
  )

  print(session.id)
  print(session.cdp_url)        # wss://cdp-proxy.firecrawl.dev/cdp/...
  print(session.live_view_url)  # https://liveview.firecrawl.dev/...
  ```

  ```bash CLI theme={null}
  # ライブビューとカスタムTTLで起動
  firecrawl browser launch-session --stream --ttl 120 --ttl-inactivity 60

  # 起動してセッション情報をファイルに保存
  firecrawl browser launch-session -o session.json --json
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "ttl": 120,
      "activityTtl": 60
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdpUrl": "wss://cdp-proxy.firecrawl.dev/cdp/550e8400-e29b-41d4-a716-446655440000",
  "liveViewUrl": "https://liveview.firecrawl.dev/550e8400-e29b-41d4-a716-446655440000",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/550e8400-e29b-41d4-a716-446655440000?interactive=true"
}
```

<div id="execute-code">
  ## コードの実行
</div>

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const result = await firecrawl.browserExecute("YOUR_SESSION_ID", {
    code: 'await page.goto("https://example.com"); const title = await page.title(); console.log(title);',
    language: "node",
  });

  console.log(result);
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  result = app.browser_execute(
      "YOUR_SESSION_ID",
      code='await page.goto("https://example.com")\ntitle = await page.title()\nprint(title)',
      language="python",
  )

  print(result)
  ```

  ```bash CLI theme={null}
  # agent-browserコマンド (デフォルト - "agent-browser"が自動的にプレフィックスとして付与されます)
  firecrawl browser execute "open https://example.com"
  firecrawl browser execute "snapshot"
  firecrawl browser execute "scrape"

  # Execute Playwright Python code
  firecrawl browser execute --python 'await page.goto("https://example.com")
  print(await page.title())'

  # Execute Playwright JavaScript code
  firecrawl browser execute --node 'await page.goto("https://example.com"); document.title'

  # Execute arbitrary bash in the sandbox
  firecrawl browser execute --bash 'ls /tmp'

  # Target a specific session
  firecrawl browser execute --session <id> "snapshot"
  ```

  ```bash cURL theme={null}
  # Execute Playwright Python code
  curl -X POST "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID/execute" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "await page.goto(\"https://example.com\")\ntitle = await page.title()\nprint(title)",
      "language": "python"
    }'

  # Playwright JavaScriptコードを実行
  curl -X POST "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID/execute" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "await page.goto(\"https://example.com\"); const title = await page.title(); console.log(title);",
      "language": "node"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "success": true,
  "result": "Example Domain"
}
```

<div id="agent-browser-bash-mode">
  ## agent-browser（Bash モード）
</div>

[agent-browser](https://github.com/vercel-labs/agent-browser) は、すべてのサンドボックスにプリインストールされているヘッドレスブラウザ CLI です。Playwright のコードを書く代わりに、エージェントはシンプルな bash コマンドを送信します。CLI は自動的に `--cdp` フラグを付与し、agent-browser がアクティブなセッションに自動で接続できるようにします。

<div id="shorthand">
  ### 省略記法
</div>

`browser` コマンドを使う最速の方法です。省略記法も `execute` も、どちらも自動的に agent-browser にコマンドを送信します。省略記法は単に `execute` を省略し、必要に応じてセッションを自動的に開始します。

```bash theme={null}
firecrawl browser "open https://example.com"
firecrawl browser "snapshot"
firecrawl browser "click @e5"
```

<div id="cli">
  ### CLI
</div>

明示的な形では `execute` を使用します。コマンドは自動的に agent-browser に送信されるので、`agent-browser` と入力したり、`--bash` を付けたりする必要はありません。

<CodeGroup>
  ```bash ナビゲーション & スナップショット theme={null}
  firecrawl browser execute "open https://example.com"
  firecrawl browser execute "snapshot"
  ```

  ```bash 操作 theme={null}
  firecrawl browser execute "click @e5"
  firecrawl browser execute "fill @e3 'search query'"
  firecrawl browser execute "scrape"
  ```
</CodeGroup>

<div id="api-sdk">
  ### API と SDK
</div>

API または SDK を使って agent-browser コマンドを実行するには、`language: "bash"` を指定します：

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.firecrawl.dev/v2/browser/YOUR_SESSION_ID/execute" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "code": "agent-browser snapshot",
      "language": "bash"
    }'
  ```

  ```javascript Node theme={null}
  const result = await app.browserExecute(sessionId, {
    code: "agent-browser snapshot",
    language: "bash",
  });
  ```

  ```python Python theme={null}
  result = app.browser_execute(
      session_id,
      code="agent-browser snapshot",
      language="bash",
  )
  ```
</CodeGroup>

<div id="session-management">
  ## セッション管理
</div>

<div id="persistent-sessions">
  ### 永続セッション
</div>

デフォルトでは、各ブラウザセッションは常にまっさらな状態から始まります。`profile` を使うと、セッション間でブラウザの状態を保存し再利用できます。ログイン状態の維持や設定の保持に役立ちます。

プロファイルを保存または選択するには、セッション作成時に `profile` パラメータを使用します。

<CodeGroup>
  ```js Node theme={null}
  const session = await firecrawl.browser({
    ttl: 300,
    profile: {
      name: "my-profile",
      saveChanges: true,
    },
  });
  ```

  ```python Python theme={null}
  session = app.browser(
      ttl=300,
      profile={
          "name": "my-profile",
          "save_changes": True,
      },
  )
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "ttl": 300,
      "profile": {
        "name": "my-profile",
        "saveChanges": true
      }
    }'
  ```

  ```bash CLI theme={null}
  # プロファイルで起動する（デフォルトで変更を保存）
  firecrawl browser launch-session --profile my-profile

  # 読み取り専用モードでプロファイルを使って起動する
  firecrawl browser launch-session --profile my-profile --no-save-changes

  # 短縮形：プロファイルで起動して一度に実行する
  firecrawl browser --profile my-profile "open https://example.com"
  ```
</CodeGroup>

| パラメータ         | デフォルト  | 説明                                                                                                           |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `name`        | —      | 永続プロファイルの名前。同じ名前のセッションはストレージを共有します。                                                                          |
| `saveChanges` | `true` | `true` の場合、ブラウザ状態は終了時にプロファイルへ保存されます。`false` に設定すると、既存データを読み込み専用で使用し、書き込みません — 複数の読み取り専用セッションを同時に扱いたい場合に便利です。 |

<Note>
  一度に 1 つのセッションだけがプロファイルへ保存できます。ほかのセッションがすでに保存中の場合、`409` エラーが返されます。同じプロファイルを `saveChanges: false` で開くか、時間をおいて再試行してください。
</Note>

ブラウザセッションの状態は、セッションがクローズされたときにのみ保存されます。したがって、再利用できるよう、使い終わったらブラウザセッションをクローズすることを推奨します。保存してクローズするには:

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  await firecrawl.deleteBrowser("YOUR_SESSION_ID");
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  app.delete_browser("YOUR_SESSION_ID")
  ```

  ```bash CLI theme={null}
  # アクティブなセッションを閉じる
  firecrawl browser close

  # 特定のセッションを閉じる
  firecrawl browser close --session <id>
  ```

  ```bash cURL theme={null}
  curl -X DELETE "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"id": "YOUR_SESSION_ID"}'
  ```
</CodeGroup>

<div id="list-sessions">
  ### セッション一覧を取得する
</div>

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const { sessions } = await firecrawl.listBrowsers();
  console.log(sessions);

  // ステータスでフィルター
  const { sessions: active } = await firecrawl.listBrowsers({ status: "active" });
  console.log(active);
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  response = app.list_browsers()
  print(response.sessions)
  ```

  ```bash CLI theme={null}
  firecrawl browser list
  firecrawl browser list active
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"

  # ステータスでフィルター
  curl -X GET "https://api.firecrawl.dev/v2/browser?status=active" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"
  ```
</CodeGroup>

```json Response theme={null}
{
  "success": true,
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "active",
      "cdpUrl": "wss://cdp-proxy.firecrawl.dev/cdp/550e8400-e29b-41d4-a716-446655440000",
      "liveViewUrl": "https://liveview.firecrawl.dev/550e8400-e29b-41d4-a716-446655440000",
      "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/550e8400-e29b-41d4-a716-446655440000?interactive=true",
      "createdAt": "2025-01-15T10:30:00Z",
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}
```

<div id="ttl-configuration">
  ### TTL 設定
</div>

セッションには 2 種類の TTL 設定があります:

| Parameter     | Default      | Description                    |
| ------------- | ------------ | ------------------------------ |
| `ttl`         | 300s (5 min) | セッションの最大存続時間 (30-3600s)        |
| `activityTtl` | 120s (2 min) | 非アクティブ時の自動クローズまでの時間 (10-3600s) |

<div id="close-a-session">
  ### セッションを終了する
</div>

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  await firecrawl.deleteBrowser("YOUR_SESSION_ID");
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  app.delete_browser("YOUR_SESSION_ID")
  ```

  ```bash CLI theme={null}
  # アクティブなセッションを閉じる
  firecrawl browser close

  # 特定のセッションを閉じる
  firecrawl browser close --session <id>
  ```

  ```bash cURL theme={null}
  curl -X DELETE "https://api.firecrawl.dev/v2/browser" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"id": "YOUR_SESSION_ID"}'
  ```
</CodeGroup>

<div id="live-view">
  ## ライブビュー
</div>

各セッションのレスポンスには `liveViewUrl` が含まれており、これを埋め込むことでブラウザーの状態をリアルタイムで確認できます。デバッグ、デモ、ブラウザー駆動型 UI の構築などに便利です。

```json Response theme={null}
{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdpUrl": "wss://cdp-proxy.firecrawl.dev/cdp/550e8400-...",
  "liveViewUrl": "https://liveview.firecrawl.dev/550e8400-...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/550e8400-...?interactive=true"
}
```

```html theme={null}
<iframe src="LIVE_VIEW_URL" width="100%" height="600" />
```

<div id="interactive-live-view">
  ### インタラクティブ Live View
</div>

レスポンスには `interactiveLiveViewUrl` も含まれます。閲覧専用の標準的な Live View と異なり、インタラクティブ Live View では、埋め込みストリームを通じてユーザーがブラウザセッションを直接操作できます（クリックや文字入力など）。これは、ユーザー向けのブラウザ UI の構築、共同でのデバッグ、あるいは閲覧者がブラウザを操作する必要があるあらゆるシナリオに有用です。

```html theme={null}
<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />
```

<div id="connecting-via-cdp">
  ## CDP 経由での接続
</div>

すべてのセッションは CDP WebSocket URL を提供します。`execute` API と `--bash` フラグでほとんどのユースケースはカバーできますが、完全にローカルで制御したい場合は、直接接続することもできます。

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Firecrawl from '@mendable/firecrawl-js';
  import { chromium } from "playwright-core";

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
  const session = await firecrawl.browser();

  const browser = await chromium.connectOverCDP(session.cdpUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] || (await context.newPage());

  await page.goto("https://example.com");
  console.log(await page.title());

  await browser.close();
  await firecrawl.deleteBrowser(session.id);
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl
  from playwright.sync_api import sync_playwright

  app = Firecrawl(api_key="fc-YOUR-API-KEY")
  session = app.browser()

  with sync_playwright() as p:
      browser = p.chromium.connect_over_cdp(session.cdp_url)
      context = browser.contexts[0]
      page = context.pages[0] if context.pages else context.new_page()

      page.goto("https://example.com")
      print(page.title())

      browser.close()

  app.delete_browser(session.id)
  ```

  ```bash agent-browser theme={null}
  # セッションのレスポンスで返される cdpUrl を使用
  agent-browser open https://example.com --cdp "$CDP_URL"
  agent-browser snapshot --cdp "$CDP_URL"
  ```
</CodeGroup>

<div id="when-to-use-browser">
  ## Browser を使うべきタイミング
</div>

| ユースケース                           | 適切なツール                        |
| -------------------------------- | ----------------------------- |
| 既知の URL からコンテンツを抽出する             | [Scrape](/ja/features/scrape) |
| Web を検索して結果を取得する                 | [Search](/ja/features/search) |
| ページネーションの操作、フォーム入力、クリックを伴うフローの操作 | **Browser**                   |
| インタラクションを伴うマルチステップのワークフロー        | **Browser**                   |
| 複数のサイトを並列にブラウジングする               | **Browser**（各セッションは分離されている）   |

<div id="use-cases">
  ## ユースケース
</div>

* **競合分析** - 競合サイトを閲覧し、検索フォームやフィルターを操作して、価格や機能を構造化データとして抽出する
* **ナレッジベースの取り込み** - クリック操作、ページネーション、認証が必要なヘルプセンター、ドキュメント、サポートポータルを辿る
* **市場調査** - 複数のブラウザーセッションを並列で起動し、求人サイト、不動産リスティング、法的データベースなどからデータセットを構築する

<div id="pricing">
  ## 料金
</div>

料金体系はシンプルで、ブラウザの稼働1分あたり2クレジットです。無料プランでは最大5時間まで無料で利用できます。

<div id="rate-limits">
  ## レート制限
</div>

初期リリースでは、すべてのプランで最大 20 個のブラウザーセッションを同時に稼働させることができます。

<div id="api-reference">
  ## API リファレンス
</div>

* [ブラウザセッションを作成](/ja/api-reference/endpoint/browser-create)
* [ブラウザコードを実行](/ja/api-reference/endpoint/browser-execute)
* [ブラウザセッションの一覧を取得](/ja/api-reference/endpoint/browser-list)
* [ブラウザセッションを削除](/ja/api-reference/endpoint/browser-delete)

***

ご意見やご不明な点がありましたら、[help@firecrawl.com](mailto:help@firecrawl.com) までメールいただくか、[Discord](https://discord.gg/gSmWdAkdwd) でご連絡ください。