GitHub - vercel-labs/just-bash: Bash for Agents

just-bash is a TypeScript-based simulated bash environment designed specifically for AI agents that need a secure, sandboxed shell environment. Unlike traditional bash shells that execute real commands on your system, just-bash provides a controlled virtual filesystem and command execution environment that keeps agents contained while still giving them the familiar bash interface.

Security-First Design

The shell operates with a strict security model where execution is isolated to the provided filesystem. This means agents can only access files you explicitly give them, and all command execution is protected against infinite loops and excessive recursion. The system includes configurable execution limits to prevent denial-of-service attacks through resource exhaustion.

Network access is disabled by default, requiring explicit configuration through URL prefix allow-lists and HTTP method restrictions. When enabled, the curl command is available but requests are filtered to only allow connections to approved domains and methods. This "secure-by-default" approach ensures agents can't accidentally or maliciously access external resources.

Filesystem Flexibility

just-bash offers four filesystem implementations to suit different use cases:

• InMemoryFs: Pure in-memory filesystem with no disk access
• OverlayFs: Copy-on-write over real directories - reads from disk, writes stay in memory
• ReadWriteFs: Direct read-write access to real directories (use with caution)
• MountableFs: Combine multiple filesystems at different paths for complex setups

This flexibility allows you to choose the right balance between isolation and functionality. For example, you might mount a read-only knowledge base alongside a writable workspace, or use OverlayFs to let agents read from your project directory without modifying it.

Custom Commands and Extensibility

Beyond the built-in bash commands, just-bash supports custom TypeScript commands through the defineCommand API. This allows you to extend the environment with domain-specific functionality that agents can use. Custom commands receive full context including filesystem access, current working directory, environment variables, and stdin, making it easy to build sophisticated tools.

AI Agent Integration

The project includes bash-tool, an optimized wrapper specifically for AI agents that provides ready-to-use AI SDK tools. This integration makes it straightforward to give agents bash capabilities without dealing with the underlying complexity. The tool handles file management, command execution, and result formatting in a way that's natural for AI interactions.

CLI and Interactive Shell

A CLI binary is available for direct use, providing a secure alternative to bash for AI agents. The CLI uses OverlayFs by default, ensuring all writes are discarded after execution. An interactive shell is also available for testing and development, with full internet access enabled by default for convenience.

Supported Commands and Features

just-bash supports a comprehensive set of bash commands including file operations, text processing, data processing (with tools like jq and sqlite3), compression, navigation, and network commands. The shell features standard bash syntax including pipes, redirections, command chaining, variables, functions, loops, and if statements.

Development and Compatibility

The project includes AST transform plugins that allow you to parse, modify, and analyze bash scripts before execution. This is useful for instrumentation, security analysis, or extracting information from scripts. Additionally, just-bash provides a Sandbox class that's API-compatible with @vercel/sandbox, making it easy to swap between implementations depending on your needs.

For developers, the project offers comprehensive testing, TypeScript support, and clear documentation. The interactive shell and CLI tools make it easy to experiment and debug.

Use Cases

just-bash is ideal for scenarios where you need to give AI agents shell-like capabilities without the security risks of real bash execution. This includes AI coding assistants, automated testing environments, data processing pipelines, and any application where you want to sandbox command execution while maintaining bash compatibility.

Getting Started

Installation is straightforward with npm: npm install just-bash. The basic API is simple - create a Bash instance and use exec() to run commands. The project includes detailed documentation for configuration options, custom commands, filesystem setup, and advanced features like Python support via Pyodide and SQLite via sql.js.

License

Apache-2.0

GitHub Repository