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

# 모달샌드박스

격리된 상태에서 명령을 실행합니다.[Modal](https://modal.com)클라우드 샌드박스. Modal의 인프라가 지원되는 안전하고 임시적인 환경을 제공합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[WorkspaceSandbox 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/sandbox).

## 설치

**npm**:

```bash
npm install @mastra/modal
```

**pnpm**:

```bash
pnpm add @mastra/modal
```

**Yarn**:

```bash
yarn add @mastra/modal
```

**Bun**:

```bash
bun add @mastra/modal
```

## 용법

Workspace에 `ModalSandbox`를 추가하고 Agent에 할당합니다:

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ModalSandbox } from '@mastra/modal'

const workspace = new Workspace({
  sandbox: new ModalSandbox({
    id: 'dev-sandbox',
    baseImage: 'ubuntu:22.04',
    timeoutMs: 60_000,
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

## 입증

환경 변수 또는 생성자 옵션을 통해 모달 자격 증명을 설정합니다.

```bash
MODAL_TOKEN_ID=ak-...
MODAL_TOKEN_SECRET=as-...
```

또는 직접 전달하세요.

```typescript
const sandbox = new ModalSandbox({
  tokenId: process.env.MODAL_TOKEN_ID,
  tokenSecret: process.env.MODAL_TOKEN_SECRET,
})
```

다음에서 자격 증명을 받으세요.[Modal dashboard](https://modal.com/settings/tokens).

## 생성자 매개변수

**id** (`string`): 이 Sandbox의 고유 식별자/이름입니다. 이후 start() 호출에서 Sandbox에 다시 연결할 수 있도록 Modal Sandbox 이름으로 사용됩니다. (Default: `자동 생성`)

**appName** (`string`): Sandbox와 연결할 Modal App 이름입니다. (Default: `'mastra'`)

**baseImage** (`string`): Sandbox에 사용할 Docker 이미지입니다. (Default: `'ubuntu:22.04'`)

**timeoutMs** (`number`): 밀리초 단위의 최대 실제 수명입니다. 활동 여부와 관계없이 이 시간이 만료되면 Sandbox가 종료됩니다. Modal의 최대값은 24시간(86\_400\_000)입니다. (Default: `300000(5분)`)

**env** (`Record<string, string>`): 생성 시 Sandbox에 포함되는 환경 변수입니다.

**workdir** (`string`): Sandbox 내부의 기본 작업 디렉터리입니다.

**tokenId** (`string`): Modal 토큰 ID입니다. MODAL\_TOKEN\_ID 환경 변수를 대신 사용할 수 있습니다.

**tokenSecret** (`string`): Modal 토큰 비밀 값입니다. MODAL\_TOKEN\_SECRET 환경 변수를 대신 사용할 수 있습니다.

**instructions** (`string | function`): getInstructions()에서 반환되는 사용자 지정 지침입니다. 기본값을 완전히 대체하려면 문자열을 전달하고, 확장하려면 함수를 전달합니다.

**onStart** (`function`): Sandbox가 실행 상태에 도달한 후 호출되는 수명 주기 훅입니다.

**onStop** (`function`): Sandbox가 중지되기 전에 호출되는 수명 주기 훅입니다.

**onDestroy** (`function`): Sandbox가 폐기되기 전에 호출되는 수명 주기 훅입니다.

## 속성

**id** (`string`): Sandbox 인스턴스 식별자입니다.

**name** (`string`): Provider 이름('ModalSandbox')

**provider** (`string`): Provider 식별자('modal')

**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

**modal** (`Sandbox`): 기반 Modal Sandbox 인스턴스입니다. Sandbox가 시작되지 않았으면 SandboxNotReadyError를 발생시킵니다.

**processes** (`ModalProcessManager`): 백그라운드 프로세스 관리자입니다. SandboxProcessManager 레퍼런스를 참조하세요.

## 샌드박스 수명주기

- **`_start()`**: 실행 중인 기존 Sandbox에 다시 연결을 시도합니다. 찾지 못하면 최신 스냅샷(이전 `_stop()`에서 생성된 스냅샷이 있는 경우) 또는 baseImage에서 Sandbox를 생성합니다.
- **`_stop()`**: 파일 시스템의 스냅샷을 생성한 다음 Sandbox를 종료합니다. 스냅샷은 이후 시작에 사용할 수 있도록 동일한 인스턴스의 Memory에 보관됩니다.
- **`_destroy()`**: Sandbox를 종료하고 모든 스냅샷을 삭제합니다.

```typescript
const sandbox = new ModalSandbox({
  id: 'dev-sandbox',
  baseImage: 'ubuntu:22.04',
  timeoutMs: 300_000,
})

await sandbox._start()
await sandbox.processes.spawn('npm install')
await sandbox._stop()
await sandbox._start()
```

## 백그라운드 프로세스

`ModalSandbox`에는 백그라운드 프로세스를 생성하고 관리하는 내장 프로세스 관리자가 포함되어 있습니다. 각 `spawn()` 호출은 Modal SDK의 `Sandbox.exec()` API를 통해 새 `ContainerProcess`를 생성합니다.

```typescript
const sandbox = new ModalSandbox({ id: 'dev-sandbox' })
await sandbox._start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node script.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// Wait for the process to complete
const result = await handle.wait()
console.log(result.exitCode)

// Kill the process
await handle.kill()
```

> **노트:** `sendStdin()`지원되지 않습니다. Modal JS SDK는 stdin을 노출하지 않습니다.`Sandbox.exec()`.

전체 API는 [`SandboxProcessManager` 레퍼런스](https://mastra.zisheng.pro/ko/reference/workspace/process-manager)를 참조하세요.

## 관련된

- [SandboxProcessManager 참조](https://mastra.zisheng.pro/ko/reference/workspace/process-manager)
- [WorkspaceSandbox 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/sandbox)
- [E2B샌드박스 참조](https://mastra.zisheng.pro/ko/reference/workspace/e2b-sandbox)
- [Daytona샌드박스 참조](https://mastra.zisheng.pro/ko/reference/workspace/daytona-sandbox)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)