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

# ArchilFilesystem

Stocke les fichiers sur les disques élastiques et serverless d'[Archil](https://docs.archil.com). Associe une API objet compatible S3 pour des lectures et écritures rapides à `exec()` pour les opérations de shell POSIX et à `grep()` pour les recherches parallèles côté serveur. Pour en savoir plus sur l'interface, consultez l'[interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem).

## Installation

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## Utilisation

Ajoutez un `ArchilFilesystem` à un Workspace et attribuez-le à un 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,
})
```

### Créer un disque lors de l'initialisation

Si vous ne disposez pas déjà d'un disque, fournissez `createDiskOptions` pour en créer un automatiquement :

```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
```

### Valeurs de repli des variables d'environnement

Lorsque `apiKey` et `region` sont omis, le Provider lit les variables d'environnement suivantes :

- `ARCHIL_API_KEY` : clé API
- `ARCHIL_REGION` : région (par exemple `aws-us-east-1`)
- `ARCHIL_S3_BASE_URL` : point de terminaison S3 personnalisé (facultatif)

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

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

## Paramètres du constructeur

**diskId** (`string`): ID d’un disque Archil existant (par exemple "dsk-0123456789abcdef"). Mutuellement exclusif avec createDiskOptions.

**createDiskOptions** (`CreateDiskRequest`): Options de création d’un disque lors de l’initialisation. Mutuellement exclusif avec diskId.

**apiKey** (`string`): Clé API Archil. Utilise par défaut la variable d’environnement ARCHIL\_API\_KEY.

**region** (`string`): Région Archil (par exemple "aws-us-east-1"). Utilise par défaut la variable d’environnement ARCHIL\_REGION.

**baseUrl** (`string`): URL personnalisée du plan de contrôle Archil (pour les tests ou les déploiements auto-hébergés).

**s3BaseUrl** (`string`): URL personnalisée de l’API compatible S3. Utilise par défaut la variable d’environnement ARCHIL\_S3\_BASE\_URL.

**id** (`string`): Identifiant unique de cette instance de système de fichiers. (Default: `Généré automatiquement`)

**displayName** (`string`): Nom d’affichage lisible dans l’interface utilisateur.

**icon** (`FilesystemIcon`): Identifiant de l’icône dans l’interface utilisateur.

**description** (`string`): Courte description de ce système de fichiers dans l’interface utilisateur.

**readOnly** (`boolean`): Lorsque cette valeur est true, toutes les opérations d’écriture sont bloquées. (Default: `false`)

## Propriétés

**id** (`string`): Identifiant de l’instance du système de fichiers.

**name** (`string`): Nom du Provider ('ArchilFilesystem').

**provider** (`string`): Identifiant du Provider ('archil').

**diskId** (`string | undefined`): ID du disque Archil (disponible après l’initialisation).

**readOnly** (`boolean | undefined`): Indique si le système de fichiers est en mode lecture seule.

## Méthodes

ArchilFilesystem implémente l'[interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem) et fournit toutes les méthodes standard d'un système de fichiers :

- `readFile(path, options?)` : lit le contenu d'un fichier
- `writeFile(path, content, options?)` : écrit du contenu dans un fichier
- `appendFile(path, content)` : ajoute du contenu à un fichier
- `deleteFile(path, options?)` : supprime un fichier
- `copyFile(src, dest, options?)` : copie un fichier
- `moveFile(src, dest, options?)` : déplace ou renomme un fichier
- `mkdir(path, options?)` : crée un répertoire
- `rmdir(path, options?)` : supprime un répertoire
- `readdir(path, options?)` : répertorie le contenu d'un répertoire
- `exists(path)` : vérifie si un chemin existe
- `stat(path)` : récupère les métadonnées d'un fichier ou d'un répertoire

### `init()`

Initialise le système de fichiers. Se connecte au disque existant ou en crée un nouveau.

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

### `getInfo()`

Renvoie les métadonnées de cette instance de système de fichiers.

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

### Méthodes propres à Archil

#### `exec(command)`

Exécute une commande shell sur le disque. Renvoie le code de sortie, stdout et stderr.

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

#### `grep(options)`

Effectue une recherche parallèle côté serveur dans les fichiers du disque.

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

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

Génère une URL signée pour partager un fichier.

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

## Ressources associées

- [Interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem)
- [Référence S3Filesystem](https://mastra.zisheng.pro/fr/reference/workspace/s3-filesystem)
- [Référence GCSFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/gcs-filesystem)
- [Référence AzureBlobFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/azure-blob-filesystem)
- [Documentation Archil](https://docs.archil.com)