Codeline

just-bash is a virtual bash shell environment implemented in TypeScript, designed to allow AI agents to execute shell scripts securely without interacting with the host operating system. It addresses the security risks inherent in granting shell access to AI agents by running commands against an in-memory filesystem, ensuring that no real disk operations or host OS interactions occur.

The tool parses and executes shell scripts through an abstract syntax tree (AST) pipeline, supporting a wide range of bash features such as pipes, redirections, conditional and loop constructs, functions, glob patterns, heredocs, and variable expansion. Over 70 commands are implemented, each as a separate module, enabling scripts to perform complex operations like chaining commands with && or ||, and using utilities such as cat, grep, sed, and jq within the virtual environment. The parser uses recursive descent techniques and enforces strict limits on parser depth, token count, and iterations to guard against malicious input, which is especially relevant when input is generated by large language models.

just-bash includes a modular filesystem layer, with the default being an entirely in-memory filesystem that stores files, directories, symlinks, and permissions in a map structure. Additional filesystem types are available: OverlayFs allows read-only access to a real directory while keeping all writes virtual, ReadWriteFs enables actual disk access when desired, and MountableFs supports combining multiple filesystems at different mount points. This design allows for scenarios such as granting an agent read-only access to a codebase while keeping all modifications isolated in memory.

Security is further enhanced by monkey-patching potentially dangerous JavaScript globals during script execution, using context tracking to ensure these patches only affect code running within the shell environment. Dynamic imports are blocked at multiple levels to prevent unauthorized code execution. The tool can be used programmatically via a TypeScript API, allowing for custom command definitions and integration with overlay filesystems, or through a CLI for direct shell command execution. It also provides a Sandbox class compatible with @vercel/sandbox for local development and testing. This makes just-bash particularly suitable for developers and researchers building or testing AI agents that require safe, isolated shell environments.