로컬샌드박스
추가된 항목: @mastra/core@1.1.0
로컬 시스템에서 명령을 실행합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceSandbox interface.
용법용법에 대한 직접 링크
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 샌드박싱의 구성 옵션입니다(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 샌드박싱네이티브 OS 샌드박싱에 대한 직접 링크
LocalSandbox추가 보안을 위해 기본 OS 수준 샌드박싱을 지원합니다.
- macOS: 파일 시스템 및 네트워크 격리에 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
},
})
격리가 활성화된 경우:
- 파일 쓰기는 작업공간 디렉토리(및 구성된 경로)로 제한됩니다.
- 파일 읽기는 어디에서나 허용됩니다(시스템 바이너리에 필요).
- 네트워크 액세스는 기본적으로 차단됩니다.
- 프로세스 격리를 통해 호스트 시스템에 영향을 주지 않음
샌드박스 프로필 위치샌드박스 프로필 위치에 대한 직접 링크
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
프로필 파일 이름은 작업 영역 경로 및 구성의 해시이므로 동일한 설정을 가진 샌드박스는 동일한 프로필을 공유하지만 다른 구성은 별도의 파일을 얻습니다. 이는 여러 샌드박스를 동시에 실행할 때 충돌을 방지합니다.
이러한 분리는 샌드박스 프로세스가 자체 보안 프로필을 읽거나 수정하는 것을 방지합니다. 프로필은 샌드박스가 시작될 때 생성되고 삭제될 때 정리됩니다.