> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# PlatformSandbox

Mastra Platform 環境に Sandbox をプロビジョニングするクライアントです。各 `PlatformSandbox` インスタンスは1つのリモート Sandbox を所有します。`start()` でプロビジョニングし、`executeCommand()` でコマンドを実行し、`destroy()` で破棄します。リモート Sandbox を追加するには、インスタンスも追加します。設定済みテンプレートから派生させるには `clone()` を使用します（[クローン](#cloning-for-a-fleet-of-sandboxes)を参照）。

Sandbox は、Python 3、Node 22、TypeScript、tsx、一般的なビルド Tool がインストール済みのレシピチェックポイントから起動します。固定の `id` を渡して[チェックポイント復元](#checkpoint-recovery)を有効にすると、新しい Sandbox が以前の Filesystem から起動します。

関連 Provider：セルフホストの Railway Sandbox には [`RailwaySandbox`](https://mastra.zisheng.pro/ja/reference/workspace/railway-sandbox)、ローカル Sandbox には [`LocalSandbox`](https://mastra.zisheng.pro/ja/reference/workspace/local-sandbox) を使用します。

> **情報:** インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)を参照してください。

## インストール

**npm**:

```bash
npm install @mastra/platform-workspace
```

**pnpm**:

```bash
pnpm add @mastra/platform-workspace
```

**Yarn**:

```bash
yarn add @mastra/platform-workspace
```

**Bun**:

```bash
bun add @mastra/platform-workspace
```

Platform の認証情報を設定します。アクセストークン、プロジェクト ID、環境 ID は環境変数を使用できるため、Mastra Platform へのデプロイではコンストラクターオプションを省略できます。

**.env ファイル**:

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
```

**コンストラクター**:

```typescript
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 に割り当てます。

```typescript
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 環境で動作する他のサービスへアクセスできます。

```typescript
const workspace = new Workspace({
  sandbox: new PlatformSandbox({
    networkIsolation: 'PRIVATE',
  }),
})
```

デフォルトの `ISOLATED` モードでは、外向きインターネットアクセスのみが許可され、プライベートネットワークには接続できません。

### 実行中の Sandbox に再接続する

新しい Sandbox を作成せず実行中の Sandbox へ再接続するには、既存の `sandboxId` を渡します。

```typescript
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` を渡します。

```typescript
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 向けにクローンする

`clone()` は、認証情報とデフォルト値（アクセストークン、プロジェクト、環境、ネットワーク分離、タイムアウト、指示、env、アイドルタイムアウト）を継承しつつ、インスタンスごとの上書きを適用した独立した同階層の `PlatformSandbox` を返します。返された Sandbox は未起動で、自身の `start()` でプロビジョニングされるため、`clone()` は I/O を行いません。

```typescript
const template = new PlatformSandbox({
  networkIsolation: 'PRIVATE',
  idleTimeoutMinutes: 30,
})

const perProject = template.clone({ id: `project-${projectId}` })
await perProject.start()
```

`clone()` とクローンごとの固定 `id` を組み合わせると、各クローンで個別に[チェックポイント復元](#checkpoint-recovery)を有効にできます。

### コマンドを実行する

`executeCommand` はリモート Sandbox でコマンドを実行し、その出力を返します。引数を安全にシェルクォートするには `args` を渡します。

```typescript
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** (`string`): Platform のアクセストークン。未指定の場合は環境変数 MASTRA\_PLATFORM\_ACCESS\_TOKEN を使用します。

**projectId** (`string`): Platform のプロジェクト ID。未指定の場合は環境変数 MASTRA\_PROJECT\_ID を使用します。

**environmentId** (`string`): Sandbox が属する Platform 環境 ID。未指定の場合は環境変数 MASTRA\_ENVIRONMENT\_ID を使用します。sandboxId を渡さない場合は必須です。

**sandboxId** (`string`): 新しい Sandbox を作成せず再接続する既存の Sandbox ID。設定した場合、environmentId は不要です。

**idleTimeoutMinutes** (`number`): アクティビティがない状態で Platform が破棄するまで Sandbox を維持する時間。

**networkIsolation** (`'ISOLATED' | 'PRIVATE'`): ネットワークモード。'ISOLATED'（デフォルト）は外向きインターネットアクセスのみを許可します。'PRIVATE' は Platform 環境のプライベートネットワークに接続します。

**env** (`Record<string, string>`): 作成時に Sandbox へ組み込む環境変数。コマンドごとの環境変数を executeCommand に渡すこともできます。

**timeout** (`number`): デフォルトのコマンド実行タイムアウト（ミリ秒）。呼び出しごとに ExecuteCommandOptions.timeout で上書きできます。

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): getInstructions() が返すカスタム指示。文字列はデフォルトを完全に置き換えます。関数はデフォルトを受け取り、リクエストごとに拡張またはカスタマイズできます。

**id** (`string`): この Sandbox インスタンスの一意な識別子。復元用の参考キーとして Platform へ送信されます。Platform が以前の Sandbox の id として認識すると、新しい Sandbox はベースレシピではなく、その Sandbox の最新チェックポイントから起動します。未知の id の場合は新しい Sandbox を作成します。省略すると自動生成され、チェックポイント復元は無効になります。 (Default: `Auto-generated`)

**fetch** (`typeof fetch`): カスタム fetch 実装。主にテストで使用します。

## プロパティ

**id** (`string`): Sandbox インスタンスの識別子。

**name** (`string`): Provider 名（'PlatformSandbox'）。

**provider** (`string`): Provider 識別子（'platform'）。

**status** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'.

**processes** (`PlatformProcessManager`): バックグラウンドプロセスマネージャー。SandboxProcessManager リファレンスを参照してください。

## メソッド

**start** (`() => Promise<void>`): リモート Sandbox をプロビジョニングします。コンストラクターへ sandboxId を渡した場合は再接続します。Sandbox の実行中は冪等です。再接続先が破棄済みの場合は、新しくプロビジョニングします。

**destroy** (`() => Promise<void>`): リモート Sandbox を破棄し、キャッシュ済みの実行リースを消去します。以後の start() では新しい Sandbox をプロビジョニングします（固定の id が設定されている場合はチェックポイントから復元）。

**stop** (`() => Promise<void>`): destroy() の別名。

**executeCommand** (`(command: string, args?: string[], options?: ExecuteCommandOptions) => Promise<CommandResult>`): リモート Sandbox でコマンドを実行し、stdout、stderr、exitCode、executionTimeMs を返します。command はシェル文字列で、args は安全にシェルクォートされます。

**clone** (`(options?: SandboxCloneOptions) => PlatformSandbox`): 認証情報とデフォルト値を継承しつつ、インスタンスごとの値（id、sandboxId、env、idleTimeoutMinutes）を上書きした未起動の同階層 PlatformSandbox を構築します。I/O は行いません。1つの設定済みテンプレートから複数の独立した Sandbox を構築する際に使用します。

**getInfo** (`() => Promise<SandboxInfo>`): Sandbox の Platform ID、Provider、ステータス、createdAt、メタデータ（sandboxId、providerResourceId、platformStatus）を返します。

**getInstructions** (`(opts?: { requestContext?: RequestContext }) => string`): Workspace が Tool の説明に表示する Sandbox の指示を返します。コンストラクターの instructions オプションを適用し、未指定の場合は、実行中のリモート Sandbox ID を含む Platform のデフォルト指示を返します。

## エラー

Platform API の失敗では `PlatformApiError` が発生します。構造化された `{ error: { message, type } }` レスポンスは、`.code`（機械可読な種別）と `.proxyMessage`（人が読める文字列）へ解析されます。未加工のレスポンス本文は `.body` で引き続き参照できます。

```typescript
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 エラーをスローすることもあります。

```typescript
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 データプレーンの障害とコマンドの失敗を区別できます。

## 関連項目

- [PlatformFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/platform-filesystem)
- [RailwaySandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/railway-sandbox)
- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [SandboxProcessManager リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)