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

# Vercel샌드박스

내부에서 명령을 실행합니다.[Vercel Sandbox](https://vercel.com/docs/vercel-sandbox)그건 임시적이야[폭죽](https://firecracker-microvm.github.io/)Amazon Linux 2023을 실행하는 MicroVM. 지속적인 세션 내 파일 시스템을 제공합니다.`sudo`액세스, 노출된 포트 및 백그라운드 프로세스. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[WorkspaceSandbox 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/sandbox).

> **노트:** 이는 명령을 상태 비저장 Vercel 서버리스 **Functions**로 실행하는 [`VercelServerlessSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/vercel-serverless)와 다릅니다. `VercelSandbox`는 영구 파일 시스템과 장기 실행 프로세스를 갖춘 전체 Linux MicroVM을 실행합니다.

## 설치

**npm**:

```bash
npm install @mastra/vercel
```

**pnpm**:

```bash
pnpm add @mastra/vercel
```

**Yarn**:

```bash
yarn add @mastra/vercel
```

**Bun**:

```bash
bun add @mastra/vercel
```

## 입증

명시적인 자격 증명을 제공하지 않으면 `@vercel/sandbox` SDK가 Vercel OIDC 토큰을 자동으로 사용합니다. `token`, `teamId`, `projectId` 중 하나를 제공하는 경우 세 값을 모두 함께 제공하세요.

**OIDC (recommended)**:

로컬 개발의 경우 프로젝트를 연결하고 개발 토큰을 가져옵니다.

```bash
vercel link
vercel env pull
```

Vercel에서는 인증이 자동으로 처리되므로 구성이 필요하지 않습니다.

**Access token (.env)**:

OIDC가 없는 환경의 경우 세 가지 값을 모두 함께 제공합니다.

```bash
VERCEL_TOKEN=your-token
VERCEL_TEAM_ID=your-team-id
VERCEL_PROJECT_ID=your-project-id
```

**Constructor**:

```typescript
new VercelSandbox({
  token: 'your-token',
  teamId: 'your-team-id',
  projectId: 'your-project-id',
})
```

## 용법

Workspace에 `VercelSandbox`를 추가하고 Agent에 할당합니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { VercelSandbox } from '@mastra/vercel'

const workspace = new Workspace({
  sandbox: new VercelSandbox({
    runtime: 'node24',
    timeout: 600_000,
  }),
})

const agent = new Agent({
  id: 'code-agent',
  name: 'Code Agent',
  instructions: 'You are a coding assistant working in this workspace.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

const response = await agent.generate('Print "Hello, world!" and show the Node.js version.')

console.log(response.text)
```

### 리소스 및 노출된 포트

vCPU(vCPU당 Memory 2048MB)를 할당하고 포트를 노출하여 샌드박스 내부에서 실행되는 네트워크 서비스에 연결합니다.

```typescript
const sandbox = new VercelSandbox({
  runtime: 'node24',
  resources: { vcpus: 4 },
  ports: [3000],
})

const workspace = new Workspace({ sandbox })
await sandbox.start()

// The public HTTPS domain for an exposed port is available via getInfo()
const { metadata } = sandbox.getInfo()
console.log(metadata?.domains) // { 3000: 'https://....vercel.run' }
```

### 스트리밍 출력

`onStdout` 및 `onStderr` 콜백을 통해 명령 출력을 실시간으로 스트리밍합니다.

```typescript
await sandbox.executeCommand('sh', ['-c', 'for i in 1 2 3; do echo "line $i"; sleep 1; done'], {
  onStdout: chunk => process.stdout.write(chunk),
  onStderr: chunk => process.stderr.write(chunk),
})
```

두 콜백 모두 선택 사항이며 독립적으로 사용할 수 있습니다.

## 생성자 매개변수

**id** (`string`): 이 Sandbox 인스턴스의 고유 식별자입니다. (Default: `자동 생성`)

**sandboxName** (`string`): Vercel API에 전달할 선택적 이름입니다. 생략하면 자동 생성됩니다.

**token** (`string`): Vercel API 토큰입니다. 지정하지 않으면 VERCEL\_TOKEN 환경 변수를 사용합니다. OIDC 토큰을 사용하려면 생략하세요.

**teamId** (`string`): Vercel 팀 ID입니다. 지정하지 않으면 VERCEL\_TEAM\_ID 환경 변수를 사용합니다.

**projectId** (`string`): Vercel 프로젝트 ID입니다. 지정하지 않으면 VERCEL\_PROJECT\_ID 환경 변수를 사용합니다.

**runtime** (`'node24' | 'node22' | 'node26' | 'python3.13'`): Sandbox 런타임입니다. (Default: `'node24'`)

**timeout** (`number`): Sandbox가 자동 종료되기 전까지의 제한 시간(밀리초)입니다. (Default: `300000 (5분)`)

**resources** (`{ vcpus?: number }`): 리소스 할당입니다. 각 vCPU에는 2048MB 메모리가 제공됩니다.

**ports** (`number[]`): Sandbox에서 노출할 포트입니다(최대 15개). 공개 HTTPS 도메인은 getInfo().metadata.domains를 통해 사용할 수 있습니다.

**env** (`Record<string, string>`): 모든 명령이 상속하는 기본 환경 변수입니다. (Default: `{}`)

**metadata** (`Record<string, unknown>`): getInfo()를 통해 노출되는 사용자 지정 메타데이터입니다. (Default: `{}`)

**instructions** (`string | ((opts) => string)`): getInstructions()가 반환하는 기본 지침을 재정의합니다. 문자열을 전달해 대체하거나 함수를 전달해 기본값을 확장합니다.

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

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

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

## 속성

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

**name** (`'VercelSandbox'`): 사람이 읽을 수 있는 이름입니다.

**provider** (`'vercel-sandbox'`): Provider 유형 식별자입니다.

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

**sandbox** (`Sandbox`): 기본 @vercel/sandbox Sandbox 인스턴스입니다. Sandbox가 시작되지 않았으면 SandboxNotReadyError를 발생시킵니다.

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

## 백그라운드 프로세스

`VercelSandbox`백그라운드 프로세스를 생성하고 관리하기 위한 프로세스 관리자가 포함되어 있습니다. 생성된 각 프로세스는 MicroVM 내에서 분리된 명령으로 실행되며 출력은 명령 로그를 통해 스트리밍됩니다.

```typescript
const sandbox = new VercelSandbox({ runtime: 'node24', ports: [3000] })
await sandbox.start()

const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

console.log(handle.stdout)
await handle.kill()
```

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

> **노트:** Vercel Sandbox SDK는 명령 실행을 위한 stdin 채널을 노출하지 않으므로 `handle.sendStdin()`은 오류를 발생시킵니다. 이 Provider는 파일 시스템 마운트(FUSE)도 지원하지 않습니다.

## 제한

- vCPU당 Memory가 2048MB인 최대 32개의 vCPU.
- 최대 15개의 노출된 포트.
- 파일 시스템은 임시적입니다. 세션 내에서만 지속되며 샌드박스가 중지되면 손실됩니다.
- 최대 실행 시간은 계획에 따라 다르며(Hobby에서는 45분, Pro 및 Enterprise에서는 최대 24시간) 기본값은 5분입니다.

현재 제한 사항과 가격은 [Vercel Sandbox 문서](https://vercel.com/docs/vercel-sandbox)를 참조하세요.