LocalFilesystem

Added in: @mastra/core@1.1.0

Stores files in a directory on the local filesystem. For interface details, see WorkspaceFilesystem Interface.

Usage

Add a LocalFilesystem to a workspace and assign it to an agent. The agent can then read, write, and manage files as part of its tasks:

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  model: 'openai/gpt-6.1-sol',
  workspace,
})

// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')

Constructor parameters

basePath:

string

Base directory path on disk. All file paths are resolved relative to this directory.

id?:

string

= Auto-generated

Unique identifier for this filesystem instance

contained?:

boolean

= true

When true, all file operations are restricted to stay within basePath. Prevents path traversal attacks and symlink escapes. See containment.

allowedPaths?:

string[]

= []

Additional directories the agent can access outside of basePath.

instructions?:

string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)

Custom instructions that override the default instructions returned by getInstructions(). Pass a string to fully replace them, or a function to extend them with access to the current requestContext for per-request customization.

readOnly?:

boolean

= false

When true, all write operations are blocked. Read operations are still allowed.

Properties

id:

string

Filesystem instance identifier

name:

string

Provider name ('LocalFilesystem')

provider:

string

Provider identifier ('local')

basePath:

string

The absolute base path on disk

readOnly:

boolean | undefined

Whether the filesystem is in read-only mode

allowedPaths:

readonly string[]

Current set of resolved allowed paths. These paths are permitted beyond basePath when containment is enabled.

Methods

init()

Initialize the filesystem. Creates the base directory if it doesn't exist.

await filesystem.init()

Called by workspace.init().

Lazy initialization

LocalFilesystem initializes on first operation if not already initialized, creating the base directory automatically. Calling init() explicitly is optional but can be useful to pre-create directories before the first operation.

destroy()

Clean up filesystem resources.

await filesystem.destroy()

Called by workspace.destroy().

setAllowedPaths(pathsOrUpdater)

Update the allowed paths at runtime. Accepts a new paths array (replaces current) or an updater callback that receives the current paths and returns the new set.

// Set directly
filesystem.setAllowedPaths(['/home/user/.config'])

// Update with callback
filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])

// Clear all allowed paths
filesystem.setAllowedPaths([])

Parameters:

pathsOrUpdater:

string[] | ((current: readonly string[]) => string[])

New allowed paths array or updater function receiving current paths

readFile(path, options?)

Read file contents.

const content = await filesystem.readFile('docs/guide.md', { encoding: 'utf-8' })
const buffer = await filesystem.readFile('image.png')

Parameters:

path:

string

File path relative to basePath

options?:

Options

Configuration options.

Options

encoding?:

BufferEncoding

Text encoding (for example 'utf-8'). When omitted, the file is returned as a Buffer.

writeFile(path, content, options?)

Write content to a file.

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

File content

options?:

Options

Configuration options.

Options

recursive?:

boolean

Create parent directories if they don't exist

overwrite?:

boolean

Overwrite existing file

expectedMtime?:

Date

If provided, the write fails with a StaleFileError when the file's current modification time doesn't match. Use this for optimistic concurrency control to detect external modifications between read and write.

appendFile(path, content)

Append content to an existing file.

await filesystem.appendFile('logs/app.log', 'New log entry\n')

Parameters:

path:

string

File path relative to basePath

content:

string | Buffer | Uint8Array

Content to append

deleteFile(path, options?)

Delete a file.

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?:

Options

Configuration options.

Options

force?:

boolean

Don't throw error if file doesn't exist

copyFile(src, dest, options?)

Copy a file to a new location.

await filesystem.copyFile('docs/template.md', 'docs/new-doc.md')
await filesystem.copyFile('src/config.json', 'backup/config.json', { overwrite: false })

Parameters:

src:

string

Source file path

dest:

string

Destination file path

options?:

Options

Configuration options.

Options

overwrite?:

boolean

Overwrite destination if it exists

moveFile(src, dest, options?)

Move or rename a file.

await filesystem.moveFile('docs/draft.md', 'docs/final.md')
await filesystem.moveFile('temp/upload.txt', 'files/document.txt')

Parameters:

src:

string

Source file path

dest:

string

Destination file path

options?:

Options

Configuration options.

Options

overwrite?:

boolean

Overwrite destination if it exists

mkdir(path, options?)

Create a directory.

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

Parameters:

path:

string

Directory path

options?:

Options

Configuration options.

Options

recursive?:

boolean

Create parent directories

rmdir(path, options?)

Remove a directory.

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

Parameters:

path:

string

Directory path

options?:

Options

Configuration options.

Options

recursive?:

boolean

Remove contents recursively

force?:

boolean

Don't throw if directory doesn't exist

readdir(path, options?)

List directory contents.

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

// List the basePath root
const rootEntries = await filesystem.readdir('.')

exists(path)

Check if a path exists.

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

stat(path)

Get file or directory metadata.

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

getInfo()

Returns metadata about this filesystem instance.

const info = filesystem.getInfo()
// { id: '...', name: 'LocalFilesystem', provider: 'local', basePath: '/workspace', readOnly: false }

getInstructions(opts?)

Returns a description of how paths work in this filesystem. When assigned to an agent, this is injected into the agent's system message.

const instructions = filesystem.getInstructions()
// 'Local filesystem at "/workspace". Relative paths resolve from this directory. File access is restricted to this directory.'

Pass requestContext to enable per-request customization when the instructions constructor option is a function:

const instructions = filesystem.getInstructions({ requestContext })

Parameters:

opts.requestContext?:

RequestContext

Forwarded to the instructions function if one was provided in the constructor.

Returns: string

To override the default output, pass an instructions option to the constructor. See constructor parameters.

Path resolution

How basePath works

The basePath option sets the root directory for all file operations. Paths passed to methods like readFile() are resolved as follows:

• Relative paths are resolved against basePath: docs/guide.md → <basePath>/docs/guide.md
• Use . to refer to the root of basePath, for example readdir('.')
• Absolute paths are treated as host paths, not as paths inside basePath. With the default contained: true, any absolute path that falls outside basePath and the configured allowedPaths is rejected with a PermissionError
• ~ expands to the user's home directory, so it's also a host path and is subject to the same containment rules

const filesystem = new LocalFilesystem({
  basePath: './workspace',
})

// Resolves to ./workspace/docs/guide.md
await filesystem.readFile('docs/guide.md')
await filesystem.readFile('./docs/guide.md')

// Root of basePath
await filesystem.readdir('.')

// Throws a PermissionError with the default contained: true
await filesystem.readFile('/docs/guide.md')

To read host absolute paths outside basePath, add them to allowedPaths or set contained: false. Prefer allowedPaths when only a few external directories are needed.

const filesystem = new LocalFilesystem({
  basePath: './workspace',
  allowedPaths: ['/home/user/shared-docs'],
})

await filesystem.readFile('/home/user/shared-docs/guide.md')

Mounted filesystems

When a LocalFilesystem is mounted in a workspace through CompositeFilesystem, workspace-facing paths include the mount prefix. For example, with a mount at /workspace, the workspace path /workspace/report.md is passed to the underlying filesystem as report.md, relative to its basePath. See Filesystem mounts for mount configuration.

Relative paths and execution context

When you use a relative path for basePath, it resolves from process.cwd(). In Mastra projects, the cwd changes based on how you run your code:

Context	Working directory	./workspace resolves to
mastra dev	./src/mastra/public/	./src/mastra/public/workspace
mastra start	./.mastra/output/	./.mastra/output/workspace
Direct script	Where you ran the command	Relative to that location

This can cause confusion when the same relative path resolves to different locations.

Recommended: Use absolute paths

For consistent paths across all execution contexts, use an environment variable with an absolute path:

import { LocalFilesystem } from '@mastra/core/workspace'

const filesystem = new LocalFilesystem({
  basePath: process.env.WORKSPACE_PATH!,
})

Set WORKSPACE_PATH in your environment to an absolute path like /home/user/my-project/workspace. It ensures the workspace path is consistent regardless of how you run your code.

Related

• WorkspaceFilesystem interface
• Workspace class
• Sandbox