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

# LocalSandbox

**追加バージョン：** `@mastra/core@1.1.0`

ローカルシステムでコマンドを実行します。インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)を参照してください。

## 使用方法

Workspace に `LocalSandbox` を追加して Agent に割り当てます。これにより Agent はタスクの一環としてシェルコマンドを実行できます。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
    env: {
      NODE_ENV: 'development',
    },
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})

// The agent now has the execute_command tool available
const response = await agent.generate('Run npm install')
```

### 自動起動の動作

`LocalSandbox` がまだ動作していない場合は、最初のコマンド実行時に自動起動します。最初のコマンドの遅延を避けるには、アプリケーションの起動時に `workspace.init()` を呼び出して Sandbox を明示的に起動することもできます。

## コンストラクターパラメーター

**id** (`string`): この Sandbox インスタンスの一意な識別子。 (Default: `Auto-generated`)

**workingDirectory** (`string`): コマンドを実行するディレクトリ。seatbelt プロファイルから分離するため、デフォルトは process.cwd() 内の .sandbox/ です。 (Default: `process.cwd()/.sandbox/`)

**env** (`NodeJS.ProcessEnv`): 設定する環境変数。上書きしない限り、デフォルトで PATH が含まれます。

**timeout** (`number`): 操作のデフォルトタイムアウト（ミリ秒）。 (Default: `30000`)

**isolation** (`'none' | 'seatbelt' | 'bwrap'`): OS ネイティブの Sandbox バックエンド。macOS では 'seatbelt'、Linux では 'bwrap' を使用します。 (Default: `'none'`)

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): getInstructions() が返すデフォルトの指示を上書きするカスタム指示。完全に置き換えるには文字列を、現在の requestContext を参照してリクエストごとにカスタマイズするには拡張関数を渡します。

**nativeSandbox** (`NativeSandboxConfig`): ネイティブ Sandbox の設定（後述の NativeSandboxConfig を参照）。

## `NativeSandboxConfig`

OS ネイティブの Sandbox 用設定オプション（`isolation: 'seatbelt'` または `'bwrap'` とともに使用）。

**allowNetwork** (`boolean`): Sandbox 化されたコマンドからのネットワークアクセスを許可するかどうか。 (Default: `false`)

**readOnlyPaths** (`string[]`): 読み取り専用アクセスを許可する追加パス（システムパスは常に読み取り可能）。

**readWritePaths** (`string[]`): Workspace ディレクトリの外部で読み書きを許可する追加パス。

**seatbeltProfilePath** (`string`): カスタム seatbelt プロファイルファイルへのパス（macOS のみ）。ユーザーが作成したファイルはそのまま使用されます。Mastra はマウントパスを追加しないため、マウントするすべてのパスをプロファイルで事前に許可する必要があります。ファイルが存在しない場合は、マウントパスを許可するデフォルトプロファイルが生成され、このパスへ書き込まれます。Mastra は生成したプロファイルに印を付けるため、以後の実行ではユーザー作成ファイルとして読み込まずに再生成します。生成済みプロファイルを編集して変更を維持するには、印となるコメントを削除してください。その後はユーザー作成ファイルとして扱われ、マウントパスは追加されません。

**bwrapArgs** (`string[]`): bwrap に渡す追加引数（Linux のみ）。

**allowSystemBinaries** (`boolean`): 標準のシステムバイナリパス（/bin、/usr/bin など）への読み取りアクセスを許可するかどうか。 (Default: `true`)

## プロパティ

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

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

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

**status** (`ProviderStatus`): 'starting' | 'running' | 'stopped' | 'error'

**workingDirectory** (`string`): 設定済みの作業ディレクトリ。

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

## パスの解決

### 相対パスと実行コンテキスト

`workingDirectory` に相対パスを使用すると、`process.cwd()` を基準に解決されます。Mastra プロジェクトでは、コードの実行方法によって cwd が変わります。

| コンテキスト         | 作業ディレクトリ               | `./workspace` の解決先              |
| -------------- | ---------------------- | ------------------------------- |
| `mastra dev`   | `./src/mastra/public/` | `./src/mastra/public/workspace` |
| `mastra start` | `./.mastra/output/`    | `./.mastra/output/workspace`    |
| スクリプトを直接実行     | コマンドを実行した場所            | その場所からの相対パス                     |

同じ相対パスが異なる場所へ解決されるため、混乱を招くことがあります。

### 推奨：絶対パスを使用する

すべての実行コンテキストでパスを統一するには、絶対パスを設定した環境変数を使用します。

```typescript
import { LocalSandbox } from '@mastra/core/workspace'

const sandbox = new LocalSandbox({
  workingDirectory: process.env.WORKSPACE_PATH!,
})
```

環境変数 `WORKSPACE_PATH` に `/home/user/my-project/workspace` などの絶対パスを設定します。コードの実行方法にかかわらず、コマンドを同じディレクトリから実行できます。

## バックグラウンドプロセス

`LocalSandbox` には、バックグラウンドプロセスを起動・管理するプロセスマネージャーが組み込まれています。プロセスは `child_process.spawn` を使用し、ローカルマシン上の子プロセスとして動作します。

```typescript
const sandbox = new LocalSandbox({ workingDirectory: './workspace' })
await sandbox.start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js')

// Read output, send stdin, kill
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
```

ネイティブ分離（`seatbelt` または `bwrap`）を有効にすると、起動したプロセスも同じ分離バックエンドでラップされます。

完全な API は、[`SandboxProcessManager` リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)を参照してください。

## 静的メソッド

### `detectIsolation()`

現在のプラットフォームで利用可能な最適の分離バックエンドを検出します。

```typescript
const detection = LocalSandbox.detectIsolation()
// { backend: 'seatbelt', available: true, message: 'Seatbelt available on macOS' }
```

## 環境の分離

デフォルトでは、`LocalSandbox` の環境に含まれるのは `PATH` だけです。これにより、コマンドを実行可能にしつつ、API キーやシークレットの意図しない公開を防ぎます。

```typescript
// Default: only PATH is available (commands work, secrets protected)
const secureSandbox = new LocalSandbox({
  workingDirectory: './workspace',
})

// Explicit: pass specific variables
const sandbox = new LocalSandbox({
  workingDirectory: './workspace',
  env: {
    NODE_ENV: 'development',
    API_URL: 'https://api.example.com',
  },
})

// Full access (use with caution)
const devSandbox = new LocalSandbox({
  workingDirectory: './workspace',
  env: process.env,
})
```

## OS ネイティブの Sandbox

`LocalSandbox` は、セキュリティを強化するため OS ネイティブの Sandbox に対応します。

- **macOS**：Filesystem とネットワークの分離に Seatbelt（`sandbox-exec`）を使用
- **Linux**：名前空間の分離に Bubblewrap（`bwrap`）を使用

```typescript
// Detect the best available backend for this platform
const detection = LocalSandbox.detectIsolation()
console.log(detection)
// { backend: 'seatbelt', available: true, message: '...' }

// Enable native sandboxing
const sandbox = new LocalSandbox({
  workingDirectory: './workspace',
  isolation: 'seatbelt', // or 'bwrap' on Linux
  nativeSandbox: {
    allowNetwork: false, // Block network access (default)
    readWritePaths: ['/tmp/extra'], // Additional writable paths
  },
})
```

分離を有効にすると、次の制限が適用されます。

- ファイルの書き込みは Workspace ディレクトリ（および設定済みパス）内に制限されます
- ファイルの読み取りはすべての場所で許可されます（システムバイナリに必要）
- ネットワークアクセスはデフォルトで遮断されます
- プロセス分離により、ホストシステムへの影響を防ぎます

### Sandbox プロファイルの場所

macOS で seatbelt 分離を使用すると、`LocalSandbox` は作業ディレクトリとは別に、`process.cwd()` 内の `.sandbox-profiles/` フォルダーへプロファイルファイルを生成します。

```text
project/
├── .sandbox/                      # Default working directory (sandboxed)
│   └── ... files created by sandbox
├── .sandbox-profiles/             # Seatbelt profiles (outside sandbox)
│   └── seatbelt-a1b2c3d4.sb       # Hash based on workspace + config
└── ... your project files
```

プロファイルのファイル名は Workspace のパスと設定から生成したハッシュです。同じ設定の Sandbox は同じプロファイルを共有し、設定が異なる場合は別のファイルを使用します。これにより、複数の Sandbox を同時実行する際の競合を防ぎます。

この分離により、Sandbox 化されたプロセスが自身のセキュリティプロファイルを読み取ったり変更したりするのを防ぎます。プロファイルは Sandbox の起動時に作成され、破棄時にクリーンアップされます。

## 関連項目

- [SandboxProcessManager リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)
- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [Workspace クラス](https://mastra.zisheng.pro/ja/reference/workspace/workspace-class)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)