gist.md

VercelLogotype

    AI Cloud
    Core Platform
    Security
    Company
    Learn
    Open Source
    Use Cases
    Tools
    Users

The safest way to run code you didn’t write.

Modern apps increasingly need to execute code they didn’t author. From AI agents, customer scripts, or dynamic systems. remote-sandbox.vercel.run Sandbox is not running Agent Generate a Next.js app that allows to list and search Emojis Create Sandbox Upload files Execute Execute Get Sandbox URL

Reducing the risk of untrusted code, at scale. Cost-efficient, scalable execution with Fluid compute

Vercel Sandbox runs on Fluid compute, Vercel optimized execution model that scales CPU and memory dynamically across millions of executions.

With Active CPU pricing, you’re billed only when code is actively running, not during idle or wait time, resulting in up to 95% lower cost for workloads with bursty or I/O-bound patterns. "

Vercel Sandbox expands what our frontend infrastructure can handle. We plan to rely on it more for running untrusted code in AI workflows and for integrating tools that cannot run in a Node.js serverless function."

Tudor Golubenco

CTO, Xata Xata "

Cua lets teams run computer-use agents from their apps with 100+ compatible VLMs — agents operate real desktops backed by Vercel Sandbox. Next.js playground on Vercel; agents execute in Vercel Sandbox via Cua with logs, replays, and evals — fully suited for reinforcement learning (RL) workflows."

Francesco Bonacci

Founder, Cua AI Cua Get started

You can get started with Vercel Sandbox quickly and easily. Launch a secure, interactive sandbox environment in milliseconds.

$ npx sandbox create --connect

Quickly give Vercel Sandbox a try with your AI tool of choice. Bootstrap a simple Node.js CLI that creates a Vercel sandbox. Use this code:

import { Sandbox } from '@vercel/sandbox';

const sandbox = await Sandbox.create();

const { exitCode } = await sandbox.runCommand({ cmd: 'node', args: ['-e', 'process.exit(0)'], });

console.log(exitCode === 0 ? 'ok' : 'failed');

await sandbox.stop();

Include auth setup (vercel login && vercel link) with error handling. Frequently Asked Questions

Vercel Sandbox is an on-demand, isolated Linux microVM that runs arbitrary code safely through an SDK or CLI.

Sandbox gives you secure microVM isolation, built-in authentication and observability, and usage-based pricing without any infrastructure to maintain.

Yes. Sandbox is purpose-built to execute untrusted or AI-generated code in fully isolated, short-lived environments.

Each sandbox runs inside a Firecracker microVM on the same infrastructure that powers Vercel’s build system.

Node.js 22 and Python 3.13 are available by default, with more runtimes coming soon.

Yes. Each sandbox runs on Amazon Linux 2023, so you can install packages with dnf and use sudo as needed.

Sandboxes run for 5 minutes by default, up to 45 minutes on Hobby and 5 hours on Pro and Enterprise plans, with programmatic extensions available.

Each sandbox can use up to 8 vCPUs and 2 GB of RAM per vCPU.

Yes. You can open up to four ports and access them through a sandbox URL, such as sandbox.domain(port).

You can view active sandboxes in the Observability → Sandboxes view for your project, and stream real-time logs to your terminal.

Ready to deploy? Start building with a free account. Speak to an expert for your Pro or Enterprise needs.

Trial Vercel with higher execution, increased app bandwidth, Speed Insights, team features, and more. Products

AI
Enterprise
Fluid Compute
Next.js
Observability
Previews
Rendering
Security
Turbo
Domains
Sandbox
Workflow
v0

Resources

Community
Docs
Knowledge Base
Academy
Help
Integrations
Platforms
Pricing
Resources
Solution Partners
Startups
Templates

Company

About
Blog
Careers
Changelog
Contact Us
Customers
Events
Partners
Shipped
Privacy Policy

Social

GitHub
LinkedIn
Twitter
YouTube

Loading status… Select a display theme: system light dark

vercel sandboxの使い道を教えて

Vercel Sandbox は、Vercel が提供する「短時間で立ち上がる隔離された Linux microVM（Firecracker）」で、自分が書いていない（=信頼できない可能性がある）コードを安全に実行するための実行環境です。Next.js のサーバレス関数や Edge ではやりにくい「任意コード実行」を、より強い隔離で扱えます。

代表的な使い道

1) AIエージェント／LLMが生成したコードの実行

LLMが提案したスクリプト、データ加工コード、簡易ツールをその場で走らせる
“Computer-use agent”（ブラウザ操作・デスクトップ操作系）のバックエンド実行環境にする
→ 生成コードは危険になり得るので、アプリ本体から切り離した microVM で実行するのが定石です。

2) ユーザー提供のスクリプト実行（カスタムロジック）

例：SaaSで「ユーザーが書いた変換ルール」「Webhook 変換」「独自フィルタ」などを実行
例：ノーコード/ローコード製品の「式」「関数」「プラグイン」を実行
→ 自社サーバ上で直接動かすと侵害リスクが高いため、Sandbox で隔離実行。

3) セキュアなコード実行API（“Run code”機能）

オンラインIDE、教育サービス、採点システム（ジャッジ）、チュートリアルの実行環境
“ユーザーが貼り付けたコードを実行して結果を返す”系機能
→ 短命VMで毎回リセットできるので、汚染や持ち越しを抑えやすい。

4) 変換・ビルド・解析などの「重い/危険な」バッチ処理

ドキュメント変換（pandoc等）、画像/動画変換、PDF処理、スクレイピングの前処理
依存パッケージを OS レベルで入れたい処理（Amazon Linux上で dnf が使える）
→ サーバレス関数より自由度が高く、プロセス分離も強い。

5) 不審ファイルの動的解析（マルウェア“研究”寄り）

添付ファイルやスクリプトを開いて挙動を見る、IOC抽出など
※用途としては可能性がありますが、実運用はルール設計（ネットワーク制限/ログ/保存）を慎重に。

使うメリット（何が嬉しいか）

強い隔離：microVM（Firecracker）でプロセスだけの分離より堅牢
短命・使い捨て：実行ごとに環境を捨てられる
スケール：大量の実行を想定（AIワークロード向き）
課金が“動いている時間”中心（Active CPU）で、I/O待ちが多い処理に有利なケースがある
観測性：ログ配信や管理画面での確認ができる

どんな時に「Sandboxを使うべき」？

実行するコードが ユーザー生成／AI生成／外部提供 で、完全には信頼できない
Next.js サーバレス関数に入れるには 危険・権限が強すぎる・依存が重い
“コード実行”機能をプロダクトに組み込みたい

逆に、Sandboxじゃなくていい場合

自分が管理するアプリコードのみを実行する（通常のServerless/Edgeで十分）
長時間常駐プロセスや状態を持つサーバが必要（別アーキテクチャが向く）

もし「具体的にどんなプロダクトで使いたいか（例：ユーザースクリプト、AIエージェント、オンラインIDEなど）」を教えてくれれば、Sandboxでの構成例（API設計、権限制御、ログ/保存、コスト見積もりの考え方）まで絞って提案できます。

いまいちイメージ湧かないんですけど。今までのソリューションや手段とは何が違うの？大量の実行を想定（AIワークロード向き）とあるけど、そんなシチュなんてあるの？

Vercel Sandbox を「何が新しいのか」「どんな大量実行があるのか」が腹落ちする形で整理します。ポイントは “任意コード実行”を、サーバレス関数より強い隔離（microVM）で、しかも大量に回せるように製品化したもの です。

1) まず何が違うの？（従来手段との比較）

A. Next.js / Serverless Functions（Node実行）との違い

Serverless/Edge は基本的に「自社が書いたコード」を安全に運用するためのもので、ユーザーやAIが生成した“怪しいコード”を走らせる用途は想定が弱いです。

隔離の強さ
- Serverless: 同一ランタイム/同一OS上での分離（コンテナ/プロセス中心）＋制限はあるが「任意コード実行」を前提にしていない
- Sandbox: Firecracker microVM（より硬い境界）で “このVMの中で好きに実行していい” を前提に設計
OSレベル依存
- Serverless: OSパッケージ入れる、特殊ツール動かす、権限必要…がやりづらい
- Sandbox: Amazon Linux 上で dnf / sudo が使える。変換・解析ツール類を入れやすい
“攻撃される前提”の作り
- Serverless: もちろんセキュアだが、プロダクト要件として「不正コードを大量に実行」する設計はしにくい
- Sandbox: まさにそこを狙っている

結論：「自社コード」なら Serverless、「他人/AIのコード」なら Sandbox が分かりやすい。

B. Docker（自前K8s/ECS）でのサンドボックスと何が違う？

「コンテナで隔離して実行」は昔からある王道です。違いは 運用と隔離の“前提”。

運用コスト
- 自前: クラスタ運用、スケーリング、ノード管理、脆弱性対応、監視、キュー設計…全部自分
- Sandbox: そのへんを Vercelがマネージドで提供（SDK/CLIで起動→実行→破棄）
隔離
- Docker: 強いが、根本はカーネル共有（設定次第）
- microVM: VM境界に寄る（より強い隔離を狙いやすい）
短命・使い捨ての標準化
- 自前でも可能だが、プラットフォーム設計が必要
- Sandboxは短命実行が標準

結論：Dockerで作れるが、“任意コード実行基盤”を自前で作る面倒を製品として肩代わりしている。

C. Replit / Code Runner 系の外部サービスと何が違う？

それらは「IDE/開発体験込み」のサービスが多い
Vercel Sandbox は **自分のプロダクトの一部として埋め込む“実行エンジン”**に寄っている（Vercelの認証/観測/プロジェクトに統合）

2) 「大量の実行」ってどんなシチュエーション？

「毎秒数千のコード実行」みたいな極端な話だけじゃないです。AI時代だと **“小さい実行が大量に発生する”**が普通に起きます。

シチュ1：AIエージェントが“試行錯誤”で何十回も走らせる

例：あなたのアプリに「AIにCSV整理を頼む」機能があるとします。

AIが変換スクリプトを書く
実行して失敗（型違い、文字コード、列名揺れ）
修正して再実行
さらに追加要件で再実行…

ユーザー1人の1回の操作が、裏で 10〜50回の実行になることがあります。
これが 1000ユーザー / 日になると、数万実行/日は現実的です。

シチュ2：Tool use（関数呼び出し）で“細かいタスクを分割”する

エージェントは「一発で完成」よりも、次のように分割します。

「このリポジトリ読んで」→解析実行
「テスト走らせて」→実行
「Lint直して」→実行
「依存更新して」→実行

1つの依頼が 複数コマンド実行に分解されるので、実行回数が増えがちです。

シチュ3：ユーザースクリプト機能（SaaSの拡張）を提供している

例：

「受信WebhookをユーザーのJSで整形」
「独自のルールでデータ変換」
「ワークフローのカスタムステップ」

こういうのは、ユーザーが増えるほど イベント数＝実行数で増えます。
さらに「ユーザーコードは信頼できない」ので Sandbox が刺さる。

シチュ4：オンラインIDE/教材/採点（ジャッジ）

1クラスで数百人が、課題提出のたびに何回も実行 → 短時間にバーストします。
サンドボックスは短命実行を捌くのに向いています。

3) 何が嬉しいのかを一言で言うと

“他人/AIのコードを実行する機能”を、プロダクション品質で作れる
しかも 自前で実行基盤（K8s、ジョブキュー、隔離、監視、課金最適化）を持たなくていい

4) 具体イメージ（超ミニ例）

あなたの Next.js アプリで「ユーザーが貼ったJSを実行して結果を返す」機能を作るとします。

以前：
- 自前で実行用ワーカー基盤を作る / 外部サービスに投げる / 無理やりServerlessでやって危険と戦う
Sandbox：
- API で Sandbox を起動 → node script.js → 出力回収 → Sandbox破棄
- しかも microVM で隔離

もし「今イメージできない」の原因が、あなたの作っているものに“他人のコードを実行する要件がない”からなら、それが正常です。
逆に、次のどれかがあるなら刺さりやすいです：

AIにコードを書かせて実行したい（データ加工、repo操作、テスト実行）
ユーザーがスクリプト/式/プラグインを書ける機能を入れたい
OSツール（変換・解析）を安全に動かしたい

あなたが作っているプロダクト（または作りたい機能）を1〜2行で教えてください。「Sandbox が必要な場面か」「代替（ServerlessやQueue+Worker）の方がいいか」を、その前提で具体構成に落とします。

sandboxを使う時は冪等性を確保するべきですよね？毎回一から vm をつくって、必要な環境をセットアップして、コードを実行して、をできるようにする。基本的にその理解で合っていて、Vercel Sandbox を「短命・使い捨ての実行環境」として使うなら 冪等性（同じ入力→同じ結果、途中で落ちても再実行できる）を前提に設計するのがほぼ必須です。理由は「VMがいつでも捨てられる/作り直される」ことが価値であり、そこに依存すると運用が壊れるからです。

ただし、冪等性を“Sandboxの中で全部完結”させるというより、外側（あなたのアプリ側）でジョブを冪等に管理し、Sandboxは純粋な実行器にするのがコツです。

1) まず前提：Sandboxは「ステートレス実行器」とみなす

典型フローはおっしゃる通りで、

Sandbox作成
環境セットアップ（依存導入・ファイル配置）
コード実行
結果回収
Sandbox破棄

このとき Sandbox内の状態は信用しない / 再利用を前提にしない のが基本です（キャッシュを置いて高速化、は“最適化”として後から）。

2) 冪等性が必要になる具体ポイント

(A) リトライが普通に起きる

ネットワーク一時障害
タイムアウト
実行中にプロセスが落ちる
Sandbox自体の終了（TTL）

→ 「同じジョブをもう一回投げる」が避けられないので、二重実行されても壊れない設計が必要。

(B) “副作用”があると壊れる

例：

外部DBに INSERT を2回して重複
Stripe 等の外部APIを2回叩いて二重課金
S3に同名で上書きして取り違え

→ Sandboxの中で副作用を起こすなら、必ず冪等化が必要。

3) 具体的な設計パターン（おすすめ）

パターン1：外側で「ジョブID」を発行し、結果を1回だけ確定する（王道）

リクエスト受付時に jobId を発行（UUIDなど）
入力（コード・データ・依存情報）を jobId に紐づけて保存
Sandbox実行は「jobIdの入力を取りに行って、出力を jobId で返す」だけ
DB側は jobId をユニークにして 二重コミットを防ぐ（UPSERT / unique制約）

これで、Sandboxが何回走っても最終結果がブレにくい。

パターン2：外部API呼び出しは“Sandboxの外”に寄せる

Sandbox内では計算・変換・解析だけ
決済、メール送信、DB更新などの副作用はアプリサーバ側で「1回だけ」実行

これができると冪等性が一気に簡単になります。

パターン3：どうしても外部API叩くならIdempotency Keyを使う

StripeのIdempotency-Keyのように、外部が冪等キー対応しているなら必ず使う。対応してないAPIなら、あなた側で「このjobIdでは既に呼んだ」記録を持つ。

4) セットアップを毎回やるのは正しい？（はい。ただ最適化は可能）

毎回クリーンに作ってセットアップするのは“正”です。ただ、セットアップが重い場合は次を検討します。

入力を固定化：OS依存のインストールを減らす（可能ならnpm/pip中心に）
セットアップスクリプトも冪等に：dnf install -y ... を何度走らせてもOK、みたいに
成果物キャッシュは外部化：Sandbox内に残すのではなく、オブジェクトストレージ等に置く（ただしキャッシュヒットは“あったら使う”程度）

Vercel Sandbox自体に「常に同じVMを温存して使い回す」発想を強く持つと、結局不安定になります。

5) 実装チェックリスト（最低限）

jobId（冪等キー）を全リクエストに付与
入力（コード/依存/データ）を jobId で固定し、途中で内容が変わらないようにする
出力の確定は jobId のユニーク制約やトランザクションで“1回だけ”
リトライ戦略（タイムアウト/再実行回数/指数バックオフ）
Sandbox実行は「副作用最小」、副作用が必要なら冪等キー

もし「何をSandbox内でやって、何を外に出すべきか」を具体に引きたいので、想定ユースケース（例：ユーザースクリプト実行、AIが生成したPythonでETL、リポジトリに対するテスト実行など）を教えてください。副作用ポイントごとに冪等化の設計を落とし込めます。

vercel sandbox を使うときの具体的なフローは？ API で vm 起動命令と実行させたいコードを送る？

典型は「APIで“VMに入ってコマンド叩く”」というより、あなたのアプリ（Next.js / Backend）から Vercel Sandbox SDK/CLI を使って microVM を作り、VM内でコマンドを実行して、結果（stdout/stderr/成果物）を回収して捨てる、という流れです。
（＝HTTPで“コード文字列”を投げて勝手に実行してくれる単体サービス、というより「隔離実行環境をAPIで操作する」イメージ）

以下、実運用でよくある具体フローを2パターンで。

パターンA：同期実行（短い処理向け・リクエスト内で完結）

クライアント → あなたのAPIに実行依頼（コード/入力/依存情報など）
あなたのAPIが Sandbox.create() でSandbox作成
必要ファイルをSandboxに配置（コード、package.json、入力データなど）
sandbox.runCommand() で実行（node/python、任意コマンド）
stdout/stderr/exit code を取得
必要なら成果物ファイルを取り出す
sandbox.stop() で破棄
APIレスポンスとして結果を返す

向いてるもの:

数秒〜数十秒で終わる変換
“1回走らせて結果返す”系

パターンB：非同期実行（現実はこっちが多い：長い/失敗する/リトライする）

クライアント → あなたのAPIに依頼
APIは jobId を発行して「受け付けた」だけ返す（202）
Queue/Workflow/ジョブワーカーが jobId を拾う
ワーカーがSandboxを作成
Sandbox内でセットアップ → 実行
結果をDB/オブジェクトストレージへ保存（jobIdで紐付け、冪等に）
Sandbox破棄
クライアントは jobId でポーリング、またはWebhook/SSEで完了通知

向いてるもの:

AIエージェントの試行錯誤、複数ステップ
タイムアウトしがちな処理、リトライしたい処理
成果物（zip、画像、ログ）が大きい

「APIでVM起動命令とコードを送る？」への答え

概ね Yes ですが、よくある設計はこう整理すると安全で運用しやすいです。

クライアント → あなたのAPI:
「この jobId に対して、この入力で、この“実行内容”をやって」という“依頼”を送る
あなたのAPI/ワーカー → Vercel Sandbox（SDK）:
VM起動 / ファイル配置 / コマンド実行を行う

つまり「クライアントがVercel Sandboxへ直接コードを投げる」より、必ずあなたのサーバ側が仲介して

認可
リソース制限（時間、CPU、メモリ、許可コマンド）
入力の固定（冪等性）
ログ/成果物の取り扱いを統制する形が一般的です。

最小の疑似コード（イメージ）

import { Sandbox } from "@vercel/sandbox";

export async function runUserCode({ files, cmd, args }) {
  const sb = await Sandbox.create();

  try {
    // 例: ファイル配置（APIは実際のSDKの形に合わせて）
    // await sb.writeFile("/work/index.js", files["index.js"]);

    const result = await sb.runCommand({ cmd, args });
    // result: exitCode, stdout, stderr ... のような情報を回収

    return result;
  } finally {
    await sb.stop();
  }
}

実際に設計するときに決めるべきこと（重要）

コード/入力はどこに置く？
文字列で送るのか、ストレージに置いてSandboxが取得するのか
成果物はどう回収する？（stdoutだけ？ファイルも？）
副作用（DB更新/外部API）はSandbox内で許す？（許すなら冪等キー必須）
タイムアウト・リトライ（非同期ジョブが推奨になりがち）

あなたの想定はどれに近いですか？

ユーザーが貼ったJS/Pythonを1回実行して結果を返す（同期）
AIが何度も試しながら実行する（非同期・複数回）
OSツール込みで変換（pandoc/ffmpeg等）

それで、具体的な「ファイルの渡し方」「結果の取り回し」「冪等化」をその前提でフロー図レベルまで落とします。

え？ Sandbox.create() や runCommand() はローカルで microVM 立ち上げるってこと？違うよね？

違います。Sandbox.create() や runCommand() は ローカルPC上で microVM を起動するものではなく、Vercel のインフラ上（リモート）で sandbox（Firecracker microVM）を作って、その中でコマンドを実行するための SDK 呼び出しです。

何がどこで動くか（整理）

あなたのコード（Next.js API / Worker / ローカルCLI）

ここで Sandbox.create() を呼ぶ
実体は「Vercel Sandbox の管理APIに対して、sandbox作成をリクエストする」イメージ
返ってくるのは “リモートの sandbox へのハンドル（ID/接続情報）”

sandbox（microVM）

Vercel 側の環境で起動する
runCommand() は「そのリモートVMの中で cmd を実行して、stdout/stderr/exitCode を返して」という命令

つまり SDK は “VMをローカルで動かすライブラリ” ではなく、リモート実行環境を操作するクライアントです。

じゃあ `npx sandbox create --connect` は？

これも同じで、CLIが リモートに sandbox を作って、それに **ローカル端末から接続（ログ閲覧・操作）**しているだけです。Docker Desktop みたいにローカルでVMが立つわけではありません。

イメージ（超短く）

Sandbox.create() = 「VercelにVM作って」と頼む
sandbox.runCommand(...) = 「そのVMの中でこのコマンド実行して」
sandbox.stop() = 「VM捨てて」

補足：どこから呼ぶのが一般的？

開発中は ローカルのNodeスクリプトから呼んでも “VMはリモート” です（ただし認証済みである必要あり）
本番は あなたのバックエンド/ジョブワーカーから呼んで、ユーザーからの依頼を仲介するのが一般的です（直叩きさせない）

もし「ローカルから呼ぶ場合、認証は何が必要？」「本番で Next.js の Route Handler から呼ぶのはアリ？」みたいな運用面の前提を教えてくれたら、その形での推奨構成を具体化します。

stakiran/gist.md