Give a Mastra agent persistent file storage with Archil

A working agent writes files constantly: reports, datasets, build outputs. By default those files sit in a sandbox that gets wiped the second the run ends.

That's fine for a one-shot agent, but it's a problem for agents that keep running. Durable agents survive client disconnects and network blips. Task lists keep an agent on track through long-running, multi-step work. An agent that runs for hours, or picks up where it left off tomorrow, needs its files to outlive the run too. Resumable execution on top of disposable storage only gets you halfway.

The @mastra/archil integration attaches an Archil disk to your agent's workspace: persistent file storage, backed by your own S3, that an agent can read, write, run code on, and search in place.

Attach a disk, get a workspace

A Mastra Workspace is where an agent's files and shell live. ArchilFilesystem makes that workspace an Archil disk.

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ArchilFilesystem } from '@mastra/archil'
 
const filesystem = new ArchilFilesystem({
  diskId: 'dsk-0123456789abcdef',
  apiKey: process.env.ARCHIL_API_KEY,
  region: 'aws-us-east-1',
})
 
const workspace = new Workspace({ filesystem })
 
const agent = new Agent({
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-8',
  workspace,
})

Point it at an existing diskId and the agent picks up every file from the last run. Don't have a disk yet? Pass createDiskOptions instead, and init() makes one. Either way the files are still there next time the agent runs.

Run code where the files already live

Object storage gives you readFile and writeFile. Archil gives those too, plus three methods for working directly on the disk:

exec() runs a shell command on the disk. Run Python, Node, or Bash against the files server-side, without shipping them anywhere:

const result = await filesystem.exec('python analyze.py /data/run-47.csv')
// { exitCode: 0, stdout: '…', stderr: '' }

grep() searches across the disk in parallel. An agent resuming a long job can find what an earlier run wrote instead of re-deriving it:

const { matches } = await filesystem.grep({
  directory: '/reports',
  pattern: 'ERROR',
  recursive: true,
  glob: '*.log',
})

And share() hands a file off as a signed URL, so the output of one run becomes a link you (or a teammate, or another agent) can open:

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

Why this disk and not a folder in S3

You could bolt an agent onto a raw S3 bucket. You'd then wait for large objects to download before the agent could touch them, manage capacity by hand, and write your own plumbing to move data back and forth.

Archil exists so you don't have to. It turns an S3 bucket into a local-feeling filesystem with full POSIX semantics (renames, appends, locking), so code written against a normal filesystem works unchanged. Reads and writes come back roughly 30x faster than hitting S3 directly, you only pay for the data you're actively using, and edits flow back to the bucket within minutes. A data-heavy agent working over a multi-gigabyte dataset or a pile of model weights can start right away instead of sitting through a download first.

Get started

npm install @mastra/archil

Set ARCHIL_API_KEY and ARCHIL_REGION, attach the filesystem to a workspace, and your agent has storage that outlasts the run. The ArchilFilesystem reference has the full API.