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

# Blaxel샌드박스

격리된 상태에서 명령을 실행합니다.[Blaxel](https://blaxel.ai/)클라우드 샌드박스. FUSE를 통한 클라우드 스토리지(S3, GCS) 탑재를 지원하여 안전하고 격리된 코드 실행 환경을 제공합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[WorkspaceSandbox 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/sandbox).

## 설치

**npm**:

```bash
npm install @mastra/blaxel
```

**pnpm**:

```bash
pnpm add @mastra/blaxel
```

**Yarn**:

```bash
yarn add @mastra/blaxel
```

**Bun**:

```bash
bun add @mastra/blaxel
```

## 용법

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

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { BlaxelSandbox } from '@mastra/blaxel'

const workspace = new Workspace({
  sandbox: new BlaxelSandbox(),
})

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,
})
```

### 리소스가 포함된 커스텀 이미지

추가 Memory가 있는 사용자 지정 Docker 이미지를 사용합니다.

```typescript
const workspace = new Workspace({
  sandbox: new BlaxelSandbox({
    image: 'node:20-slim',
    memory: 8192,
    region: 'auto',
    timeout: '10m',
  }),
})
```

## 생성자 매개변수

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

**image** (`string`): Sandbox에 사용할 Docker 이미지입니다. Debian 기반 이미지는 S3 및 GCS 마운트를 모두 지원합니다. Alpine 기반 이미지는 S3 마운트만 지원합니다. (Default: `'blaxel/ts-app:latest'`)

**memory** (`number`): MB 단위 Memory 할당량입니다. (Default: `4096`)

**timeout** (`string`): 기간 문자열로 지정하는 실행 제한 시간입니다(예: '5m', '1h'). Blaxel Sandbox TTL에 매핑됩니다.

**region** (`string`): Sandbox를 생성할 Blaxel 리전입니다. 리전을 자동으로 선택하려면 'auto'를 사용하고, 특정 리전을 지정하려면 'us-pdx-1'과 같은 값을 설정합니다. (Default: `process.env.BL_REGION || 'auto'`)

**env** (`Record<string, string>`): Sandbox에 설정할 환경 변수입니다.

**labels** (`Record<string, string>`): Sandbox의 사용자 지정 레이블입니다.

**runtimes** (`SandboxRuntime[]`): 지원되는 런타임입니다. 유효한 값: 'node', 'python', 'bash', 'ruby', 'go', 'rust', 'java', 'cpp', 'r'. (Default: `['node', 'python', 'bash']`)

**ports** (`Array<{ name?: string; target: number; protocol?: 'HTTP' | 'TCP' | 'UDP' }>`): Sandbox에서 노출할 포트입니다.

## 속성

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

**name** (`string`): 'BlaxelSandbox'

**provider** (`string`): 'blaxel'

**status** (`ProviderStatus`): 'pending' | 'initializing' | 'running' | 'stopped' | 'error'

**instance** (`SandboxInstance`): Blaxel API에 직접 액세스하기 위한 기본 Blaxel SandboxInstance입니다. Sandbox가 시작되지 않았으면 SandboxNotReadyError를 발생시킵니다.

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

## 백그라운드 프로세스

`BlaxelSandbox`백그라운드 프로세스 생성 및 관리를 위한 내장 프로세스 관리자가 포함되어 있습니다.

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

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

// Interact with the process
console.log(handle.stdout)
await handle.kill()
```

:::참고 Blaxel Sandbox는 stdin을 지원하지 않습니다. `handle.sendStdin()`을 호출하면 오류가 발생합니다. ::: 전체 API는 [`SandboxProcessManager` 레퍼런스](https://mastra.zisheng.pro/ko/reference/workspace/process-manager)를 참조하세요.

## 클라우드 스토리지 마운트

Blaxel 샌드박스는 S3 또는 GCS 파일 시스템을 마운트할 수 있으므로 샌드박스 내부의 로컬 디렉터리로 클라우드 저장소에 액세스할 수 있습니다.

### S3

```typescript
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { BlaxelSandbox } from '@mastra/blaxel'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
  },
  sandbox: new BlaxelSandbox(),
})
```

### GCS

```typescript
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'
import { BlaxelSandbox } from '@mastra/blaxel'

const workspace = new Workspace({
  mounts: {
    '/data': new GCSFilesystem({
      bucket: 'my-bucket',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
    }),
  },
  sandbox: new BlaxelSandbox(),
})
```