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

# 로컬샌드박스

**추가된 항목:** `@mastra/core@1.1.0`

로컬 시스템에서 명령을 실행합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[WorkspaceSandbox interface](https://mastra.zisheng.pro/ko/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: `자동 생성`)

**workingDirectory** (`string`): 명령 실행 디렉터리입니다. seatbelt 프로필과 격리하기 위해 기본값은 process.cwd()의 .sandbox/입니다. (Default: `process.cwd()/.sandbox/`)

**env** (`NodeJS.ProcessEnv`): 설정할 환경 변수입니다. 재정의하지 않는 한 PATH가 기본적으로 포함됩니다.

**timeout** (`number`): 작업의 기본 제한 시간(밀리초) (Default: `30000`)

**isolation** (`'none' | 'seatbelt' | 'bwrap'`): 네이티브 OS 샌드박싱 백엔드입니다. macOS에서는 'seatbelt', Linux에서는 'bwrap'을 사용합니다. (Default: `'none'`)

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): getInstructions()에서 반환되는 기본 지침을 재정의하는 사용자 지정 지침입니다. 완전히 대체하려면 문자열을 전달하고, 요청별 사용자 지정을 위해 현재 requestContext에 액세스하면서 확장하려면 함수를 전달합니다.

**nativeSandbox** (`NativeSandboxConfig`): 네이티브 샌드박싱 구성입니다(아래의 NativeSandboxConfig 참조).

## `NativeSandboxConfig`

네이티브 OS 샌드박싱의 구성 옵션입니다(`isolation: 'seatbelt'` 또는 `'bwrap'`과 함께 사용).

**allowNetwork** (`boolean`): 샌드박싱된 명령의 네트워크 액세스를 허용합니다. (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/ko/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 샌드박싱

`LocalSandbox`추가 보안을 위해 기본 OS 수준 샌드박싱을 지원합니다.

- **macOS**: 파일 시스템 및 네트워크 격리에 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
  },
})
```

격리가 활성화된 경우:

- 파일 쓰기는 작업공간 디렉토리(및 구성된 경로)로 제한됩니다.
- 파일 읽기는 어디에서나 허용됩니다(시스템 바이너리에 필요).
- 네트워크 액세스는 기본적으로 차단됩니다.
- 프로세스 격리를 통해 호스트 시스템에 영향을 주지 않음

### 샌드박스 프로필 위치

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
```

프로필 파일 이름은 작업 영역 경로 및 구성의 해시이므로 동일한 설정을 가진 샌드박스는 동일한 프로필을 공유하지만 다른 구성은 별도의 파일을 얻습니다. 이는 여러 샌드박스를 동시에 실행할 때 충돌을 방지합니다.

이러한 분리는 샌드박스 프로세스가 자체 보안 프로필을 읽거나 수정하는 것을 방지합니다. 프로필은 샌드박스가 시작될 때 생성되고 삭제될 때 정리됩니다.

## 관련된

- [SandboxProcessManager 참조](https://mastra.zisheng.pro/ko/reference/workspace/process-manager)
- [WorkspaceSandbox 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/sandbox)
- [작업공간 클래스](https://mastra.zisheng.pro/ko/reference/workspace/workspace-class)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)