ArchilFilesystem

Stores files on Archil elastic, serverless disks. Combines an S3-compatible object API for fast reads/writes with exec() for POSIX shell operations and grep() for parallel server-side search.

info

For interface details, see WorkspaceFilesystem Interface.

Installation

npm

npm install @mastra/archil

pnpm

pnpm add @mastra/archil

Yarn

yarn add @mastra/archil

Bun

bun add @mastra/archil

Usage

Add an ArchilFilesystem to a workspace and assign it to an agent:

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({
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

Creating a new disk on init

If you don't have an existing disk, provide createDiskOptions to create one automatically:

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

Environment variable fallbacks

When apiKey and region are omitted, the provider reads from environment variables:

• ARCHIL_API_KEY - API key
• ARCHIL_REGION - Region (e.g. aws-us-east-1)
• ARCHIL_S3_BASE_URL - Custom S3 endpoint (optional)

import { ArchilFilesystem } from '@mastra/archil'

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

Constructor parameters

diskId?:

string

Existing Archil disk ID (e.g. "dsk-0123456789abcdef"). Mutually exclusive with `createDiskOptions`.

createDiskOptions?:

CreateDiskRequest

Options for creating a new disk on init. Mutually exclusive with `diskId`.

apiKey?:

string

Archil API key. Falls back to `ARCHIL_API_KEY` environment variable.

region?:

string

Archil region (e.g. "aws-us-east-1"). Falls back to `ARCHIL_REGION` environment variable.

baseUrl?:

string

Custom Archil control-plane URL (for testing or self-hosted deployments).

s3BaseUrl?:

string

Custom S3-compatible API URL. Falls back to `ARCHIL_S3_BASE_URL` environment variable.

id?:

string

= Auto-generated

Unique identifier for this filesystem instance.

displayName?:

string

Human-friendly display name for the UI.

icon?:

FilesystemIcon

Icon identifier for the UI.

description?:

string

Short description of this filesystem for the UI.

readOnly?:

boolean

= false

When true, all write operations are blocked.

Properties

id:

string

Filesystem instance identifier.

name:

string

Provider name ('ArchilFilesystem').

provider:

string

Provider identifier ('archil').

diskId:

string | undefined

The Archil disk ID (available after init).

readOnly:

boolean | undefined

Whether the filesystem is in read-only mode.

Methods

ArchilFilesystem implements the WorkspaceFilesystem interface, providing all standard filesystem methods:

• readFile(path, options?) - Read file contents
• writeFile(path, content, options?) - Write content to a file
• appendFile(path, content) - Append content to a file
• deleteFile(path, options?) - Delete a file
• copyFile(src, dest, options?) - Copy a file
• moveFile(src, dest, options?) - Move or rename a file
• mkdir(path, options?) - Create a directory
• rmdir(path, options?) - Remove a directory
• readdir(path, options?) - List directory contents
• exists(path) - Check if a path exists
• stat(path) - Get file or directory metadata

init()

Initialize the filesystem. Connects to the existing disk or creates a new one.

await filesystem.init()

getInfo()

Returns metadata about this filesystem instance.

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

Archil-specific methods

exec(command)

Run a shell command on the disk. Returns exit code, stdout, and stderr.

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

grep(options)

Run a parallel server-side search across files on the disk.

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

share(path, options?)

Generate a signed URL for sharing a file.

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

Related

• WorkspaceFilesystem interface
• S3Filesystem reference
• GCSFilesystem reference
• AzureBlobFilesystem reference
• Archil documentation