@mastra/core/dist/workspace/sandbox/local-sandbox.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

/**
 * Local Sandbox Provider
 *
 * A sandbox implementation that executes commands on the local machine.
 * This is the default sandbox for development and local agents.
 *
 * Supports optional native OS sandboxing:
 * - macOS: Uses seatbelt (sandbox-exec) for filesystem and network isolation
 * - Linux: Uses bubblewrap (bwrap) for namespace isolation
 */
import type { RequestContext } from '../../request-context/index.js';
import type { WorkspaceFilesystem } from '../filesystem/filesystem.js';
import type { MountResult } from '../filesystem/mount.js';
import type { ProviderStatus } from '../lifecycle.js';
import type { InstructionsOption } from '../types.js';
import { LocalProcessManager } from './local-process-manager.js';
import { MastraSandbox } from './mastra-sandbox.js';
import type { MastraSandboxOptions } from './mastra-sandbox.js';
import type { MountManager } from './mount-manager.js';
import type { IsolationBackend, NativeSandboxConfig } from './native-sandbox/index.js';
import type { SandboxInfo } from './types.js';
/** Directory for mount marker files used to detect config changes across restarts. */
export declare const MARKER_DIR: string;
/**
 * Local sandbox provider configuration.
 */
export interface LocalSandboxOptions extends Omit<MastraSandboxOptions, 'processes'> {
    /** Unique identifier for this sandbox instance */
    id?: string;
    /** Working directory for command execution */
    workingDirectory?: string;
    /**
     * Environment variables to set for command execution.
     * PATH is included by default unless overridden (needed for finding executables).
     * Other host environment variables are not inherited unless explicitly passed.
     *
     * @example
     * ```typescript
     * // Default - only PATH is available
     * env: undefined
     *
     * // Add specific variables
     * env: { NODE_ENV: 'production', HOME: process.env.HOME }
     *
     * // Full host environment (less secure)
     * env: process.env
     * ```
     */
    env?: NodeJS.ProcessEnv;
    /** Default timeout for operations in ms (default: 30000) */
    timeout?: number;
    /**
     * Isolation backend for sandboxed execution.
     * - 'none': No sandboxing (direct execution on host) - default
     * - 'seatbelt': macOS sandbox-exec (built-in on macOS)
     * - 'bwrap': Linux bubblewrap (requires installation)
     *
     * Use `LocalSandbox.detectIsolation()` to get the recommended backend.
     * @default 'none'
     */
    isolation?: IsolationBackend;
    /**
     * Configuration for native sandboxing.
     * Only used when isolation is 'seatbelt' or 'bwrap'.
     */
    nativeSandbox?: NativeSandboxConfig;
    /**
     * 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;
}
/**
 * Local sandbox implementation.
 *
 * Executes commands directly on the host machine.
 * This is the recommended sandbox for development and trusted local execution.
 *
 * @example
 * ```typescript
 * import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core';
 *
 * const workspace = new Workspace({
 *   filesystem: new LocalFilesystem({ basePath: './my-workspace' }),
 *   sandbox: new LocalSandbox({ workingDirectory: './my-workspace' }),
 * });
 *
 * await workspace.init();
 * const result = await workspace.executeCommand('node', ['script.js']);
 * ```
 */
export declare class LocalSandbox extends MastraSandbox {
    readonly id: string;
    readonly name = "LocalSandbox";
    readonly provider = "local";
    status: ProviderStatus;
    readonly workingDirectory: string;
    readonly isolation: IsolationBackend;
    readonly processes: LocalProcessManager;
    readonly mounts: MountManager;
    private readonly env;
    private _nativeSandboxConfig;
    private _seatbeltProfile?;
    private _seatbeltProfilePath?;
    private _sandboxFolderPath?;
    private _userProvidedProfilePath;
    private readonly _createdAt;
    private readonly _instructionsOverride?;
    private _activeMountPaths;
    /** Snapshot of `readWritePaths` from ctor; entries here are never removed on unmount. */
    private readonly _initialReadWritePaths;
    /** Refcount for isolation paths added by mounts (not present in `_initialReadWritePaths`). */
    private _mountIsolationRefCount;
    /** Normalized mount path → canonical isolation path recorded for that mount. */
    private _mountPathToIsolationPath;
    constructor(options?: LocalSandboxOptions);
    /**
     * Start the local sandbox.
     * Creates working directory and sets up seatbelt profile if using macOS isolation.
     * Status management is handled by the base class.
     */
    start(): Promise<void>;
    /**
     * Stop the local sandbox.
     * Unmounts all active mounts before stopping.
     * Status management is handled by the base class.
     */
    stop(): Promise<void>;
    /**
     * Destroy the local sandbox and clean up resources.
     * Unmounts all filesystems, clears mount state, and cleans up seatbelt profile.
     * Status management is handled by the base class.
     */
    destroy(): Promise<void>;
    /** @deprecated Use `status === 'running'` instead. */
    isReady(): Promise<boolean>;
    getInfo(): Promise<SandboxInfo>;
    getInstructions(opts?: {
        requestContext?: RequestContext;
    }): string;
    private _getDefaultInstructions;
    private generateId;
    /**
     * Build the environment object for execution.
     * Always includes PATH by default (needed for finding executables).
     * Merges the sandbox's configured env with any additional env from the command.
     * @internal Used by LocalProcessManager.
     */
    buildEnv(additionalEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
    /**
     * Mount a filesystem at a path on the local host.
     *
     * - **local** — Creates a symlink from `<workingDir>/<mount>` to the basePath.
     *
     * Virtual mount paths (e.g. `/s3`) are resolved under the sandbox's workingDirectory.
     * Other mount types can be handled via the `onMount` hook.
     */
    mount(filesystem: WorkspaceFilesystem, mountPath: string): Promise<MountResult>;
    /**
     * Unmount a filesystem from a path.
     */
    unmount(mountPath: string): Promise<void>;
    /**
     * Write a marker file for detecting config changes.
     * Uses hostPath (resolved OS path) for the marker filename and content,
     * and mountPath (virtual path) for looking up the entry.
     */
    private writeMarkerFile;
    /**
     * Check if a path is already mounted and if the config matches.
     * Uses hostPath (resolved OS path) for checking the actual mount point.
     */
    private checkExistingMount;
    /**
     * Check if a marker file exists for a given host path (regardless of content).
     * Returns true if we previously created a mount here.
     */
    private hasMarkerFile;
    /**
     * Check if a marker file matches the given config.
     * Returns 'matching' if hash matches, 'mismatched' if hash differs,
     * or 'foreign' if no marker exists (we didn't create this mount).
     */
    private checkMarkerFile;
    /**
     * Dynamically add a mount path to the sandbox isolation allowlist.
     *
     * - Seatbelt: pushes to readWritePaths, regenerates inline profile
     * - Bwrap: pushes to readWritePaths (buildBwrapCommand reads config each call)
     *
     * Local mounts are symlinks under `workingDirectory`. Bubblewrap cannot
     * `--bind` a symlink (it fails with "Unable to mount source on destination"),
     * so we store the canonical path (`realpath`) of the mount point — the same
     * directory the symlink refers to.
     */
    private addMountPathToIsolation;
    /**
     * Reverse {@link addMountPathToIsolation}: drop refcounted paths from the allowlist on unmount
     * while preserving user-provided `readWritePaths` from construction.
     */
    private removeMountIsolationForPath;
    /**
     * Resolve a virtual mount path to a host filesystem path.
     *
     * Virtual paths like "/s3" become `<workingDir>/s3`. This differs from E2B
     * where root-level paths like `/s3` are used directly (E2B runs in a VM with sudo).
     * LocalSandbox runs on the host, so mounts are scoped under workingDirectory.
     */
    private resolveHostPath;
    /**
     * Wrap a command with the configured isolation backend.
     * @internal Used by LocalProcessManager for background process isolation.
     */
    wrapCommandForIsolation(command: string): {
        command: string;
        args: string[];
    };
    /**
     * Detect the best available isolation backend for this platform.
     * Returns detection result with backend recommendation and availability.
     *
     * @example
     * ```typescript
     * const result = LocalSandbox.detectIsolation();
     * const sandbox = new LocalSandbox({
     *   isolation: result.available ? result.backend : 'none',
     * });
     * ```
     */
    static detectIsolation(): import("./native-sandbox").SandboxDetectionResult;
}
//# sourceMappingURL=local-sandbox.d.ts.map