just-bash-mcp 2.6.0 → 2.8.0

package/package.json

@@ -1,33 +1,33 @@
 {
 	"name": "just-bash-mcp",
-	"version": "2.6.0",
+	"version": "2.8.0",
 	"description": "MCP server providing a sandboxed bash environment using just-bash",
 	"type": "module",
-	"main": "./build/index.js",
-	"types": "./build/index.d.ts",
+	"main": "./src/index.ts",
 	"exports": {
 		".": {
-			"types": "./build/index.d.ts",
-			"import": "./build/index.js"
+			"import": "./src/index.ts"
 		}
 	},
 	"bin": {
-		"just-bash-mcp": "build/index.js"
+		"just-bash-mcp": "src/index.ts"
 	},
 	"files": [
-		"build",
+		"src",
+		"tsconfig.json",
 		"README.md",
 		"LICENSE"
 	],
 	"scripts": {
-		"build": "tsc",
-		"start": "node build/index.js",
-		"dev": "bun src/index.ts",
-		"typecheck": "bun tsc --noEmit",
-		"lint": "bunx @biomejs/biome@latest lint",
-		"format": "bunx @biomejs/biome@latest format --write",
-		"check": "bunx @biomejs/biome@latest check --write",
-		"prepublishOnly": "bun run build"
+		"start": "node src/index.ts",
+		"dev": "node --watch src/index.ts",
+		"lint": "oxlint --type-aware",
+		"lint:fix": "oxlint --type-aware --fix",
+		"typecheck": "oxlint --type-aware --type-check",
+		"format": "oxfmt --write src/",
+		"format:check": "oxfmt --check src/",
+		"check": "oxlint --type-aware --type-check && oxfmt --check src/",
+		"ci": "oxlint --type-aware --type-check && oxfmt --check src/"
 	},
 	"keywords": [
 		"mcp",
@@ -56,16 +56,18 @@
 	},
 	"homepage": "https://github.com/dalist1/just-bash-mcp#readme",
 	"engines": {
-		"node": ">=18.0.0"
+		"node": ">=22.0.0"
 	},
+	"packageManager": "bun@1.3.8",
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.25.2",
-		"just-bash": "^2.7.0",
-		"zod": "^4.3.5"
+		"@modelcontextprotocol/sdk": "^1.26.0",
+		"just-bash": "^2.9.6",
+		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.3.11",
-		"@types/node": "^25.0.6",
-		"typescript": "^5.9.3"
+		"@types/node": "^25.2.1",
+		"oxfmt": "^0.28.0",
+		"oxlint": "^1.43.0",
+		"oxlint-tsgolint": "^0.11.4"
 	}
 }

package/src/config/index.ts

@@ -0,0 +1,358 @@
+/**
+ * Configuration module for just-bash-mcp
+ * Handles environment variable parsing and configuration building
+ */
+
+import {
+	type BashLogger,
+	type BashOptions,
+	type CommandName,
+	InMemoryFs,
+	MountableFs,
+	type MountConfig,
+	type NetworkConfig,
+	OverlayFs,
+	ReadWriteFs,
+} from "just-bash";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+
+export interface TraceEvent {
+	category: string;
+	name: string;
+	durationMs: number;
+	details?: Record<string, unknown>;
+}
+
+export type TraceCallback = (event: TraceEvent) => void;
+
+// ============================================================================
+// Environment Variable Parsing
+// ============================================================================
+
+function parseEnvString(key: string, defaultValue: string): string {
+	return process.env[key] || defaultValue;
+}
+
+function parseEnvBoolean(key: string, defaultValue: boolean): boolean {
+	return process.env[key] === "true" ? true : defaultValue;
+}
+
+function parseEnvInt(key: string, defaultValue: number): number {
+	const value = process.env[key];
+	if (!value) return defaultValue;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? defaultValue : parsed;
+}
+
+function parseEnvStringArray(key: string): string[] {
+	return process.env[key]?.split(",").filter(Boolean) || [];
+}
+
+// ============================================================================
+// Configuration Constants
+// ============================================================================
+
+export interface Config {
+	readonly VERSION: string;
+	readonly SERVER_NAME: string;
+	readonly OVERLAY_ROOT: string | undefined;
+	readonly READ_WRITE_ROOT: string | undefined;
+	readonly MOUNTS_CONFIG: string | undefined;
+	readonly INITIAL_CWD: string;
+	readonly ALLOW_NETWORK: boolean;
+	readonly ALLOWED_URL_PREFIXES: string[];
+	readonly ALLOWED_METHODS: HttpMethod[];
+	readonly MAX_REDIRECTS: number;
+	readonly NETWORK_TIMEOUT_MS: number;
+	readonly MAX_RESPONSE_SIZE: number | undefined;
+	readonly MAX_CALL_DEPTH: number;
+	readonly MAX_COMMAND_COUNT: number;
+	readonly MAX_LOOP_ITERATIONS: number;
+	readonly MAX_AWK_ITERATIONS: number;
+	readonly MAX_SED_ITERATIONS: number;
+	readonly MAX_JQ_ITERATIONS: number;
+	readonly MAX_GLOB_OPERATIONS: number;
+	readonly MAX_STRING_LENGTH: number;
+	readonly MAX_ARRAY_ELEMENTS: number;
+	readonly MAX_HEREDOC_SIZE: number;
+	readonly MAX_SUBSTITUTION_DEPTH: number;
+	readonly MAX_SQLITE_TIMEOUT_MS: number;
+	readonly MAX_PYTHON_TIMEOUT_MS: number;
+	readonly MAX_OUTPUT_LENGTH: number;
+	readonly MAX_FILE_READ_SIZE: number | undefined;
+	readonly ENABLE_LOGGING: boolean;
+	readonly ENABLE_TRACING: boolean;
+	readonly ENABLE_PYTHON: boolean;
+	readonly ENABLE_DEFENSE_IN_DEPTH: boolean;
+	readonly OVERLAY_READ_ONLY: boolean;
+	readonly ALLOWED_COMMANDS: CommandName[] | undefined;
+}
+
+function getAllowedMethods(): HttpMethod[] {
+	const methods = parseEnvStringArray("JUST_BASH_ALLOWED_METHODS");
+	return methods.length > 0 ? (methods as HttpMethod[]) : ["GET", "HEAD"];
+}
+
+function getAllowedCommands(): CommandName[] | undefined {
+	const commands = parseEnvStringArray("JUST_BASH_ALLOWED_COMMANDS");
+	return commands.length > 0 ? (commands as CommandName[]) : undefined;
+}
+
+function parseEnvOptionalInt(key: string): number | undefined {
+	const value = process.env[key];
+	if (!value) return undefined;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+export const config: Config = {
+	// Server info
+	VERSION: "2.8.0",
+	SERVER_NAME: "just-bash-mcp",
+
+	// Filesystem configuration
+	OVERLAY_ROOT: process.env.JUST_BASH_OVERLAY_ROOT,
+	READ_WRITE_ROOT: process.env.JUST_BASH_READ_WRITE_ROOT,
+	MOUNTS_CONFIG: process.env.JUST_BASH_MOUNTS,
+	INITIAL_CWD: parseEnvString("JUST_BASH_CWD", "/home/user"),
+
+	// Network configuration
+	ALLOW_NETWORK: parseEnvBoolean("JUST_BASH_ALLOW_NETWORK", false),
+	ALLOWED_URL_PREFIXES: parseEnvStringArray("JUST_BASH_ALLOWED_URLS"),
+	ALLOWED_METHODS: getAllowedMethods(),
+	MAX_REDIRECTS: parseEnvInt("JUST_BASH_MAX_REDIRECTS", 20),
+	NETWORK_TIMEOUT_MS: parseEnvInt("JUST_BASH_NETWORK_TIMEOUT_MS", 30000),
+	MAX_RESPONSE_SIZE: parseEnvOptionalInt("JUST_BASH_MAX_RESPONSE_SIZE"),
+
+	// Execution limits
+	MAX_CALL_DEPTH: parseEnvInt("JUST_BASH_MAX_CALL_DEPTH", 100),
+	MAX_COMMAND_COUNT: parseEnvInt("JUST_BASH_MAX_COMMAND_COUNT", 10000),
+	MAX_LOOP_ITERATIONS: parseEnvInt("JUST_BASH_MAX_LOOP_ITERATIONS", 10000),
+	MAX_AWK_ITERATIONS: parseEnvInt("JUST_BASH_MAX_AWK_ITERATIONS", 10000),
+	MAX_SED_ITERATIONS: parseEnvInt("JUST_BASH_MAX_SED_ITERATIONS", 10000),
+	MAX_JQ_ITERATIONS: parseEnvInt("JUST_BASH_MAX_JQ_ITERATIONS", 10000),
+	MAX_GLOB_OPERATIONS: parseEnvInt("JUST_BASH_MAX_GLOB_OPERATIONS", 100000),
+	MAX_STRING_LENGTH: parseEnvInt("JUST_BASH_MAX_STRING_LENGTH", 10485760),
+	MAX_ARRAY_ELEMENTS: parseEnvInt("JUST_BASH_MAX_ARRAY_ELEMENTS", 100000),
+	MAX_HEREDOC_SIZE: parseEnvInt("JUST_BASH_MAX_HEREDOC_SIZE", 10485760),
+	MAX_SUBSTITUTION_DEPTH: parseEnvInt("JUST_BASH_MAX_SUBSTITUTION_DEPTH", 50),
+	MAX_SQLITE_TIMEOUT_MS: parseEnvInt("JUST_BASH_MAX_SQLITE_TIMEOUT_MS", 5000),
+	MAX_PYTHON_TIMEOUT_MS: parseEnvInt("JUST_BASH_MAX_PYTHON_TIMEOUT_MS", 30000),
+
+	// Output limits
+	MAX_OUTPUT_LENGTH: parseEnvInt("JUST_BASH_MAX_OUTPUT_LENGTH", 30000),
+
+	// Filesystem limits
+	MAX_FILE_READ_SIZE: parseEnvOptionalInt("JUST_BASH_MAX_FILE_READ_SIZE"),
+
+	// Debugging
+	ENABLE_LOGGING: parseEnvBoolean("JUST_BASH_ENABLE_LOGGING", false),
+	ENABLE_TRACING: parseEnvBoolean("JUST_BASH_ENABLE_TRACING", false),
+
+	// Feature flags
+	ENABLE_PYTHON: parseEnvBoolean("JUST_BASH_ENABLE_PYTHON", false),
+	ENABLE_DEFENSE_IN_DEPTH: parseEnvBoolean("JUST_BASH_DEFENSE_IN_DEPTH", false),
+	OVERLAY_READ_ONLY: parseEnvBoolean("JUST_BASH_OVERLAY_READ_ONLY", false),
+
+	// Command filtering
+	ALLOWED_COMMANDS: getAllowedCommands(),
+};
+
+// ============================================================================
+// Logger and Trace Callback
+// ============================================================================
+
+export const bashLogger: BashLogger | undefined = config.ENABLE_LOGGING
+	? {
+			info(message: string, data?: Record<string, unknown>): void {
+				if (data) {
+					console.error(`[just-bash] INFO: ${message}`, data);
+				} else {
+					console.error(`[just-bash] INFO: ${message}`);
+				}
+			},
+			debug(message: string, data?: Record<string, unknown>): void {
+				if (data) {
+					console.error(`[just-bash] DEBUG: ${message}`, data);
+				} else {
+					console.error(`[just-bash] DEBUG: ${message}`);
+				}
+			},
+		}
+	: undefined;
+
+export const traceCallback: TraceCallback | undefined = config.ENABLE_TRACING
+	? (event: TraceEvent) => {
+			if (event.details) {
+				console.error(
+					`[just-bash] TRACE: ${event.category}/${event.name} ${event.durationMs}ms`,
+					JSON.stringify(event.details),
+				);
+			} else {
+				console.error(`[just-bash] TRACE: ${event.category}/${event.name} ${event.durationMs}ms`);
+			}
+		}
+	: undefined;
+
+// ============================================================================
+// Configuration Builders
+// ============================================================================
+
+export function buildNetworkConfig(): NetworkConfig | undefined {
+	if (!config.ALLOW_NETWORK) {
+		return undefined;
+	}
+
+	if (config.ALLOWED_URL_PREFIXES.length > 0) {
+		return {
+			allowedUrlPrefixes: config.ALLOWED_URL_PREFIXES,
+			allowedMethods: config.ALLOWED_METHODS,
+			maxRedirects: config.MAX_REDIRECTS,
+			timeoutMs: config.NETWORK_TIMEOUT_MS,
+			...(config.MAX_RESPONSE_SIZE !== undefined && {
+				maxResponseSize: config.MAX_RESPONSE_SIZE,
+			}),
+		};
+	}
+
+	return {
+		dangerouslyAllowFullInternetAccess: true,
+		maxRedirects: config.MAX_REDIRECTS,
+		timeoutMs: config.NETWORK_TIMEOUT_MS,
+		...(config.MAX_RESPONSE_SIZE !== undefined && {
+			maxResponseSize: config.MAX_RESPONSE_SIZE,
+		}),
+	};
+}
+
+export function buildExecutionLimits(): NonNullable<BashOptions["executionLimits"]> {
+	return {
+		maxCallDepth: config.MAX_CALL_DEPTH,
+		maxCommandCount: config.MAX_COMMAND_COUNT,
+		maxLoopIterations: config.MAX_LOOP_ITERATIONS,
+		maxAwkIterations: config.MAX_AWK_ITERATIONS,
+		maxSedIterations: config.MAX_SED_ITERATIONS,
+		maxJqIterations: config.MAX_JQ_ITERATIONS,
+		maxGlobOperations: config.MAX_GLOB_OPERATIONS,
+		maxStringLength: config.MAX_STRING_LENGTH,
+		maxArrayElements: config.MAX_ARRAY_ELEMENTS,
+		maxHeredocSize: config.MAX_HEREDOC_SIZE,
+		maxSubstitutionDepth: config.MAX_SUBSTITUTION_DEPTH,
+		maxSqliteTimeoutMs: config.MAX_SQLITE_TIMEOUT_MS,
+		maxPythonTimeoutMs: config.MAX_PYTHON_TIMEOUT_MS,
+	};
+}
+
+export function parseMountsConfig(): MountConfig[] {
+	if (!config.MOUNTS_CONFIG) return [];
+	try {
+		const parsed: unknown = JSON.parse(config.MOUNTS_CONFIG);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.map(
+			(mount: { mountPoint: string; root: string; type?: string; readOnly?: boolean }) => {
+				const fsType = mount.type || "overlay";
+				const maxFileReadSize = config.MAX_FILE_READ_SIZE;
+				const filesystem =
+					fsType === "readwrite"
+						? new ReadWriteFs({
+								root: mount.root,
+								...(maxFileReadSize !== undefined && { maxFileReadSize }),
+							})
+						: new OverlayFs({
+								root: mount.root,
+								readOnly: mount.readOnly,
+								...(maxFileReadSize !== undefined && { maxFileReadSize }),
+							});
+				return { mountPoint: mount.mountPoint, filesystem };
+			},
+		);
+	} catch {
+		return [];
+	}
+}
+
+// ============================================================================
+// Environment Variables Documentation
+// ============================================================================
+
+export const ENVIRONMENT_VARIABLES = {
+	JUST_BASH_OVERLAY_ROOT: "Real directory to mount as overlay (read from disk, write to memory)",
+	JUST_BASH_OVERLAY_READ_ONLY:
+		"If true, all writes to overlay filesystem throw errors (default: false)",
+	JUST_BASH_READ_WRITE_ROOT: "Real directory with read-write access",
+	JUST_BASH_MOUNTS: "JSON array of mount configurations (supports type, readOnly fields)",
+	JUST_BASH_CWD: "Initial working directory (default: /home/user)",
+	JUST_BASH_ALLOW_NETWORK: "Enable network access (default: false)",
+	JUST_BASH_ALLOWED_URLS: "Comma-separated URL prefixes to allow",
+	JUST_BASH_ALLOWED_METHODS: "Comma-separated HTTP methods (default: GET,HEAD)",
+	JUST_BASH_ALLOWED_COMMANDS: "Comma-separated list of allowed commands",
+	JUST_BASH_MAX_REDIRECTS: "Max HTTP redirects (default: 20)",
+	JUST_BASH_NETWORK_TIMEOUT_MS: "Network timeout in ms (default: 30000)",
+	JUST_BASH_MAX_RESPONSE_SIZE: "Max network response body size in bytes (default: 10MB)",
+	JUST_BASH_MAX_CALL_DEPTH: "Max recursion depth (default: 100)",
+	JUST_BASH_MAX_COMMAND_COUNT: "Max commands per execution (default: 10000)",
+	JUST_BASH_MAX_LOOP_ITERATIONS: "Max bash loop iterations (default: 10000)",
+	JUST_BASH_MAX_AWK_ITERATIONS: "Max AWK while/for loop iterations (default: 10000)",
+	JUST_BASH_MAX_SED_ITERATIONS: "Max sed branch loop iterations (default: 10000)",
+	JUST_BASH_MAX_JQ_ITERATIONS: "Max jq loop iterations (default: 10000)",
+	JUST_BASH_MAX_GLOB_OPERATIONS: "Max glob filesystem operations (default: 100000)",
+	JUST_BASH_MAX_STRING_LENGTH: "Max string length in bytes (default: 10485760 = 10MB)",
+	JUST_BASH_MAX_ARRAY_ELEMENTS: "Max array elements (default: 100000)",
+	JUST_BASH_MAX_HEREDOC_SIZE: "Max heredoc size in bytes (default: 10485760 = 10MB)",
+	JUST_BASH_MAX_SUBSTITUTION_DEPTH: "Max command substitution nesting depth (default: 50)",
+	JUST_BASH_MAX_SQLITE_TIMEOUT_MS: "SQLite timeout in ms (default: 5000)",
+	JUST_BASH_MAX_PYTHON_TIMEOUT_MS: "Python timeout in ms (default: 30000)",
+	JUST_BASH_MAX_OUTPUT_LENGTH: "Max output length (default: 30000)",
+	JUST_BASH_MAX_FILE_READ_SIZE:
+		"Max file read size in bytes for OverlayFs/ReadWriteFs (default: 10MB)",
+	JUST_BASH_ENABLE_LOGGING: "Enable debug logging (default: false)",
+	JUST_BASH_ENABLE_TRACING: "Enable performance tracing (default: false)",
+	JUST_BASH_ENABLE_PYTHON: "Enable python3/python commands via Pyodide (default: false)",
+	JUST_BASH_DEFENSE_IN_DEPTH:
+		"Enable defense-in-depth mode that patches dangerous JS globals (default: false)",
+} as const;
+
+// ============================================================================
+// Command Categories Documentation
+// ============================================================================
+
+export const COMMAND_CATEGORIES = {
+	fileOperations: "cat, cp, file, ln, ls, mkdir, mv, readlink, rm, rmdir, split, stat, touch, tree",
+	textProcessing:
+		"awk, base64, column, comm, cut, diff, expand, fold, grep (egrep, fgrep), head, join, md5sum, nl, od, paste, printf, rev, rg (ripgrep), sed, sha1sum, sha256sum, sort, strings, tac, tail, tr, unexpand, uniq, wc, xargs",
+	dataProcessing:
+		"jq (JSON), python3/python (Python via Pyodide), sqlite3 (SQLite), xan (CSV), yq (YAML/XML/TOML/CSV)",
+	compression: "gzip (gunzip, zcat), tar",
+	navigation:
+		"basename, cd, dirname, du, echo, env, export, find, hostname, printenv, pwd, tee, whoami",
+	shellUtilities:
+		"alias, bash, chmod, clear, date, expr, false, help, history, seq, sh, sleep, time, timeout, true, unalias, which",
+	network: "curl, html-to-markdown (when network enabled)",
+} as const;
+
+// ============================================================================
+// Features Documentation
+// ============================================================================
+
+export const FEATURES = {
+	customCommands: "Define custom TypeScript commands using defineCommand()",
+	rawScript: "Preserve leading whitespace in scripts (useful for here-docs)",
+	logger: "Optional execution logging via BashLogger interface",
+	trace: "Performance profiling via TraceCallback",
+	commandFilter: "Restrict available commands via JUST_BASH_ALLOWED_COMMANDS env var",
+	sandboxApi: "Vercel Sandbox compatible API via bash_sandbox_* tools",
+	python: "Python support via Pyodide (opt-in via JUST_BASH_ENABLE_PYTHON=true)",
+	defenseInDepth:
+		"Defense-in-depth mode that monkey-patches dangerous JS globals during execution (opt-in via JUST_BASH_DEFENSE_IN_DEPTH=true)",
+	overlayReadOnly:
+		"Read-only overlay filesystem mode (opt-in via JUST_BASH_OVERLAY_READ_ONLY=true)",
+	networkResponseSize:
+		"Configurable max network response body size via JUST_BASH_MAX_RESPONSE_SIZE",
+	fileReadSizeLimit:
+		"Configurable max file read size for OverlayFs/ReadWriteFs via JUST_BASH_MAX_FILE_READ_SIZE",
+} as const;

package/src/index.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+/**
+ * just-bash-mcp - MCP Server for sandboxed bash execution
+ *
+ * A Model Context Protocol (MCP) server that provides AI agents with a
+ * secure, sandboxed bash environment powered by just-bash from Vercel Labs.
+ *
+ * @see https://github.com/vercel-labs/just-bash
+ * @see https://modelcontextprotocol.io
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { config } from "./config/index.ts";
+import { registerAllTools } from "./tools/index.ts";
+
+// ============================================================================
+// Server Initialization
+// ============================================================================
+
+const server = new McpServer({
+	name: config.SERVER_NAME,
+	version: config.VERSION,
+});
+
+// Register all tools with the server
+registerAllTools(server);
+
+// ============================================================================
+// Start Server
+// ============================================================================
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools/bash-instance.ts

@@ -0,0 +1,160 @@
+/**
+ * Bash instance management
+ * Handles creation and lifecycle of Bash instances
+ */
+
+import {
+	Bash,
+	type BashOptions,
+	type CustomCommand,
+	InMemoryFs,
+	MountableFs,
+	OverlayFs,
+	ReadWriteFs,
+	Sandbox,
+	type SandboxOptions,
+} from "just-bash";
+
+import {
+	bashLogger,
+	buildExecutionLimits,
+	buildNetworkConfig,
+	config,
+	parseMountsConfig,
+	traceCallback,
+} from "../config/index.ts";
+
+// ============================================================================
+// Bash Instance Factory
+// ============================================================================
+
+/**
+ * Create a new Bash instance with the given configuration
+ */
+export function createBashInstance(
+	files?: Record<string, string>,
+	customCommands?: CustomCommand[],
+	env?: Record<string, string>,
+): Bash {
+	const networkConfig = buildNetworkConfig();
+	const executionLimits = buildExecutionLimits();
+
+	const baseOptions: BashOptions = {
+		network: networkConfig,
+		executionLimits,
+		files,
+		env,
+		logger: bashLogger,
+		trace: traceCallback,
+		customCommands,
+		commands: config.ALLOWED_COMMANDS,
+		python: config.ENABLE_PYTHON,
+		defenseInDepth: config.ENABLE_DEFENSE_IN_DEPTH,
+	};
+
+	// Check for mountable filesystem configuration
+	const mounts = parseMountsConfig();
+	if (mounts.length > 0) {
+		const mountableFs = new MountableFs({
+			base: new InMemoryFs(),
+			mounts,
+		});
+		return new Bash({
+			...baseOptions,
+			fs: mountableFs,
+			cwd: config.INITIAL_CWD,
+		});
+	}
+
+	// Check for read-write filesystem configuration
+	if (config.READ_WRITE_ROOT) {
+		const rwfs = new ReadWriteFs({
+			root: config.READ_WRITE_ROOT,
+			...(config.MAX_FILE_READ_SIZE !== undefined && {
+				maxFileReadSize: config.MAX_FILE_READ_SIZE,
+			}),
+		});
+		return new Bash({
+			...baseOptions,
+			fs: rwfs,
+			cwd: config.READ_WRITE_ROOT,
+		});
+	}
+
+	// Check for overlay filesystem configuration
+	if (config.OVERLAY_ROOT) {
+		const overlay = new OverlayFs({
+			root: config.OVERLAY_ROOT,
+			readOnly: config.OVERLAY_READ_ONLY,
+			...(config.MAX_FILE_READ_SIZE !== undefined && {
+				maxFileReadSize: config.MAX_FILE_READ_SIZE,
+			}),
+		});
+		return new Bash({
+			...baseOptions,
+			fs: overlay,
+			cwd: overlay.getMountPoint(),
+		});
+	}
+
+	// Default: in-memory filesystem
+	return new Bash({
+		...baseOptions,
+		cwd: config.INITIAL_CWD,
+	});
+}
+
+// ============================================================================
+// Persistent Bash Instance (singleton pattern)
+// ============================================================================
+
+let persistentBash: Bash | null = null;
+
+/**
+ * Get or create the persistent Bash instance
+ */
+export function getPersistentBash(): Bash {
+	if (!persistentBash) {
+		persistentBash = createBashInstance();
+	}
+	return persistentBash;
+}
+
+/**
+ * Reset the persistent Bash instance
+ */
+export function resetPersistentBash(): void {
+	persistentBash = null;
+}
+
+// ============================================================================
+// Persistent Sandbox Instance (singleton pattern)
+// ============================================================================
+
+let persistentSandbox: Sandbox | null = null;
+
+/**
+ * Get or create the persistent Sandbox instance
+ */
+export async function getPersistentSandbox(): Promise<Sandbox> {
+	if (!persistentSandbox) {
+		const networkConfig = buildNetworkConfig();
+		const options: SandboxOptions = {
+			cwd: config.INITIAL_CWD,
+			network: networkConfig,
+			maxCallDepth: config.MAX_CALL_DEPTH,
+			maxCommandCount: config.MAX_COMMAND_COUNT,
+			maxLoopIterations: config.MAX_LOOP_ITERATIONS,
+			...(config.OVERLAY_ROOT && { overlayRoot: config.OVERLAY_ROOT }),
+		};
+		persistentSandbox = await Sandbox.create(options);
+	}
+	return persistentSandbox;
+}
+
+/**
+ * Reset the persistent Sandbox instance
+ */
+export function resetPersistentSandbox(): void {
+	persistentSandbox = null;
+}