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

# 작업공간

작업공간은 Mastra 플랫폼이 배포 시 Agent에 프로비저닝하고 전달하는 런타임 리소스 세트입니다. 각 환경에는 고유한 작업 공간이 있으므로`production`그리고`staging`격리 상태를 유지하세요.

모든 작업공간은 두 가지 기능을 제공합니다.

- 파일 시스템 스토리지용 **버킷** 하나로, [`PlatformFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/platform-filesystem)로 래핑됩니다. 버킷은 Agent가 여러 실행에 걸쳐 읽고 쓸 수 있는 환경 범위의 영구 저장소입니다.
- 명령 실행용 **온디맨드 Sandbox** 풀로, [`PlatformSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/platform-sandbox)로 래핑됩니다. 각 `PlatformSandbox` 인스턴스는 `start()`에서 자체 원격 Sandbox를 프로비저닝하고 `destroy()`에서 제거합니다. Agent는 일반적으로 세션마다 여러 Sandbox를 시작하여 작업에 사용한 뒤 그대로 둡니다. Workspace의 범위는 하나의 [환경](https://mastra.zisheng.pro/ko/docs/mastra-platform/environments)으로 지정되므로 `production`과 `staging`은 버킷이나 Sandbox 풀을 공유하지 않습니다. 플랫폼에서 프로비저닝, 인증, 유휴 리소스 정리를 관리합니다.

## Workspace가 프로비저닝되는 경우

새 프로젝트에는 기본적으로 Workspace가 활성화되어 있습니다. 환경을 생성하면 플랫폼이 해당 환경의 버킷을 자동으로 프로비저닝합니다. Sandbox 기본 이미지는 백그라운드에서 미리 준비되므로 첫 번째 `PlatformSandbox` 호출도 빠르게 시작됩니다. 아직 활성화하지 않은 기존 프로젝트의 Workspaces 탭에는 **Enable workspaces** 작업이 표시됩니다. 활성화하면 프로젝트의 모든 환경에 버킷이 프로비저닝됩니다. 예를 들어 샌드박스 공급자가 로드 중인 동안 환경에 대한 프로비저닝이 실패하면 작업 영역 탭에 실패가 표시되고 재시도가 제공됩니다. 환경 자체는 여전히 생성됩니다. 다시 시도할 때까지 작업공간만 사용할 수 없습니다.

## 코드에서 작업공간 사용

공급자 패키지를 설치합니다.

**npm**:

```bash
npm install @mastra/platform-workspace
```

**pnpm**:

```bash
pnpm add @mastra/platform-workspace
```

**Yarn**:

```bash
yarn add @mastra/platform-workspace
```

**Bun**:

```bash
bun add @mastra/platform-workspace
```

공급자를 작업 공간으로 구성하고 이를 Mastra에 등록합니다.

```typescript
import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'

export const workspace = new Workspace({
  filesystem: new PlatformFilesystem(),
  sandbox: new PlatformSandbox(),
})
```

```typescript
import { Mastra } from '@mastra/core'
import { workspace } from './workspace'

export const mastra = new Mastra({
  workspace,
})
```

`PlatformFilesystem`과 `PlatformSandbox`는 환경 변수에서 구성을 읽으므로 플랫폼에서는 옵션을 전달하지 않습니다. 플랫폼이 배포 시 해당 변수를 주입합니다. [환경 변수](#environment-variables)를 참조하세요.

## 하나의 버킷, 많은 샌드박스

`PlatformFilesystem`과 `PlatformSandbox`는 수명 주기가 서로 다르며, 이는 Agent를 설계할 때 중요합니다. **`PlatformFilesystem`환경 버킷에 대한 수명이 긴 핸들입니다.**환경의 모든 요청, 모든 Agent 및 모든 샌드박스는 동일한 객체 스토리지를 읽고 씁니다. Agent가 작성한 모든 내용은 명시적으로 삭제하지 않는 한 다음 요청 시 표시됩니다.

**`PlatformSandbox`임시 샌드박스를 프로비저닝하기 위한 클라이언트입니다.**각`PlatformSandbox` instance owns one remote sandbox:

- `start()`는 새 Sandbox를 프로비저닝하거나 전달된 `sandboxId`에 다시 연결합니다.
- `executeCommand()`는 해당 Sandbox에서 명령을 실행합니다.
- `destroy()`는 Sandbox를 제거합니다. `stop()`은 별칭입니다. `Workspace`에 전달하는 `sandbox`는 Agent가 자체 요청 내에서 사용하는 Tool을 제공합니다. 작업별 Workspace, 사용자별 테넌트 또는 호출자의 셸 상태에 영향을 주면 안 되는 백그라운드 작업처럼 Agent에 별도의 격리된 환경이 필요한 경우 다른 `PlatformSandbox`를 생성하세요.

```typescript
import { PlatformSandbox } from '@mastra/platform-workspace'

export async function runInFreshSandbox(command: string) {
  const sandbox = new PlatformSandbox()
  await sandbox.start()
  try {
    return await sandbox.executeCommand(command)
  } finally {
    await sandbox.destroy()
  }
}
```

또는 구성된 샌드박스를 플릿의 템플릿으로 복제하여 복제가 자격 증명, 환경, 네트워크 격리 및 기본값을 반복하지 않고 상속하도록 합니다.

```typescript
const template = new PlatformSandbox({ networkIsolation: 'PRIVATE' })

const perProjectSandbox = template.clone({ id: `project-${projectId}` })
await perProjectSandbox.start()
```

전체 수명 주기, 체크포인트 복구, 재연결 및 복제 옵션은 [`PlatformSandbox` 참고 문서](https://mastra.zisheng.pro/ko/reference/workspace/platform-sandbox)를 참조하세요.

## 환경변수

작업공간이 있는 플랫폼 환경에서 실행되는 모든 배포는 다음 변수를 자동으로 받습니다.

| 변수                                                       | 설명                                                                                      |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `MASTRA_PLATFORM_ACCESS_TOKEN`                           | Workspace Provider가 인증에 사용하는 플랫폼 발급 JSON Web Token(JWT)입니다. 토큰 범위는 배포의 조직과 프로젝트로 제한됩니다. |
| `MASTRA_PROJECT_ID`                                      | 배포가 속한 프로젝트입니다.                                                                         |
| `MASTRA_ENVIRONMENT_ID`                                  | 배포가 속한 환경입니다. 플랫폼에서 사용할 Sandbox 풀을 선택합니다.                                               |
| `MASTRA_PLATFORM_BUCKET_NAME`                            | 환경에 연결된 버킷 이름입니다. `PlatformFilesystem`이 읽고 쓸 버킷을 선택합니다.                                 |
| 이 이름은 예약되어 있습니다. 프로젝트에서 명시적으로 설정한 경우 플랫폼 관리 값이 우선 적용됩니다. |                                                                                         |

## 지역 발전

네 변수를 `.env` 파일에 추가하세요. 프로젝트, 환경 및 버킷 값은 프로젝트의 **Workspaces** 탭에서 가져옵니다. `MASTRA_PLATFORM_ACCESS_TOKEN`에는 조직 설정 페이지의 **API Tokens**에서 `sk_` API 토큰을 생성해 사용하세요. 플랫폼 배포에서는 주입된 JWT를 대신 사용합니다.

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
```

`PlatformFilesystem`과 `PlatformSandbox`는 로컬과 플랫폼에서 동일하게 동작하며 해당 환경의 같은 버킷과 Sandbox 풀에 연결됩니다. 프로덕션 데이터를 격리하려면 로컬 실행에 `staging` 또는 `preview` 환경의 변수를 사용하세요. 플랫폼에 전혀 영향을 주지 않는 완전한 오프라인 루프가 필요하면 로컬 빌드에서 Provider를 [`LocalFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/local-filesystem)과 [`LocalSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/local-sandbox)로 교체하세요.

## 작업 공간 검사

플랫폼 프로젝트의 작업공간 탭에는 환경별로 다음이 표시됩니다.

- 업로드, 다운로드, 삭제 작업이 포함된 버킷 상태 및 해당 콘텐츠입니다.
- 해당 명령, 종료 코드 및 기간이 포함된 최근 샌드박스 세션입니다.
- 프로비저닝 실패**Retry** action.

## 또한보십시오

- [`PlatformFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/platform-filesystem): 파일 시스템 공급자에 대한 참조입니다.
- [`PlatformSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/platform-sandbox): 체크포인트 복구 및 복제를 포함한 샌드박스 공급자에 대한 참조입니다.
- [환경](https://mastra.zisheng.pro/ko/docs/mastra-platform/environments): 환경이 작업 공간, 변수 및 데이터베이스의 범위를 지정하는 방법입니다.