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

# 모래 상자

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

샌드박스 공급자는 Agent에 셸 명령을 실행할 수 있는 기능을 제공합니다. 작업 영역에서 샌드박스를 구성하면 Agent는 작업의 일부로 명령을 실행할 수 있습니다.

샌드박스 공급자는 통제된 환경에서 명령을 실행합니다.

- **명령 실행**: 인수를 사용하여 셸 명령 실행
- **백그라운드 프로세스**: 개발 서버 및 감시자와 같은 장기 실행 프로세스 생성
- **작업 디렉토리**: 특정 디렉터리에서 실행되는 명령
- **환경변수**: 사용 가능한 변수를 제어합니다.
- **시간 초과**: 장기 실행 명령이 중단되는 것을 방지합니다.
- **격리**: 보안을 위한 선택적 OS 수준 샌드박싱

:::tip\[📹 보기]

원격 Sandbox가 Agent에 작업할 수 있는 격리된 컴퓨터를 제공하는 방식을 알아보려면 [Mastra 원격 Sandbox 개요](https://www.youtube.com/watch?v=Ix2X-sjVXjw)를 참조하세요. :::

## 지원되는 Provider

- [`LocalSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/local-sandbox): 로컬 머신에서 명령을 실행합니다.
- [`AgentCoreRuntimeSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/agentcore-runtime-sandbox): AWS Bedrock AgentCore Runtime 세션에서 명령을 실행합니다.
- [`AppleContainerSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/apple-container-sandbox): Apple의 OCI Linux 컨테이너에서 명령을 실행합니다.`container` CLI
- [`BlaxelSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/blaxel-sandbox): 격리된 Blaxel 클라우드 샌드박스에서 명령을 실행합니다.
- [`DaytonaSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/daytona-sandbox): 격리된 Daytona 클라우드 샌드박스에서 명령을 실행합니다.
- [`DockerSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/docker-sandbox): 로컬 시스템의 수명이 긴 Docker 컨테이너에서 명령을 실행합니다.
- [`E2BSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/e2b-sandbox): 격리된 E2B 클라우드 샌드박스에서 명령을 실행합니다.
- [`ModalSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/modal-sandbox): 격리된 Modal 클라우드 샌드박스에서 명령을 실행합니다.
- [`PlatformSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/platform-sandbox): Mastra Platform 환경에 연결된 샌드박스에서 명령을 실행합니다.
- [`RailwaySandbox`](https://mastra.zisheng.pro/ko/reference/workspace/railway-sandbox): 일시적이고 격리된 철도 클라우드 샌드박스에서 명령을 실행합니다.
- [`VercelSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/vercel-sandbox): 임시 Vercel Sandbox Firecracker MicroVM에서 명령을 실행합니다.
- [`VercelServerlessSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/vercel-serverless): 상태 비저장 Vercel 서버리스 함수로 명령을 실행합니다.

## 기본 사용법

샌드박스를 사용하여 작업 영역을 만들고 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',
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful development assistant.',
  workspace,
})

// The agent now has the execute_command tool available
const response = await agent.generate('Run `ls -la` in the workspace directory')
```

환경 격리 및 네이티브 OS Sandbox를 비롯한 구성 옵션은 [`LocalSandbox` 레퍼런스](https://mastra.zisheng.pro/ko/reference/workspace/local-sandbox)를 참조하세요.

## 동적 샌드박스

`sandbox` 옵션에는 정적 인스턴스 대신 리졸버 함수를 사용할 수 있습니다. 리졸버는 `requestContext`를 받아 요청별 Sandbox를 반환하므로 하나의 Workspace에서 호출자의 ID, 역할 또는 테넌트에 따라 서로 다른 Sandbox를 제공할 수 있습니다.

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

const workspace = new Workspace({
  sandbox: ({ requestContext }) => {
    const userId = requestContext.get('user-id') as string
    return new LocalSandbox({
      workingDirectory: `/workspaces/${userId}`,
    })
  },
})

const agent = new Agent({
  id: 'multi-tenant-agent',
  model: 'your-provider/your-model',
  workspace,
})
```

각 요청은 Tool 실행 시 자체 샌드박스를 확인합니다.

```typescript
import { RequestContext } from '@mastra/core/request-context'

// User Alice — commands run in /workspaces/alice
const aliceCtx = new RequestContext([['user-id', 'alice']])
await agent.generate('List files in cwd', { requestContext: aliceCtx })

// User Bob — commands run in /workspaces/bob
const bobCtx = new RequestContext([['user-id', 'bob']])
await agent.generate('List files in cwd', { requestContext: bobCtx })
```

기본적으로 Workspace 지침은 일관된 자리표시자 텍스트를 사용하여 런타임 Sandbox를 설명합니다. 구체적인 요청별 세부 정보를 포함하려면 [Workspace 지침](#workspace-instructions)을 참조하세요. 예를 들어 데이터베이스에서 테넌트 구성을 조회하기 위해 확인자는 비동기식일 수도 있습니다.

```typescript
const workspace = new Workspace({
  sandbox: async ({ requestContext }) => {
    const tenant = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalSandbox({ workingDirectory: tenant.workspacePath })
  },
})
```

### 수명주기 소유권

Sandbox가 정적 인스턴스이면 `workspace.init()`이 해당 인스턴스의 `start()` 메서드를 호출하고 `workspace.destroy()`가 `destroy()` 메서드를 호출합니다. 리졸버를 사용하면 생성 시점에 Workspace가 관리할 인스턴스가 없으므로 반환된 Sandbox의 수명 주기는 호출자가 소유합니다. 확인자는 이미 시작되었거나 명시적인 시작 없이 호출을 처리할 수 있는, 사용할 준비가 된 샌드박스를 반환해야 합니다. 또한 호출자는 반환된 샌드박스에 대한 정리 타이밍을 소유합니다.

요청, 테넌트 또는 사용자별로 정리가 발생할 수 있습니다. 또한 수명이 긴 샌드박스 풀의 일부일 수도 있습니다.`workspace.destroy()` doesn't destroy resolver-returned sandboxes.

> **노트:** `sandbox` 리졸버는 `mounts` 및 `lsp: true`와 호환되지 않습니다. 둘 다 생성 시점에 구체적인 Sandbox 인스턴스가 필요하므로 리졸버와 함께 사용하면 `INVALID_CONFIG` 오류가 발생하거나(`mounts`의 경우) 경고와 함께 LSP가 비활성화됩니다(`lsp: true`의 경우).

### Tool 등록

정적 Sandbox를 사용하면 Workspace가 인스턴스를 검사하여 등록할 Tool을 결정합니다. 리졸버를 사용하면 Workspace는 모든 기능을 지원한다고 간주하여 `execute_command`(`background` 지원), `get_process_output`, `kill_process`를 등록합니다. 해석된 Sandbox가 특정 기능을 구현하지 않았다면 런타임에 명확한 `SandboxFeatureNotSupportedError`가 발생합니다.

### 백그라운드 프로세스 연속성

백그라운드 프로세스는 단일 Tool 호출보다 오래 실행될 수 있으므로 `get_process_output`과 `kill_process`는 프로세스를 시작한 동일한 Sandbox에 접근해야 합니다. 기본적으로 해석된 Sandbox는 요청별로 캐시됩니다. 이후 대화 차례와 같은 후속 요청에서도 연속성을 유지하려면 `sandboxCacheKey`를 일관된 식별자로 설정하세요. 그러면 해석된 Sandbox가 요청 대신 해당 키를 기준으로 캐시됩니다.

```typescript
const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  sandboxCacheKey: ({ requestContext }) => requestContext.get('thread-id') as string,
})
```

`sandboxCacheKey`를 사용하지 않으면 테넌트, 사용자 또는 세션이 같은 후속 호출에 리졸버가 동일한 Sandbox를 직접 반환해야 합니다. 캐시된 Sandbox가 더 이상 필요하지 않으면 자체 수명 주기 코드에서 Sandbox를 제거하고 `workspace.clearSandboxCache(cacheKey)`를 호출하여 Workspace 캐시 항목을 삭제하세요. 키가 지정된 모든 Sandbox 항목을 지우려면 `workspace.clearSandboxCache()`를 호출하세요.

### 작업공간 지침

작업 공간 지침은 Agent 시스템 메시지의 환경을 설명합니다. 샌드박스 해석기를 사용하면 작업공간은 이러한 지침을 작성하기 위해 해석기를 호출하지 않습니다. 안정적인 자리 표시자 텍스트를 내보내므로 Prompt를 구성할 때 호출자가 소유한 샌드박스를 프로비저닝하지 않으며 시스템 메시지가 요청 전체에서 일관되게 유지되므로 Prompt 캐싱이 효과적으로 유지됩니다.

구체적인 요청별 Sandbox 세부 정보를 포함하려면 `instructions.dynamicSandbox`를 `'resolve'`로 설정하세요.

```typescript
const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  instructions: { dynamicSandbox: 'resolve' },
})
```

`'resolve'`는 모든 요청에서 리졸버를 호출하므로 Sandbox를 프로비저닝하고 요청별 시스템 메시지를 구성할 수 있습니다. Sandbox를 해석하지 않고 `requestContext`를 기반으로 사용자 정의 텍스트를 반환하려면 함수를 대신 전달하세요.

```typescript
const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  instructions: {
    dynamicSandbox: ({ requestContext }) =>
      `Sandbox scoped to tenant ${requestContext.get('tenant-id')}.`,
  },
})
```

## Agent Tool

Workspace에서 Sandbox를 구성하면 Agent에 셸 명령을 실행하는 `execute_command` Tool이 제공됩니다. Sandbox Provider가 백그라운드 프로세스 실행을 지원하는 경우 `execute_command` Tool에서 장기 실행 프로세스를 시작하기 위한 `background: true`도 사용할 수 있으며, 다음 두 가지 Tool이 추가로 등록됩니다.

| Tool                                                                                                                                 | 설명                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `execute_command`                                                                                                                    | 셸 명령을 실행합니다. stdout, stderr 및 종료 코드를 반환합니다. `background: true`를 지원하므로 장기 실행 프로세스를 생성하고 PID를 반환할 수 있습니다.  |
| `get_process_output`                                                                                                                 | PID를 사용하여 백그라운드 프로세스의 stdout, stderr 및 상태를 가져옵니다. 출력 줄 수를 제한하는 `tail`과 종료될 때까지 차단하는 `wait: true`를 지원합니다. |
| `kill_process`                                                                                                                       | PID를 사용하여 백그라운드 프로세스를 중지합니다. 최근 출력을 반환합니다.                                                               |
| 이러한 Tool은 자동으로 등록됩니다. 전체 Tool 이름 목록은 [Workspace 클래스 레퍼런스](https://mastra.zisheng.pro/ko/reference/workspace/workspace-class)를 참조하세요. |                                                                                                          |

## 백그라운드 프로세스 콜백

Agent가 `execute_command` Tool을 통해 백그라운드 프로세스를 시작하면 stdout, stderr 및 프로세스 종료에 대한 수명 주기 콜백을 받을 수 있습니다. `execute_command` Tool의 `backgroundProcesses` 옵션을 통해 이를 구성하세요.

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

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        onStdout: (data, { pid }) => console.log(`[${pid}] ${data}`),
        onStderr: (data, { pid }) => console.error(`[${pid}] ${data}`),
        onExit: ({ pid, exitCode }) => console.log(`Process ${pid} exited: ${exitCode}`),
      },
    },
  },
})
```

이러한 콜백은 Agent가 다음을 통해 시작한 모든 백그라운드 프로세스에 대해 실행됩니다.`execute_command` tool.

### 중단 신호

기본적으로 백그라운드 프로세스는 Agent의 중단 신호를 상속하며 Agent 연결이 끊어지면 종료됩니다. 다음을 사용하여 이 동작을 제어하세요.`abortSignal` option:

- **`undefined`**(기본값): Agent의 중단 신호를 사용합니다.
- **`AbortSignal`**: 맞춤 신호를 사용합니다.
- **`null`또는`false`**: 중단을 비활성화합니다. Agent 종료 후에도 프로세스가 지속됩니다.

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

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        abortSignal: null, // Processes survive agent disconnection
      },
    },
  },
})
```

프로세스가 Agent보다 오래 유지되어야 하는 클라우드 Sandbox(예: E2B, Daytona, Modal)에는 `null` 또는 `false`를 사용하세요. :::참고 전체 `SandboxProcessManager` API(프로그래밍 방식으로 프로세스를 생성하고 출력을 읽으며 stdin을 전송하는 기능 포함)는 [`SandboxProcessManager` 레퍼런스](https://mastra.zisheng.pro/ko/reference/workspace/process-manager)를 참조하세요. :::

## 관련된

- [`SandboxProcessManager`참조](https://mastra.zisheng.pro/ko/reference/workspace/process-manager)
- [`AgentCoreRuntimeSandbox`참조](https://mastra.zisheng.pro/ko/reference/workspace/agentcore-runtime-sandbox)
- [`AppleContainerSandbox`참조](https://mastra.zisheng.pro/ko/reference/workspace/apple-container-sandbox)
- [`DaytonaSandbox`참조](https://mastra.zisheng.pro/ko/reference/workspace/daytona-sandbox)
- [`E2BSandbox`참조](https://mastra.zisheng.pro/ko/reference/workspace/e2b-sandbox)
- [`LocalSandbox`참조](https://mastra.zisheng.pro/ko/reference/workspace/local-sandbox)
- [`ModalSandbox`참조](https://mastra.zisheng.pro/ko/reference/workspace/modal-sandbox)
- [`VercelSandbox`참조](https://mastra.zisheng.pro/ko/reference/workspace/vercel-sandbox)
- [`VercelServerlessSandbox`참조](https://mastra.zisheng.pro/ko/reference/workspace/vercel-serverless)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)
- [파일 시스템](https://mastra.zisheng.pro/ko/docs/workspace/filesystem)