KakaFlow KB

Filesystem

8 phút đọc

Filesystem

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra documentation for configuring filesystem providers on workspaces, enabling agents to read, write, and manage files with tools for file operations.

Insight

Filesystem providers handle all file operations for a Mastra workspace including Read, Write, List, Delete, Stat, Copy/Move, and Grep operations. Supported providers include LocalFilesystem (disk storage), S3Filesystem (Amazon S3/S3-compatible), GCSFilesystem (Google Cloud Storage), GoogleDriveFilesystem, AzureBlobFilesystem, and AgentFSFilesystem (Turso/SQLite database). The filesystem option accepts a static instance or a resolver function that returns a filesystem per request based on requestContext for multi-tenant or role-based access. Containment mode (enabled by default for LocalFilesystem) restricts file operations to basePath and optional allowedPaths, preventing path traversal attacks. Tilde paths (~/Documents) expand to home directory. The setAllowedPaths() method allows runtime updates. Dynamic filesystem resolvers can be synchronous or async (e.g., for database lookups). Read-only mode excludes write tools entirely for static filesystems, while dynamic filesystems block write operations at runtime. The mounts option creates a CompositeFilesystem routing operations by path prefix to different providers. Mount paths must start with a mount prefix, cannot be nested, and filesystem and mounts are mutually exclusive.

Hành động

Create a Workspace with a filesystem provider and assign it to an Agent. For LocalFilesystem: new Workspace({ filesystem: new LocalFilesystem({ basePath: './workspace' }) }). For containment with allowed paths: pass allowedPaths: ['~/.claude/skills', '../shared-data'] array. To disable containment: set contained: false. For dynamic filesystem: pass a resolver function filesystem: ({ requestContext }) => new LocalFilesystem({...}) that returns filesystem per request. For read-only: set readOnly: true. For composite mounts: use mounts: { '/data': new S3Filesystem({...}), '/skills': new GCSFilesystem({...}) }. Pass requestContext to agent.generate() with role or tenant identifiers for dynamic resolution.

Kết quả

Agents configured with a filesystem receive tools for file operations (read_file, write_file, list_directory, delete, stat, cp, mv, grep). Operations are Sản phẩm cấm by containment rules. Dynamic filesystem resolves storage per request based on caller identity.

Điều kiện áp dụng

Requires @mastra/[email protected] or later. LocalFilesystem is default contained mode preventing path traversal. filesystem and mounts options are mutually exclusive.

Nội dung gốc (Original)

Filesystem

Added in: @mastra/[email protected]

Filesystem providers give agents the ability to read, write, and manage files. When you configure a filesystem on a workspace, agents receive tools for file operations.

A filesystem provider handles all file operations for a workspace:

  • Read - Read file contents
  • Write - Create and update files
  • List - Browse directories with optional glob pattern filtering
  • Delete - Remove files and directories
  • Stat - Get file metadata
  • Copy/Move - Copy or move files between locations
  • Grep - Search file contents using regex patterns

Supported providers

Available providers:

Tip: LocalFilesystem is the simplest way to get started as it requires no external services. For cloud storage, use S3Filesystem, GCSFilesystem, or AzureBlobFilesystem. For database-backed storage without external services, use AgentFSFilesystem.

Basic usage

Create a workspace with a filesystem 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-5.4',
  instructions: 'You are a helpful file management assistant.',
  workspace,
})
 
// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')

Containment

By default, LocalFilesystem runs in contained mode — all file operations are restricted to stay within basePath. This prevents path traversal attacks and symlink escapes.

In contained mode:

  • Relative paths (e.g. src/index.ts) resolve against basePath
  • Absolute paths (e.g. /home/user/.config/file.txt) are treated as real filesystem paths — if they fall outside basePath and any allowedPaths, a PermissionError is thrown
  • Tilde paths (e.g. ~/Documents) expand to the home directory and follow the same containment rules

If your agent needs to access specific paths outside basePath, use allowedPaths to grant access without disabling containment entirely. Relative paths are resolved against basePath, and absolute paths are used as-is:

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    allowedPaths: ['~/.claude/skills', '../shared-data'],
  }),
})

Allowed paths can be updated at runtime using the setAllowedPaths() method:

// Add a path dynamically
workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])

This is the recommended approach for least-privilege access — the agent can only reach the specific directories you allow.

If your agent needs unrestricted access to the entire filesystem, disable containment:

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

When contained is false, absolute paths are treated as real filesystem paths with no restriction.

Dynamic filesystem

The filesystem option accepts a resolver function instead of a static instance. The resolver receives requestContext and returns a filesystem per request, allowing a single workspace to serve different filesystems based on the caller’s identity, role, or tenant.

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
 
const workspace = new Workspace({
  filesystem: ({ requestContext }) => {
    const role = requestContext.get('agent-role') || 'guest'
    return new LocalFilesystem({
      basePath: `/workspaces/${role}`,
      readOnly: role !== 'admin',
    })
  },
})
 
const agent = new Agent({
  id: 'multi-role-agent',
  model: 'openai/gpt-4o',
  workspace,
})

Each request resolves its own filesystem at tool execution time:

import { RequestContext } from '@mastra/core/request-context'
 
// Admin request — reads and writes from /workspaces/admin/
const adminCtx = new RequestContext([['agent-role', 'admin']])
await agent.generate('Write report.txt with Q4 results', { requestContext: adminCtx })
 
// Viewer request — reads from /workspaces/viewer/, writes are blocked
const viewerCtx = new RequestContext([['agent-role', 'viewer']])
await agent.generate('Read info.txt', { requestContext: viewerCtx })

The resolver can also be asynchronous, for example to look up configuration from a database:

const workspace = new Workspace({
  filesystem: async ({ requestContext }) => {
    const tenantConfig = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalFilesystem({ basePath: tenantConfig.storagePath })
  },
})

Note: filesystem and mounts are mutually exclusive. You cannot use a resolver function together with mounts in the same workspace.

Read-only mode

To prevent agents from modifying files, enable read-only mode:

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

With a static filesystem, write tools (write_file, edit_file, delete, mkdir) are excluded from the agent’s toolset entirely. The agent can still read and list files.

When using a dynamic filesystem, write tools are always included because readOnly isn’t known until the resolver runs. Instead, write operations are blocked at runtime — the tool returns an error if the resolved filesystem is read-only.

Mounts and CompositeFilesystem

When you use the mounts option on a workspace, Mastra creates a CompositeFilesystem that routes file operations to the correct provider based on path prefix.

import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'
 
const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

With this configuration:

  • read_file('/data/input.csv') reads from the S3 bucket
  • write_file('/skills/guide.md', content) writes to the GCS bucket
  • list_directory('/') returns virtual entries for /data and /skills
  • Commands in the sandbox can access files at /data and /skills via FUSE mounts

Path routing

All file paths must start with a mount prefix. Operations on paths that don’t match any mount will fail. Listing the root directory (/) returns virtual directory entries for each mount point.

Mount paths can’t be nested — for example, you can’t mount at both /data and /data/sub.

filesystem vs mounts

filesystem and mounts are mutually exclusive options on a workspace:

  • Use filesystem when you have a single storage provider and don’t need to mount it into a sandbox. The agent gets file tools that operate directly against the provider.
  • Use mounts when you need cloud storage accessible inside a sandbox, or when you want to combine multiple providers. The workspace creates a CompositeFilesystem for file tools and FUSE-mounts the storage into the sandbox.

For local development, you typically don’t need mounts — a LocalFilesystem and LocalSandbox pointed at the same directory gives you both file tools and command execution on the same files. See configuration patterns for more detail.

Agent tools

When you configure a filesystem on a workspace, agents receive tools for reading, writing, listing, and deleting files. See workspace class reference for details.

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược