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

# Archil파일 시스템

다음에 파일을 저장합니다.[Archil](https://docs.archil.com)탄력적인 서버리스 디스크. 빠른 읽기/쓰기를 위해 S3 호환 개체 API를 결합합니다.`exec()`POSIX 쉘 작업 및`grep()`병렬 서버 측 검색의 경우. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[Workspace파일 시스템 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/filesystem).

## 설치

**npm**:

```bash
npm install @mastra/archil
```

**pnpm**:

```bash
pnpm add @mastra/archil
```

**Yarn**:

```bash
yarn add @mastra/archil
```

**Bun**:

```bash
bun add @mastra/archil
```

## 용법

Workspace에 `ArchilFilesystem`을 추가하고 Agent에 할당하세요.

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ArchilFilesystem } from '@mastra/archil'

const workspace = new Workspace({
  filesystem: new ArchilFilesystem({
    diskId: 'dsk-0123456789abcdef',
    apiKey: process.env.ARCHIL_API_KEY,
    region: 'aws-us-east-1',
  }),
})

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

### 초기화 시 새 디스크 만들기

기존 디스크가 없으면 `createDiskOptions`를 제공하여 자동으로 생성하세요.

```typescript
import { ArchilFilesystem } from '@mastra/archil'

const filesystem = new ArchilFilesystem({
  apiKey: process.env.ARCHIL_API_KEY,
  region: 'aws-us-east-1',
  createDiskOptions: {
    name: 'my-agent-workspace',
  },
})

await filesystem.init()
// filesystem.diskId now contains the newly created disk ID
```

### 환경 변수 대체

`apiKey`와 `region`을 생략하면 Provider가 환경 변수에서 값을 읽습니다.

- `ARCHIL_API_KEY`- API 키
- `ARCHIL_REGION`- 지역(예:`aws-us-east-1`)
- `ARCHIL_S3_BASE_URL`- 사용자 정의 S3 엔드포인트(선택 사항)

```typescript
import { ArchilFilesystem } from '@mastra/archil'

// Uses ARCHIL_API_KEY and ARCHIL_REGION from environment
const filesystem = new ArchilFilesystem({
  diskId: 'dsk-0123456789abcdef',
})
```

## 생성자 매개변수

**diskId** (`string`): 기존 Archil 디스크 ID(예: "dsk-0123456789abcdef")입니다. createDiskOptions와 함께 사용할 수 없습니다.

**createDiskOptions** (`CreateDiskRequest`): 초기화 시 새 디스크를 생성하기 위한 옵션입니다. diskId와 함께 사용할 수 없습니다.

**apiKey** (`string`): Archil API 키입니다. 지정하지 않으면 ARCHIL\_API\_KEY 환경 변수를 사용합니다.

**region** (`string`): Archil 리전입니다(예: "aws-us-east-1"). 지정하지 않으면 ARCHIL\_REGION 환경 변수를 사용합니다.

**baseUrl** (`string`): 사용자 지정 Archil 제어 플레인 URL입니다(테스트 또는 자체 호스팅 배포용).

**s3BaseUrl** (`string`): 사용자 지정 S3 호환 API URL입니다. 지정하지 않으면 ARCHIL\_S3\_BASE\_URL 환경 변수를 사용합니다.

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

**displayName** (`string`): UI에 표시할 사용자 친화적인 이름입니다.

**icon** (`FilesystemIcon`): UI에 사용할 아이콘 식별자입니다.

**description** (`string`): UI에 표시할 이 파일 시스템의 짧은 설명입니다.

**readOnly** (`boolean`): true이면 모든 쓰기 작업이 차단됩니다. (Default: `false`)

## 속성

**id** (`string`): 파일 시스템 인스턴스 식별자입니다.

**name** (`string`): Provider 이름입니다('ArchilFilesystem').

**provider** (`string`): Provider 식별자입니다('archil').

**diskId** (`string | undefined`): Archil 디스크 ID입니다(init 후 사용 가능).

**readOnly** (`boolean | undefined`): 파일 시스템이 읽기 전용 모드인지 여부입니다.

## 행동 양식

ArchilFilesystem은 다음을 구현합니다.[WorkspaceFilesystem interface](https://mastra.zisheng.pro/ko/reference/workspace/filesystem), providing all standard filesystem methods:

- `readFile(path, options?)`- 파일 내용 읽기
- `writeFile(path, content, options?)`- 파일에 콘텐츠 쓰기
- `appendFile(path, content)`- 파일에 콘텐츠 추가
- `deleteFile(path, options?)`- 파일 삭제
- `copyFile(src, dest, options?)`- 파일 복사
- `moveFile(src, dest, options?)`- 파일 이동 또는 이름 바꾸기
- `mkdir(path, options?)`- 디렉토리 생성
- `rmdir(path, options?)`- 디렉토리 제거
- `readdir(path, options?)`- 디렉토리 내용 나열
- `exists(path)`- 경로가 존재하는지 확인
- `stat(path)`- 파일 또는 디렉터리 메타데이터 가져오기

### `init()`

파일 시스템을 초기화합니다. 기존 디스크에 연결하거나 새 디스크를 만듭니다.

```typescript
await filesystem.init()
```

### `getInfo()`

이 파일 시스템 인스턴스에 대한 메타데이터를 반환합니다.

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'ArchilFilesystem', provider: 'archil', status: 'ready' }
```

### Archil 관련 방법

#### `exec(command)`

디스크에서 쉘 명령을 실행하십시오. 종료 코드, stdout 및 stderr를 반환합니다.

```typescript
const result = await filesystem.exec('ls -la /data')
// { exitCode: 0, stdout: '...', stderr: '' }
```

#### `grep(options)`

디스크의 파일 전체에 대해 병렬 서버측 검색을 실행합니다.

```typescript
const results = await filesystem.grep({
  directory: '/logs',
  pattern: 'ERROR',
  recursive: true,
  glob: '*.log',
})
// { matches: [...], stoppedReason: null }
```

#### `share(path, options?)`

파일 공유를 위해 서명된 URL을 생성합니다.

```typescript
const { url } = await filesystem.share('/reports/output.pdf', {
  expiresIn: 3600,
})
```

## 관련된

- [WorkspaceFilesystem 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/filesystem)
- [S3파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/s3-filesystem)
- [GCS파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/gcs-filesystem)
- [AzureBlob파일 시스템 참조](https://mastra.zisheng.pro/ko/reference/workspace/azure-blob-filesystem)
- [Archil 문서](https://docs.archil.com)