LocalSandbox
追加バージョン： @mastra/core@1.1.0
ローカルシステムでコマンドを実行します。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。
使用方法使用方法への直接リンク
Workspace に LocalSandbox を追加して Agent に割り当てます。これにより Agent はタスクの一環としてシェルコマンドを実行できます。
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?:
workingDirectory?:
env?:
timeout?:
isolation?:
instructions?:
nativeSandbox?:
NativeSandboxConfignativesandboxconfigへの直接リンク
OS ネイティブの Sandbox 用設定オプション（isolation: 'seatbelt' または 'bwrap' とともに使用）。
allowNetwork?:
readOnlyPaths?:
readWritePaths?:
seatbeltProfilePath?:
bwrapArgs?:
allowSystemBinaries?:
プロパティプロパティへの直接リンク
id:
name:
provider:
status:
workingDirectory:
processes:
パスの解決パスの解決への直接リンク
相対パスと実行コンテキスト相対パスと実行コンテキストへの直接リンク
workingDirectory に相対パスを使用すると、process.cwd() を基準に解決されます。Mastra プロジェクトでは、コードの実行方法によって cwd が変わります。
| コンテキスト | 作業ディレクトリ | ./workspace の解決先 |
|---|---|---|
mastra dev | ./src/mastra/public/ | ./src/mastra/public/workspace |
mastra start | ./.mastra/output/ | ./.mastra/output/workspace |
| スクリプトを直接実行 | コマンドを実行した場所 | その場所からの相対パス |
同じ相対パスが異なる場所へ解決されるため、混乱を招くことがあります。
推奨：絶対パスを使用する推奨：絶対パスを使用するへの直接リンク
すべての実行コンテキストでパスを統一するには、絶対パスを設定した環境変数を使用します。
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 を使用し、ローカルマシン上の子プロセスとして動作します。
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 リファレンスを参照してください。
静的メソッド静的メソッドへの直接リンク
detectIsolation()detectisolationへの直接リンク
現在のプラットフォームで利用可能な最適の分離バックエンドを検出します。
const detection = LocalSandbox.detectIsolation()
// { backend: 'seatbelt', available: true, message: 'Seatbelt available on macOS' }
環境の分離環境の分離への直接リンク
デフォルトでは、LocalSandbox の環境に含まれるのは PATH だけです。これにより、コマンドを実行可能にしつつ、API キーやシークレットの意図しない公開を防ぎます。
// 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 ネイティブの SandboxOS ネイティブの Sandboxへの直接リンク
LocalSandbox は、セキュリティを強化するため OS ネイティブの Sandbox に対応します。
- macOS：Filesystem とネットワークの分離に Seatbelt（
sandbox-exec）を使用 - Linux：名前空間の分離に Bubblewrap（
bwrap）を使用
// 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 プロファイルの場所Sandbox プロファイルの場所への直接リンク
macOS で seatbelt 分離を使用すると、LocalSandbox は作業ディレクトリとは別に、process.cwd() 内の .sandbox-profiles/ フォルダーへプロファイルファイルを生成します。
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 の起動時に作成され、破棄時にクリーンアップされます。