PlatformSandbox
Mastra Platform 環境に Sandbox をプロビジョニングするクライアントです。各 PlatformSandbox インスタンスは1つのリモート Sandbox を所有します。start() でプロビジョニングし、executeCommand() でコマンドを実行し、destroy() で破棄します。リモート Sandbox を追加するには、インスタンスも追加します。設定済みテンプレートから派生させるには clone() を使用します（クローンを参照）。
Sandbox は、Python 3、Node 22、TypeScript、tsx、一般的なビルド Tool がインストール済みのレシピチェックポイントから起動します。固定の id を渡してチェックポイント復元を有効にすると、新しい Sandbox が以前の Filesystem から起動します。
関連 Provider：セルフホストの Railway Sandbox には RailwaySandbox、ローカル Sandbox には LocalSandbox を使用します。
インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。
インストールインストールへの直接リンク
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/platform-workspace
pnpm add @mastra/platform-workspace
yarn add @mastra/platform-workspace
bun add @mastra/platform-workspace
Platform の認証情報を設定します。アクセストークン、プロジェクト ID、環境 ID は環境変数を使用できるため、Mastra Platform へのデプロイではコンストラクターオプションを省略できます。
- .env ファイル
- コンストラクター
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
new PlatformSandbox({
accessToken: 'your-platform-access-token',
projectId: 'your-project-id',
environmentId: 'your-environment-id',
})
Mastra Platform へのデプロイでは、MASTRA_PLATFORM_ACCESS_TOKEN、MASTRA_PROJECT_ID、MASTRA_ENVIRONMENT_ID が自動挿入されるため、オプションなしでコンストラクターを呼び出せます。ローカル開発では、組織の設定ページにある API Tokens で取得した sk_ API トークンを MASTRA_PLATFORM_ACCESS_TOKEN に設定できます。
使用方法使用方法への直接リンク
Workspace に PlatformSandbox を追加して Agent に割り当てます。
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { PlatformSandbox } from '@mastra/platform-workspace'
const workspace = new Workspace({
sandbox: new PlatformSandbox({
// accessToken, projectId, environmentId all fall back to env vars
idleTimeoutMinutes: 30,
}),
})
const agent = new Agent({
id: 'code-agent',
name: 'Code Agent',
instructions: 'You are a coding assistant working in this workspace.',
model: 'anthropic/claude-sonnet-4-6',
workspace,
})
const response = await agent.generate(
'Print "Hello, world!" and show the current working directory.',
)
console.log(response.text)
プライベートネットワークプライベートネットワークへの直接リンク
networkIsolation を PRIVATE に設定すると、環境のプライベートネットワークに接続し、同じ Mastra Platform 環境で動作する他のサービスへアクセスできます。
const workspace = new Workspace({
sandbox: new PlatformSandbox({
networkIsolation: 'PRIVATE',
}),
})
デフォルトの ISOLATED モードでは、外向きインターネットアクセスのみが許可され、プライベートネットワークには接続できません。
実行中の Sandbox に再接続する実行中の Sandbox に再接続するへの直接リンク
新しい Sandbox を作成せず実行中の Sandbox へ再接続するには、既存の sandboxId を渡します。
const sandbox = new PlatformSandbox({
sandboxId: 'sbx_abc123',
})
await sandbox.start()
const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
sandboxId を設定した場合、Sandbox はすでに存在するため environmentId は不要です。
チェックポイント復元チェックポイント復元への直接リンク
コンストラクターの id（明示指定または自動生成）は、POST /sandbox の際に復元用の参考キーとして Platform へ送信されます。
- Platform が以前のセッションの
idを認識すると、新しい Sandbox はベースレシピではなく、以前の Sandbox の Filesystem における最新チェックポイントから起動します。 idが認識されない場合、Platform はベースレシピから新しい Sandbox を起動します。自動生成 ID は一致しないため、idを省略するとチェックポイント復元は無効になります。
セッション間または destroy() / start() サイクル間で Sandbox の Filesystem を維持するには、固定の id を渡します。
const sandbox = new PlatformSandbox({
id: `project-${projectId}`,
})
await sandbox.start() // Boots from the most recent checkpoint for this id, or fresh if unknown
チェックポイント復元は、sandboxId による再接続よりも粒度が粗くなります。sandboxId による再接続では、該当する実行中の Sandbox とそのプロセスへ再び接続します。チェックポイント復元では新しい Sandbox を作成し、同じ id を持つ以前の Sandbox について Platform が取得した最新チェックポイントから Filesystem を復元します。実行中のプロセスや、最後のチェックポイント以降の Filesystem への書き込みは復元されません。
各 id は1つの独立した Filesystem に対応します。無関係な Sandbox 間で同じ id を再利用すると、それぞれが互いのチェックポイントから起動します。
複数の Sandbox 向けにクローンする複数の Sandbox 向けにクローンするへの直接リンク
clone() は、認証情報とデフォルト値（アクセストークン、プロジェクト、環境、ネットワーク分離、タイムアウト、指示、env、アイドルタイムアウト）を継承しつつ、インスタンスごとの上書きを適用した独立した同階層の PlatformSandbox を返します。返された Sandbox は未起動で、自身の start() でプロビジョニングされるため、clone() は I/O を行いません。
const template = new PlatformSandbox({
networkIsolation: 'PRIVATE',
idleTimeoutMinutes: 30,
})
const perProject = template.clone({ id: `project-${projectId}` })
await perProject.start()
clone() とクローンごとの固定 id を組み合わせると、各クローンで個別にチェックポイント復元を有効にできます。
コマンドを実行するコマンドを実行するへの直接リンク
executeCommand はリモート Sandbox でコマンドを実行し、その出力を返します。引数を安全にシェルクォートするには args を渡します。
const result = await sandbox.executeCommand('python', ['analyze.py'], {
timeout: 30_000,
cwd: '/workspace',
env: { INPUT: 'repo' },
})
console.log(result.stdout)
console.log(result.exitCode)
command 引数はシェル文字列で、リモートシェルへそのまま連結されます。パイプ、リダイレクト、チェーン（ls -la | grep foo）を使用できますが、信頼できない入力は args（安全にクォートされます）で渡すか、呼び出し元でシェルクォートする必要があります。信頼できない値を command に渡すと、Sandbox 上で任意のシェルコマンドを実行される可能性があります。
コンストラクターパラメーターコンストラクターパラメーターへの直接リンク
accessToken?:
projectId?:
environmentId?:
sandboxId?:
idleTimeoutMinutes?:
networkIsolation?:
env?:
timeout?:
instructions?:
id?:
fetch?:
プロパティプロパティへの直接リンク
id:
name:
provider:
status:
processes:
メソッドメソッドへの直接リンク
start:
destroy:
stop:
executeCommand:
clone:
getInfo:
getInstructions:
エラーエラーへの直接リンク
Platform API の失敗では PlatformApiError が発生します。構造化された { error: { message, type } } レスポンスは、.code（機械可読な種別）と .proxyMessage（人が読める文字列）へ解析されます。未加工のレスポンス本文は .body で引き続き参照できます。
import { PlatformApiError } from '@mastra/platform-workspace'
try {
await sandbox.executeCommand('cat', ['/missing.txt'])
} catch (err) {
if (err instanceof PlatformApiError) {
if (err.code === 'not_found') {
// handle missing resource
} else if (err.code === 'authentication_error') {
// refresh token
}
console.error(err.status, err.code, err.proxyMessage)
}
}
レスポンス本文が JSON でない場合（ロードバランサーからの HTML 502 など）、code と proxyMessage は undefined です。
executeCommand は直接実行データプレーン（Railway tcp-proxy への WebSocket）上で動作し、復旧不能な失敗時には2種類の型付き Sandbox エラーをスローすることもあります。
import { SandboxDestroyedError, SandboxExecTransportError } from '@mastra/platform-workspace'
try {
await sandbox.executeCommand('pytest')
} catch (err) {
if (err instanceof SandboxDestroyedError) {
// /exec-lease returned 410; the sandbox has been destroyed.
// The cached sandbox id and lease have already been cleared,
// so reusing the instance will reprovision on the next call.
} else if (err instanceof SandboxExecTransportError) {
// Both the initial WebSocket attempt and the built-in retry
// closed without an exit frame against a live sandbox.
console.error(err.closeCode, err.closeReason, err.wsEndpoint)
}
}
SandboxExecTransportError には診断フィールド（opened、closeCode、closeReason、wsEndpoint、sandboxId、command、attempts）が含まれ、運用担当者は Railway データプレーンの障害とコマンドの失敗を区別できます。