vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox は、agent-browser + headless Chrome を Vercel Sandbox microVM 内で動かすブラウザ自動化スキルです。リクエストごとに軽量な Linux 仮想マシンを起動し、ブラウザ操作コマンドを実行し終わったら、その VM を破棄します。

処理がすべて Vercel Sandbox 内で完結するため、このスキルは Vercel にデプロイされたアプリ（Next.js, SvelteKit, Nuxt, Remix, Astro などの各種フレームワーク）が、サーバーレスやエッジのような実行環境から直接、実ブラウザの自動操作を行う用途に向けて設計されています。

What problems does it solve?

従来のサーバーレスランタイムは、フル機能の Chrome を動かす用途にはあまり向いていません。

• バイナリサイズの制限やコールドスタートにより、headless Chrome をバンドルしにくい。
• Chromium が必要とするシステムライブラリが実行環境に存在しないことが多い。
• 長時間稼働する、あるいは状態を持つブラウザセッションの管理が難しい。

vercel-sandbox はこれらを次の方法で解決します。

• ブラウザジョブごとに 専用の microVM を起動する。
• VM 内に Chromium のシステム依存ライブラリ をインストールする。
• agent-browser を使って Chrome を制御し、ナビゲーション、クリック、フォーム入力、スクリーンショット取得などを行う。
• 同一 sandbox ライフサイクル内で、複数コマンド間で状態を維持したブラウザセッション をサポートする。
• 各実行を 分離かつエフェメラル（短命） に保つことで、安全性を高め、リクエスト間の状態リークを抑える。

Who is vercel-sandbox for?

このスキルがフィットしやすいのは、次のようなケースです。

• Vercel にデプロイしており、アプリや API Routes から実ブラウザの自動操作を行いたい。
• バンドルサイズ制限を気にせず headless Chrome を動かしたい。
• Vercel 上のアプリに UI テスト、スクレイピング、インタラクションフロー を組み込みたい。
• ユーザーごとの処理などに、短命で分離されたブラウザ環境 が必要。

特に以下のようなシナリオで有用です。

• Vercel 上の Next.js, SvelteKit, Nuxt, Remix, Astro などのアプリ。
• E2E チェックやビジュアルリグレッション、スモークテストを追加したいフロントエンドチーム。
• ログインフローや複雑なクライアントサイドアプリなど、実ブラウザでサードパーティサイトを読み込む必要がある API エンドポイント。

When is it not a good fit?

次のような場合には vercel-sandbox は最適とは言えないかもしれません。

• Vercel にデプロイしていない、または Vercel Sandbox を利用できない。
• 単純な HTTP リクエストだけで足りており、実ブラウザを必要としない（通常の HTTP クライアントの利用で十分な場合）。
• 数分〜数時間単位で動き続ける 長時間稼働・常駐型のブラウザプロセス が必要な場合。このスキルはエフェメラルな microVM 前提で設計されています。

主な目的がフロントエンド向けの汎用ユーティリティやビルド時ツールであれば、Sandbox 依存のない、よりシンプルなスキルの方が適している可能性があります。

How to Use

1. Prerequisites and dependencies

vercel-sandbox を利用するには、以下が必要です。

• Vercel Sandbox microVM を利用できる Vercel プロジェクト。
• sandbox を呼び出せる JavaScript/TypeScript のコードベース（例: Next.js の API Routes や Server Actions）。
• プロジェクトに @vercel/sandbox がインストールされていること:

pnpm add @vercel/sandbox

sandbox VM 内で Chromium を動かすには、（Amazon Linux / dnf ベースの環境向けに）いくつかのシステムライブラリが必要になります。リポジトリ内のパターンでは、これらの要件を表す CHROMIUM_SYSTEM_DEPS 配列を定義し、Chrome を起動する前に VM 内でインストールするようになっています。

2. Core execution pattern

vercel-sandbox の基本的な実行パターンは次の通りです。

1. @vercel/sandbox から Sandbox を import する。
2. sandbox を設定し、Chromium system deps と agent-browser をインストールするように構成する。
3. sandbox を起動し、ブラウザ自動化コマンドを実行してから microVM のシャットダウンに任せる。

スキルとのワイヤリングはエージェントシステム側で処理されます。Vercel アプリはこのスキル経由でブラウザ操作をトリガーし、スキル側が Chrome の入った microVM 内でそれらを実行されるようにします。

3. Installing vercel-sandbox as a skill

もし skills ベースのエージェント環境を利用している場合は、次のコマンドでリポジトリからこのスキルを追加できます。

npx skills add https://github.com/vercel-labs/agent-browser --skill vercel-sandbox

これにより、vercel-labs/agent-browser リポジトリから vercel-sandbox のスキル定義が取得され、エージェントや自動化フレームワークから利用可能になります。このスキルは次のような処理を担います。

• Vercel Sandbox microVM の起動。
• Chrome と必要なシステム依存ライブラリのインストール。
• agent-browser を呼び出してブラウザセッションを制御。

4. Typical workflows

スキルをインストールし、エージェント側との接続ができたら、vercel-sandbox を使って Vercel アプリ内でさまざまなブラウザ自動化ワークフローを実現できます。

a. Automating end-to-end user flows

ユーザージャーニーを再現する用途でスキルを利用できます。

• microVM 内のブラウザからアプリの URL にアクセス。
• ログイン、フォーム入力、画面遷移などの一連のフローを実行。
• 各ステップでスクリーンショットや HTML スナップショットを取得。

これはデプロイ時やスケジュール実行でのスモークテストに有用です。

b. Capturing screenshots and visual checks

headless Chrome を使って次のような処理を行えます。

• ページ全体や特定のビューポート範囲のスクリーンショット取得。
• レイアウトや重要な UI 要素の検証。
• （独自の比較ロジックと組み合わせることで）リリース間のスクリーンショット比較。

c. Interacting with third-party sites

JavaScript 依存が強いページや複雑な認証フローなど、通常の HTTP だけでは扱いづらい統合もサポートできます。

• 外部ダッシュボードやパートナーサイトを開く。
• クリック、待機、評価といった制御されたインタラクションを実行。
• agent-browser のコマンドを用いて必要なデータを抽出。

すべてが sandbox 化された VM 内で実行されるため、各リクエストは相互に分離されています。

5. Performance and snapshots

リポジトリでは、sandbox snapshots を利用して Chromium と agent-browser を事前インストールし、サブ秒レベルの起動時間 を実現できると説明されています。実際の運用イメージは次の通りです。

• Chrome と依存ライブラリをインストール済みの VM を snapshot イメージとして作成する。
• 次回以降のブラウザジョブは、その snapshot から起動することで毎回のインストールを省略する。

これにより、vercel-sandbox は Vercel アプリ内でのオンデマンド自動化に十分なレスポンスを保てます。

6. Operational tips

• VM 単位で作業をまとめる: 関連するブラウザコマンドはできるだけ 1 回の sandbox 実行内にまとめ、VM の起動オーバーヘッドを抑えましょう。
• タイムアウト管理: microVM は設計上短命なので、フローには明確なタイムアウトとリトライ戦略を組み込んでおきましょう。
• リソース使用量の監視: ブラウザ自動化は単純な HTTP よりも負荷が高いため、スクリプトは効率的に保ち、不要なページやタブの利用は避けましょう。

FAQ

What does vercel-sandbox actually run inside the microVM?

vercel-sandbox は、agent-browser と headless Chrome を Vercel Sandbox microVM 内で並行して実行します。VM はまず Chromium のシステム依存ライブラリをインストールし、その後ブラウザを起動し、ナビゲーション・インタラクション・キャプチャ用のコマンドを提供します。

Can I use vercel-sandbox with any Vercel framework?

はい。スキル自体はフレームワーク非依存で、Next.js, SvelteKit, Nuxt, Remix, Astro などを含む 任意の Vercel デプロイフレームワーク で利用できます。sandbox と通信できるサーバーサイドコードを実行できれば問題ありません。

How is this different from running Chrome directly in a serverless function?

serverless function 内で直接 Chrome を動かす場合、バンドルサイズの制限や不足しているシステムライブラリ、実行時間制約などの問題が発生しがちです。vercel-sandbox は、ジョブごとに 専用 microVM を使うことで、次のような違いがあります。

• Chromium に必要なシステムライブラリを自由にインストールできる。
• バイナリサイズ制限を気にせず agent-browser を実行できる。
• sandbox セッションの存続期間中はブラウザ状態を保持できる。

Does vercel-sandbox support persistent sessions?

単一の sandbox ライフサイクル内であればサポートされます。説明にある通り、VM が稼働している間は、複数コマンドにまたがって状態を維持したブラウザセッション を持つことができます。ただし各 microVM 自体は エフェメラル であり、sandbox 実行が終わると状態は破棄されます。

Is vercel-sandbox safe to run with untrusted tasks?

各ブラウザジョブは 分離された Vercel Sandbox microVM 内で実行されるため、タスク間には強力な分離境界が設けられます。とはいえ、通常のセキュリティプラクティス（入力検証、レートリミット、監視など）は引き続き適用すべきですが、VM レベルの分離によって各ジョブを閉じ込めやすくなっています。

Do I have to manage Chromium system dependencies myself?

リポジトリの基本パターンでは、Amazon Linux / dnf 環境向けに一式の Chromium system dependencies が定義されています。vercel-sandbox スキルはこのパターンを利用しており、必要なライブラリはメインアプリのバンドルではなく sandbox VM 内にインストールされます。ただし、利用する Chromium のバージョンに合わせて依存関係リストを更新する必要が生じる場合があります。

When should I not use vercel-sandbox?

次のような場合には vercel-sandbox の利用を避けることを検討してください。

• Vercel を利用していない、または Vercel Sandbox を有効化できない。
• シンプルな HTTP クライアントや API 連携だけで要件を満たせる。
• オンデマンドかつ短命 な sandbox 実行ではなく、長時間稼働する常駐オートメーションワーカーが必要。

How do I install vercel-sandbox as part of my agent setup?

vercel-labs/agent-browser リポジトリからスキルを追加するには、次のコマンドを使用します。

npx skills add https://github.com/vercel-labs/agent-browser --skill vercel-sandbox

インストール後は、エージェント側の設定で、（"Vercel Sandbox browser"、"microVM Chrome"、"browser automation on Vercel" などの）ブラウザ自動化リクエストを vercel-sandbox スキルへルーティングするよう構成してください。

Where can I learn more about the implementation details?

主なリファレンスは vercel-labs/agent-browser リポジトリ内の skills/vercel-sandbox 配下にあります。まずは SKILL.md から読み始めるとよいでしょう。そこでは次のような内容を確認できます。

• sandbox セットアップのパターン。
• Chromium system dependencies の一覧。
• agent-browser を microVM 内でどのように実行するか。

これらを参考にしながら、自分のプロジェクトで vercel-sandbox の動作をカスタマイズ・拡張することができます。