@mastra/core
Version:
Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
225 lines • 8.73 kB
TypeScript
/**
* Local Filesystem Provider
*
* A filesystem implementation backed by a folder on the local disk.
* This is the default filesystem for development and local agents.
*/
import type { RequestContext } from '../../request-context/index.js';
import type { ProviderStatus } from '../lifecycle.js';
import type { InstructionsOption } from '../types.js';
import type { FilesystemInfo, FileContent, FileStat, FileEntry, ReadOptions, WriteOptions, ListOptions, RemoveOptions, CopyOptions } from './filesystem.js';
import { MastraFilesystem } from './mastra-filesystem.js';
import type { MastraFilesystemOptions } from './mastra-filesystem.js';
import type { FilesystemMountConfig } from './mount.js';
/**
* Local filesystem provider configuration.
*/
export interface LocalFilesystemOptions extends MastraFilesystemOptions {
/** Unique identifier for this filesystem instance */
id?: string;
/** Base directory path on disk */
basePath: string;
/**
* When true, all file operations are restricted to stay within basePath.
* Prevents path traversal attacks and symlink escapes.
*
* - `contained: true` (default) — File access is restricted to basePath
* (and any allowedPaths). Paths that escape these boundaries throw a
* PermissionError.
* - `contained: false` — No access restrictions. Any path on the host
* filesystem is accessible.
*
* Set to `false` when the filesystem needs to access paths outside basePath,
* such as global skills directories or user home directories.
*
* @default true
*/
contained?: boolean;
/**
* When true, all write operations to this filesystem are blocked.
* Read operations are still allowed.
* @default false
*/
readOnly?: boolean;
/**
* Additional directories the agent can access outside of `basePath`.
*
* Relative paths resolve against `basePath`.
* Absolute and tilde paths are used as-is.
*
* @example
* ```typescript
* new LocalFilesystem({
* basePath: './workspace',
* contained: true,
* allowedPaths: ['../skills', '~/.claude/skills'],
* })
* ```
*/
allowedPaths?: string[];
/**
* Custom instructions that override the default instructions
* returned by `getInstructions()`.
*
* - `string` — Fully replaces the default instructions.
* Pass an empty string to suppress instructions entirely.
* - `(opts) => string` — Receives the default instructions and
* optional request context so you can extend or customise per-request.
*/
instructions?: InstructionsOption;
}
/**
* Mount configuration for local filesystems.
*
* When a `LocalFilesystem` is used as a mount in a Workspace with `LocalSandbox`,
* the sandbox creates a symlink from `<workingDir>/<mountPath>` → `basePath`.
* No FUSE tools are needed for local mounts.
*
* **Note:** When mounted with `contained: false`, the agent can access any
* path on the host filesystem through this mount. Workspace logs a warning
* at construction time if this combination is detected.
*/
export interface LocalMountConfig extends FilesystemMountConfig {
type: 'local';
basePath: string;
}
/**
* Local filesystem implementation.
*
* Stores files in a folder on the user's machine.
* This is the recommended filesystem for development and persistent local storage.
*
* @example
* ```typescript
* import { Workspace, LocalFilesystem } from '@mastra/core';
*
* const workspace = new Workspace({
* filesystem: new LocalFilesystem({ basePath: './my-workspace' }),
* });
*
* await workspace.init();
* await workspace.writeFile('hello.txt', 'Hello World!');
* ```
*/
export declare class LocalFilesystem extends MastraFilesystem {
readonly id: string;
readonly name = "LocalFilesystem";
readonly provider = "local";
readonly readOnly?: boolean;
status: ProviderStatus;
private readonly _basePath;
private readonly _contained;
private _allowedPaths;
private readonly _instructionsOverride?;
/**
* The absolute base path on disk where files are stored.
* Useful for understanding how workspace paths map to disk paths.
*/
get basePath(): string;
/**
* Whether file operations are restricted to stay within basePath.
*
* When `true` (default), relative paths resolve against basePath and
* absolute paths are kept as-is. Any resolved path that falls outside
* basePath (and allowedPaths) throws a PermissionError. When `false`,
* no containment check is applied.
*
* **Note:** When used as a CompositeFilesystem mount with `contained: false`,
* the agent can access any path on the host filesystem through this mount.
*/
get contained(): boolean;
/**
* Current set of resolved allowed paths.
* These paths are permitted beyond basePath when containment is enabled.
*/
get allowedPaths(): readonly string[];
/**
* Update allowed paths. Accepts a direct array or an updater callback
* receiving the current paths (React setState pattern).
*
* @example
* ```typescript
* // Set directly
* fs.setAllowedPaths(['../shared-data']);
*
* // Update with callback
* fs.setAllowedPaths(prev => [...prev, '~/.claude/skills']);
* ```
*/
setAllowedPaths(pathsOrUpdater: string[] | ((current: readonly string[]) => string[])): void;
constructor(options: LocalFilesystemOptions);
/**
* Return mount config for sandbox integration.
* LocalSandbox uses this to create a symlink from the mount path to basePath.
*/
getMountConfig(): LocalMountConfig;
private generateId;
/**
* Check if an absolute path falls within basePath or any allowed path.
*/
private _isWithinRoot;
private _resolvePathForContainment;
private _isWithinAnyRoot;
private toBuffer;
private resolvePath;
/**
* Build the operation string for a containment-violation `PermissionError`.
*
* When the caller passed an absolute path, suggest a concrete relative form
* only when that suffix names an existing entry under the workspace (e.g.
* `/src/app.ts` → `src/app.ts` if `<basePath>/src` exists). Otherwise emit a
* soft hint that doesn't lie about specific paths — agents that mistake `/`
* for the workspace root learn the workspace is sandboxed without us
* inventing a fictitious in-workspace location for `/etc/passwd`.
*/
private _accessOperationHint;
/**
* Resolve a workspace-relative path to an absolute disk path.
* Uses the same resolution logic as internal file operations.
* Returns `undefined` if the path violates containment.
*/
resolveAbsolutePath(inputPath: string): string | undefined;
private toRelativePath;
private assertWritable;
/**
* Verify that the resolved path doesn't escape basePath via symlinks.
* Uses realpath to resolve symlinks and check the actual target.
*/
private assertPathContained;
readFile(inputPath: string, options?: ReadOptions): Promise<string | Buffer>;
writeFile(inputPath: string, content: FileContent, options?: WriteOptions): Promise<void>;
appendFile(inputPath: string, content: FileContent): Promise<void>;
deleteFile(inputPath: string, options?: RemoveOptions): Promise<void>;
copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
private copyDirectory;
moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
mkdir(inputPath: string, options?: {
recursive?: boolean;
}): Promise<void>;
rmdir(inputPath: string, options?: RemoveOptions): Promise<void>;
readdir(inputPath: string, options?: ListOptions): Promise<FileEntry[]>;
exists(inputPath: string): Promise<boolean>;
stat(inputPath: string): Promise<FileStat>;
realpath(inputPath: string): Promise<string>;
/**
* Initialize the local filesystem by creating the base directory.
* Status management is handled by the base class.
*/
init(): Promise<void>;
/**
* Clean up the local filesystem.
* LocalFilesystem doesn't delete files on destroy by default.
* Status management is handled by the base class.
*/
destroy(): Promise<void>;
getInfo(): FilesystemInfo<{
basePath: string;
contained: boolean;
allowedPaths?: string[];
}>;
getInstructions(opts?: {
requestContext?: RequestContext<any>;
}): string;
private _getDefaultInstructions;
}
//# sourceMappingURL=local-filesystem.d.ts.map