A simulated bash environment written in TypeScript, just-bash provides AI agents with a secure, sandboxed execution context featuring an in-memory virtual filesystem. It offers controlled network access via curl with secure-by-default URL filtering, enabling agents to interact with external resources safely. The project aims to offer a robust, isolated shell environment for AI-driven tasks, reducing security risks associated with direct system access.

How It Works

just-bash simulates a bash environment using TypeScript, abstracting filesystem operations into an in-memory virtual filesystem by default. It implements execution protection against infinite loops and recursion, enhancing security. Network access, including the curl command, is opt-in and strictly controlled via configurable URL prefix and HTTP method allow-lists, ensuring outbound requests adhere to predefined security policies. This design prioritizes safety and predictability for AI agent execution.

Quick Start & Requirements

• Primary install: npm install just-bash
• Prerequisites: Node.js and a package manager (npm, pnpm).
• AI SDK Tool: bash-tool (npm install bash-tool) for seamless integration with AI models.
• Vercel Sandbox Compatible API: Use the Sandbox class for API compatibility with @vercel/sandbox.
• CLI Binary: Install globally (npm install -g just-bash) for command-line usage.
• Interactive Shell: Run pnpm shell.

Highlighted Details

• Filesystem Options: Supports InMemoryFs (default), OverlayFs (copy-on-write over disk), and ReadWriteFs (direct disk access).
• Custom Commands: Extensible with custom TypeScript commands using defineCommand.
• Network Control: Granular control over network access via allowedUrlPrefixes and allowedMethods.
• SQLite Support: Integrated sqlite3 command powered by sql.js (WASM-based, sandboxed).
• Execution Protection: Configurable limits for call depth, command count, and loop iterations.
• Vercel Sandbox API Compatibility: Provides a Sandbox class mirroring @vercel/sandbox API.

Maintenance & Community

No specific details regarding notable contributors, sponsorships, partnerships, or community channels (like Discord/Slack) are provided in the README. Development commands include pnpm test, pnpm build, and pnpm shell.

Licensing & Compatibility

• License: Apache-2.0.
• Compatibility: The Apache-2.0 license is permissive for commercial use and integration into closed-source projects. The API is designed for compatibility with @vercel/sandbox.

Limitations & Caveats

This project is designated as beta software and should be used at the user's own risk. Bash is not fully robust against Denial-of-Service attacks from input, recommending OS-level process isolation for higher security needs. Binaries or WASM execution are inherently unsupported; for full VM capabilities, Vercel Sandbox or similar products are suggested. Network access is disabled by default and requires explicit configuration.