@mastra/core/dist/loop/network/run-command-tool.d.ts

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

/**
 * Node.js-specific tool for running shell commands.
 * This file is separated from validation.ts to avoid bundling Node.js
 * dependencies into browser builds.
 *
 * @security WARNING: This tool executes shell commands and can be dangerous.
 * - NEVER use with untrusted input or in multi-tenant environments
 * - Always configure allowedCommands to restrict executable commands
 * - Always set allowedBasePaths to restrict working directories
 * - Consider running in a sandboxed environment (container, VM)
 * - Review all commands that agents may construct before deployment
 */
export interface RunCommandToolOptions {
    /**
     * Allowlist of command prefixes that are permitted.
     * If empty, all non-blocked commands are allowed (less secure).
     * @example ['git', 'npm', 'node', 'ls', 'cat', 'echo']
     */
    allowedCommands?: string[];
    /**
     * Base paths where command execution is permitted.
     * The cwd parameter must resolve to a path under one of these directories.
     * If empty, any cwd is allowed (less secure).
     * @example ['/home/user/projects', '/tmp/workspace']
     */
    allowedBasePaths?: string[];
    /**
     * Additional commands to block beyond the default blocklist.
     */
    additionalBlockedCommands?: string[];
    /**
     * Maximum execution time in milliseconds.
     * @default 30000 (30 seconds)
     */
    maxTimeout?: number;
    /**
     * Maximum buffer size for stdout/stderr in bytes.
     * @default 1048576 (1MB)
     */
    maxBuffer?: number;
    /**
     * Whether to allow potentially dangerous shell metacharacters.
     * Setting this to true is NOT recommended.
     * @default false
     */
    allowUnsafeCharacters?: boolean;
}
/**
 * Creates a tool that lets agents run shell commands with security restrictions.
 *
 * @security WARNING: This tool executes shell commands. Even with restrictions,
 * it should NEVER be used with untrusted input. Always:
 * - Configure allowedCommands to restrict which commands can run
 * - Configure allowedBasePaths to restrict working directories
 * - Review agent prompts to understand what commands may be generated
 * - Consider additional sandboxing (containers, VMs) for production use
 *
 * @example
 * ```typescript
 * // Secure configuration with allowlists
 * const agent = new Agent({
 *   tools: {
 *     runCommand: createRunCommandTool({
 *       allowedCommands: ['git', 'npm', 'node'],
 *       allowedBasePaths: ['/home/user/project'],
 *       maxTimeout: 10000,
 *     }),
 *   },
 * });
 * ```
 */
export declare function createRunCommandTool(options?: RunCommandToolOptions): import("../../tools").Tool<{
    command: string;
    timeout?: number | undefined;
    cwd?: string | undefined;
}, unknown, unknown, unknown, import("../../tools").ToolExecutionContext<unknown, unknown, unknown>, "run-command", unknown>;
//# sourceMappingURL=run-command-tool.d.ts.map