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

# 파일 시스템

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

파일 시스템 공급자는 Agent에 파일 읽기, 쓰기, 관리 기능을 제공합니다. 작업공간에서 파일 시스템을 구성하면 Agent는 파일 작업을 위한 Tool을 받습니다.

파일 시스템 공급자는 작업공간에 대한 모든 파일 작업을 처리합니다.

- **읽다**- 파일 내용 읽기
- **쓰다**- 파일 생성 및 업데이트
- **목록**- 선택적 글로브 패턴 필터링을 사용하여 디렉토리 찾아보기
- **삭제**- 파일 및 디렉토리 제거
- **통계**- 파일 메타데이터 가져오기
- **복사/이동**- 위치 간 파일 복사 또는 이동
- **그렙**- 정규식 패턴을 사용하여 파일 내용 검색

## 지원되는 Provider

사용 가능한 Provider:

- [`LocalFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/local-filesystem): 디스크의 디렉터리에 파일을 저장합니다.
- [`S3Filesystem`](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem): Amazon S3 또는 S3 호환 스토리지(R2, MinIO, Tigris)에 파일을 저장합니다.
- [`GCSFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/gcs-filesystem): Google Cloud Storage에 파일을 저장합니다.
- [`PlatformFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/platform-filesystem): Mastra Platform Workspace 버킷에 파일을 저장합니다.
- [`GoogleDriveFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/google-drive-filesystem): Google Drive 폴더에 파일을 저장합니다.
- [`AzureBlobFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/azure-blob-filesystem): Azure Blob Storage에 파일을 저장합니다.
- [`FilesSDKFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/files-sdk-filesystem): [FilesSDK](https://files-sdk.dev) 어댑터를 통해 원하는 위치에 파일을 저장합니다(S3, R2, GCS, Azure Blob, Vercel Blob, 로컬 파일 시스템 등). 하나의 Provider로 여러 백엔드를 대상으로 지정하려는 경우 유용합니다.
- [`AgentFSFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/agentfs-filesystem): AgentFS를 통해 Turso/SQLite 데이터베이스에 파일을 저장합니다.
- [`MesaFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/mesa-filesystem): 버전이 관리되는 Mesa 저장소에 파일을 저장합니다.
- [`ArchilFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/archil-filesystem): Archil 탄력적 서버리스 디스크에 파일을 저장합니다.

> **팁:** `LocalFilesystem`은 외부 서비스가 필요하지 않으므로 가장 간단하게 시작할 수 있는 방법입니다. 클라우드 스토리지에는 `S3Filesystem`, `GCSFilesystem`, `AzureBlobFilesystem` 중 하나를 사용하세요. 버전 관리 스토리지에는 `MesaFilesystem`을 사용하세요. 외부 서비스 없이 데이터베이스 기반 스토리지를 사용하려면 `AgentFSFilesystem`을 사용하세요.

## 기본 사용법

파일 시스템으로 작업공간을 생성하고 이를 Agent에 할당합니다. 그러면 Agent는 작업의 일부로 파일을 읽고, 쓰고, 관리할 수 있습니다.

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

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
})

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

// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')
```

## 방지

기본적으로 `LocalFilesystem`은 **격리 모드**로 실행되며, 모든 파일 작업은 `basePath` 내부로 제한됩니다. 이를 통해 경로 순회 공격과 심볼릭 링크를 통한 이탈을 방지합니다. 포함 모드에서:

- **상대 경로**(예: `src/index.ts`)는 `basePath`를 기준으로 해석됩니다.
- **절대 경로**(예: `/home/user/.config/file.txt`)는 실제 파일 시스템 경로로 취급됩니다. 경로가 `basePath`와 모든 `allowedPaths` 외부에 있으면 `PermissionError`가 발생합니다.
- **물결표 경로**(예: `~/Documents`)는 홈 디렉터리로 확장되며 동일한 격리 규칙을 따릅니다. Agent가 `basePath` 외부의 특정 경로에 액세스해야 한다면 격리를 완전히 비활성화하는 대신 `allowedPaths`로 액세스 권한을 부여하세요. 상대 경로는 `basePath`를 기준으로 해석되며 절대 경로는 그대로 사용됩니다.

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    allowedPaths: ['~/.claude/skills', '../shared-data'],
  }),
})
```

허용된 경로는 다음을 사용하여 런타임 시 업데이트될 수 있습니다.`setAllowedPaths()` method:

```typescript
// Add a path dynamically
workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])
```

이는 최소 권한 액세스에 권장되는 접근 방식입니다. Agent는 사용자가 허용하는 특정 디렉터리에만 접근할 수 있습니다.

Agent가 전체 파일 시스템에 대한 무제한 액세스가 필요한 경우 포함을 비활성화합니다.

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    contained: false,
  }),
})
```

`contained`가 `false`이면 절대 경로가 아무런 제한 없이 실제 파일 시스템 경로로 취급됩니다.

## 동적 파일 시스템

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

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

const workspace = new Workspace({
  filesystem: ({ requestContext }) => {
    const role = requestContext.get('agent-role') || 'guest'
    return new LocalFilesystem({
      basePath: `/workspaces/${role}`,
      readOnly: role !== 'admin',
    })
  },
})

const agent = new Agent({
  id: 'multi-role-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})
```

각 요청은 작업 공간 Tool 및 작업 공간 지침에 대한 자체 파일 시스템을 확인합니다.

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

// Admin request — reads and writes from /workspaces/admin/
const adminCtx = new RequestContext([['agent-role', 'admin']])
await agent.generate('Write report.txt with Q4 results', { requestContext: adminCtx })

// Viewer request — reads from /workspaces/viewer/, writes are blocked
const viewerCtx = new RequestContext([['agent-role', 'viewer']])
await agent.generate('Read info.txt', { requestContext: viewerCtx })
```

Workspace 지침에도 동일한 `requestContext`가 사용되므로 Agent는 해석된 Provider의 파일 시스템 컨텍스트를 확인할 수 있습니다. 예를 들어 데이터베이스에서 구성을 조회하기 위해 해석기는 비동기식일 수도 있습니다.

```typescript
const workspace = new Workspace({
  filesystem: async ({ requestContext }) => {
    const tenantConfig = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalFilesystem({ basePath: tenantConfig.storagePath })
  },
})
```

> **노트:** `filesystem`과 `mounts`는 함께 사용할 수 없습니다. 같은 Workspace에서 리졸버 함수와 `mounts`를 함께 사용할 수 없습니다.

## 읽기 전용 모드

Agent가 파일을 수정하지 못하도록 하려면 읽기 전용 모드를 활성화하세요.

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    readOnly: true,
  }),
})
```

읽기 전용 정적 파일 시스템을 사용하면 쓰기 Tool(`write_file`, `edit_file`, `delete`, `mkdir`)이 Agent의 Tool 세트에서 완전히 제외됩니다. Agent는 계속해서 파일을 읽고 나열할 수 있습니다. [동적 파일 시스템](#dynamic-filesystem)을 사용할 때는 리졸버가 실행되기 전까지 `readOnly` 값을 알 수 없으므로 쓰기 Tool이 항상 포함됩니다. 대신 런타임에 쓰기 작업이 차단되며, 해석된 파일 시스템이 읽기 전용이면 Tool이 오류를 반환합니다.

## 마운트 및`CompositeFilesystem`

Workspace에서 `mounts` 옵션을 사용하면 Mastra가 경로 접두사를 기준으로 파일 작업을 올바른 Provider에 라우팅하는 `CompositeFilesystem`을 생성합니다.

```typescript
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

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,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
```

이 구성을 사용하면 다음과 같습니다.

- `read_file('/data/input.csv')`는 S3 버킷에서 읽습니다.
- `write_file('/skills/guide.md', content)`는 GCS 버킷에 씁니다.
- `list_directory('/')`는 `/data`와 `/skills`의 가상 항목을 반환합니다.
- Sandbox의 명령은 FUSE 마운트를 통해 `/data`와 `/skills`의 파일에 액세스할 수 있습니다.

### 경로 라우팅

경로가 마운트와 일치하지 않으면 작업이 실패하므로 모든 파일 경로는 마운트 접두사로 시작해야 합니다. 루트 디렉터리(`/`)를 나열하면 각 마운트 지점의 가상 디렉터리 항목이 반환됩니다. 마운트 경로는 중첩할 수 없습니다. 예를 들어 `/data`와 `/data/sub`에 모두 마운트할 수 없습니다.

### `filesystem`대`mounts`

`filesystem`과 `mounts`는 Workspace에서 함께 사용할 수 없는 옵션입니다.

- 단일 스토리지 Provider를 사용하고 Sandbox에 마운트할 필요가 없다면 \*\*`filesystem`\*\*을 사용하세요. Agent에는 Provider를 직접 대상으로 작업하는 파일 Tool이 제공됩니다.
- Sandbox 내부에서 클라우드 스토리지에 액세스해야 하거나 여러 Provider를 결합하려면 \*\*`mounts`\*\*를 사용하세요. Workspace는 파일 Tool을 위한 CompositeFilesystem을 만들고 스토리지를 Sandbox에 FUSE로 마운트합니다. 로컬 개발에서는 일반적으로 `mounts`가 필요하지 않습니다. `LocalFilesystem`과 `LocalSandbox`가 같은 디렉터리를 가리키도록 설정하면 동일한 파일에서 파일 Tool과 명령 실행을 모두 사용할 수 있습니다. 자세한 내용은 [구성 패턴](https://mastra.zisheng.pro/ko/docs/workspace/overview)을 참조하세요.

## Agent Tool

Workspace에서 파일 시스템을 구성하면 Agent에 파일을 읽고, 쓰고, 나열하고, 삭제하는 Tool이 제공됩니다. 자세한 내용은 [Workspace 클래스 레퍼런스](https://mastra.zisheng.pro/ko/reference/workspace/workspace-class)를 참조하세요.

## 관련된

- [로컬파일시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/local-filesystem)
- [S3파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem)
- [GCS파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/gcs-filesystem)
- [GoogleDrive파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/google-drive-filesystem)
- [AzureBlob파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/azure-blob-filesystem)
- [FilesSDK파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/files-sdk-filesystem)
- [AgentFS파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/agentfs-filesystem)
- [메사파일시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/mesa-filesystem)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)
- [모래 상자](https://mastra.zisheng.pro/ko/docs/workspace/sandbox)