# WorkspaceFilesystem Interface

The `WorkspaceFilesystem` interface defines how workspaces interact with file storage.

## Methods

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

Read file contents.

```typescript
const content = await filesystem.readFile('/docs/guide.md');
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' });
```

**Parameters:**

### path:

string

File path relative to basePath

### options.encoding?:

'utf-8' | 'binary'

Text or binary encoding

**Returns:** `Promise<string | Buffer>`

### `writeFile(path, content, options?)`

Write file contents.

```typescript
await filesystem.writeFile('/docs/new.md', '# New Document');
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true });
```

**Parameters:**

### path:

string

File path relative to basePath

### content:

string | Buffer

File content

### options.recursive?:

boolean

Create parent directories if they don't exist

### options.overwrite?:

boolean

Overwrite existing file

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

Delete a file.

```typescript
await filesystem.deleteFile('/docs/old.md');
await filesystem.deleteFile('/docs/maybe.md', { force: true }); // Don't throw if missing
```

**Parameters:**

### path:

string

File path

### options.force?:

boolean

Don't throw error if file doesn't exist

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

List directory contents.

```typescript
const entries = await filesystem.readdir('/docs');
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
```

**Returns:** `Promise<FileEntry[]>`

```typescript
interface FileEntry {
  name: string;
  type: 'file' | 'directory';
  size?: number;
  modifiedAt?: Date;
}
```

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

Create a directory.

```typescript
await filesystem.mkdir('/docs/api');
await filesystem.mkdir('/deeply/nested/path', { recursive: true });
```

**Parameters:**

### path:

string

Directory path

### options.recursive?:

boolean

Create parent directories

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

Remove a directory.

```typescript
await filesystem.rmdir('/docs/old');
await filesystem.rmdir('/docs/nested', { recursive: true });
```

**Parameters:**

### path:

string

Directory path

### options.recursive?:

boolean

Remove contents recursively

### options.force?:

boolean

Don't throw if directory doesn't exist

### `exists(path)`

Check if a path exists.

```typescript
const exists = await filesystem.exists('/docs/guide.md');
```

**Returns:** `Promise<boolean>`

### `stat(path)`

Get file or directory metadata.

```typescript
const stat = await filesystem.stat('/docs/guide.md');
// { type: 'file', size: 1234, modifiedAt: Date, createdAt: Date, path: '/docs/guide.md' }
```

**Returns:** `Promise<FileStat>`

```typescript
interface FileStat {
  type: 'file' | 'directory';
  size: number;
  modifiedAt: Date;
  createdAt: Date;
  path: string;
}
```

## Optional Methods

### `init()`

Initialize the filesystem. Called by `workspace.init()`.

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

### `destroy()`

Clean up resources. Called by `workspace.destroy()`.

```typescript
await filesystem.destroy?.();
```

### `getInfo()`

Get filesystem metadata.

```typescript
const info = await filesystem.getInfo?.();
// { id, name, provider, basePath, readOnly, status, storage? }
```

**Returns:** `Promise<FilesystemInfo>`

```typescript
interface FilesystemInfo {
  id: string;
  name: string;
  provider: string;
  basePath?: string;
  readOnly?: boolean;
  status?: string;
  storage?: {
    totalBytes?: number;
    usedBytes?: number;
    availableBytes?: number;
  };
}
```

### `getInstructions()`

Get a description of how this filesystem works. Used in tool descriptions to help agents understand path semantics.

```typescript
const instructions = filesystem.getInstructions?.();
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
```

**Returns:** `string`

## Related

- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class/llms.txt)
- [Sandbox Interface](https://mastra.ai/reference/workspace/sandbox/llms.txt)