BashBox: Sandboxed Bash Interpreter for PHP AI Agents | Mohamed Said [Skip to content](#main) [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com) - [Home](https://www.msaied.com) - [Projects](https://www.msaied.com/projects) - [Articles](https://www.msaied.com/articles) - [Certificates](https://www.msaied.com/certificates) - [About](https://www.msaied.com#about) [ Contact](https://www.msaied.com#contact) Menu Menu ---- Close - [HomeStart here](https://www.msaied.com) - [ProjectsCase studies](https://www.msaied.com/projects) - [ArticlesEngineering notes](https://www.msaied.com/articles) - [CertificatesCredentials](https://www.msaied.com/certificates) - [AboutHow I work](https://www.msaied.com#about) - [ContactGet in touch](https://www.msaied.com#contact) [Start a conversation](https://www.msaied.com#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 1. [Home](https://www.msaied.com) 2. / 3. [Articles](https://www.msaied.com/articles) 4. / 5. [Composer Pacakge](https://www.msaied.com/articles?category=composer-pacakge) 6. / 7. BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP [Composer Pacakge](https://www.msaied.com/articles?category=composer-pacakge) [AI](https://www.msaied.com/articles?category=ai) BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP =========================================================== BashBox is a pure-PHP bash interpreter that lets AI agents run shell scripts safely — no proc\_open, no exec, no shell\_exec. It ships 58 commands, a virtual filesystem, configurable execution limits, and optional network access. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com#person) Published 11 Oct 2026 · Updated 13 Oct 2026 · 4 min read ShareCopy linkCopied ![BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP](https://cdn.msaied.com/775/9ffc1bfe88806626f495f3ef307e0b69.png) On this page +1. [What Is BashBox?](#what-is-bashbox) 2. [Running Your First Script](#running-your-first-script) 3. [Filesystem Backends](#filesystem-backends) 4. [Execution Limits](#execution-limits) 5. [Network Access](#network-access) 6. [Custom Commands](#custom-commands) 7. [Key Takeaways](#key-takeaways) What Is BashBox? ---------------- BashBox is a bash interpreter written entirely in pure PHP by [Pushpak Chhajed](https://github.com/pushpak1300). Its primary use case is running shell scripts that AI agents generate — safely, without ever calling `proc_open`, `exec`, or `shell_exec`. Every command is a PHP class operating against a virtual filesystem, and every execution runs under limits you define. Install it with Composer (PHP 8.4+ required, no other dependencies): ```bash composer require shipfastlabs/bashbox ``` Running Your First Script ------------------------- Create a `Bash` instance and pass a script string to `exec()`. The returned result object exposes `stdout` and `exitCode`: ```php use BashBox\Bash; $bash = new Bash; $result = $bash->exec(' NAME="BashBox" echo "Hello, $NAME" | tr a-z A-Z '); $result->stdout; // "HELLO, BASHBOX\n" $result->exitCode; // 0 ``` BashBox supports pipes, fd redirections (`2>&1`), here-docs, process substitution, arrays, functions, control flow, parameter expansion, and `set`/`shopt` options. It ships **58 commands** — including `grep`, `sed`, `sort`, `find`, `xargs`, and `sha256sum` — plus builtins like `cd`, `export`, `source`, `read`, and `trap`. A script that fails to parse returns exit code 2 with bash's syntax error on stderr rather than throwing a PHP exception. You can seed the sandbox with virtual files and environment variables at construction time: ```php use BashBox\Bash; use BashBox\BashOptions; $bash = new Bash(new BashOptions( initialFiles: [ '/home/user/app.log' => "INFO boot\nERROR db timeout\nINFO ready\n", ], env: ['APP_ENV' => 'production'], )); $bash->exec('grep ERROR app.log')->stdout; // "ERROR db timeout\n" ``` Filesystem Backends ------------------- The default `InMemoryFs` never touches disk. Three additional backends give scripts access to real files: - **`OverlayFs`** — reads from a real directory; writes stay in an in-memory copy-on-write layer. - **`ReadWriteFs`** — reads and writes to disk, confined to a root directory you specify. - **`MountableFs`** — mounts different backends at different paths. Every backend enforces a **64 MB disk quota** and a **10,000-entry limit** by default. Writes past the quota fail with `No space left on device`. BashBox also blocks path traversal and null-byte injection, and `OverlayFs` denies symlinks by default. Execution Limits ---------------- The `Limits` class exposes 18 configurable settings. Exceeding any of them throws `BashBox\Exceptions\ExecutionLimitException`: ```php use BashBox\Limits; $bash = new Bash(new BashOptions( limits: new Limits( maxCommandCount: 100, maxLoopIterations: 500, maxOutputSize: 1024 * 1024, // 1 MB maxCallDepth: 10, ), )); ``` Defaults are generous but bounded: 10,000 commands per script, 10,000 loop iterations, 10 MB of output, a call depth of 100, and 1 MB of script text. `ExecOptions` can override limits for a single `exec()` call. Network Access -------------- Network access is **off by default**. The `curl` command only exists once you pass a `NetworkConfig`: ```php use BashBox\Network\NetworkConfig; $bash = new Bash(new BashOptions( network: new NetworkConfig( allowedUrlPrefixes: ['https://api.example.com/'], allowedMethods: ['GET', 'POST'], denyPrivateRanges: true, maxResponseSize: 5 * 1024 * 1024, timeout: 10, ), )); ``` `denyPrivateRanges` is on by default and blocks loopback, private, and link-local addresses for both the URL host and the resolved IP. Redirects are only followed with `-L`, and `Authorization`/`Cookie` headers are dropped on cross-origin redirects. Custom Commands --------------- Extend `AbstractCommand` and register it on the `Bash` instance to add any command BashBox doesn't ship: ```php use BashBox\Commands\AbstractCommand; use BashBox\Commands\CommandContext; use BashBox\ExecResult; class MyCommand extends AbstractCommand { public function getName(): string { return 'mycommand'; } public function execute(array $args, CommandContext $ctx): ExecResult { return $this->success('Hello from my command!'); } } $bash->registerCommand(new MyCommand); $bash->exec('mycommand')->stdout; // "Hello from my command!" ``` Key Takeaways ------------- - Runs AI-generated bash scripts in pure PHP — no system shell calls. - Ships 58 commands plus standard builtins out of the box. - Four filesystem backends, including in-memory and overlay options. - 18 configurable execution limits with a dedicated exception on breach. - Network access is opt-in, URL-allowlisted, and private-range-blocked by default. - Requires PHP 8.4+; MIT licensed; currently at v0.0.3. - Integrates directly with the Laravel AI SDK as a tool. --- *Source: [BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP — Laravel News](https://laravel-news.com/bashbox-sandboxed-bash-php)* - [BashBox](https://www.msaied.com/articles?search=BashBox) - [AI Agents](https://www.msaied.com/articles?search=AI%20Agents) - [PHP Package](https://www.msaied.com/articles?search=PHP%20Package) - [Sandbox](https://www.msaied.com/articles?search=Sandbox) - [Laravel AI SDK](https://www.msaied.com/articles?search=Laravel%20AI%20SDK) - [Shell Scripting](https://www.msaied.com/articles?search=Shell%20Scripting) Frequently asked questions --------------------------- Does BashBox call any system shell functions like proc\_open or exec?No. BashBox is a pure-PHP interpreter. It never calls proc\_open, exec, shell\_exec, or any other system shell function. Every command is implemented as a PHP class operating against a virtual filesystem. Can BashBox scripts access the real filesystem or the network?Filesystem access depends on the backend you choose. The default InMemoryFs never touches disk, but OverlayFs, ReadWriteFs, and MountableFs can expose real directories. Network access is off by default and must be explicitly enabled via NetworkConfig, which requires an allowlist of URL prefixes. What happens when a BashBox script exceeds an execution limit?BashBox throws a BashBox\\Exceptions\\ExecutionLimitException. You can configure 18 different limits — including max command count, loop iterations, output size, and call depth — via the Limits class passed to BashOptions. ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author ---------------- [Mohamed Said](https://www.msaied.com#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. [About](https://www.msaied.com#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) [Previous articleRead/Write Splitting and Sticky Reads in Laravel: A Production Guide](https://www.msaied.com/articles/readwrite-splitting-and-sticky-reads-in-laravel-a-production-guide-1) [Next articlePuzzle Party: A Laravel + Flutter App Built With the Help of the Community](https://www.msaied.com/articles/puzzle-party-a-laravel-flutter-app-built-with-the-help-of-the-community) On this page ------------- 1. [What Is BashBox?](#what-is-bashbox) 2. [Running Your First Script](#running-your-first-script) 3. [Filesystem Backends](#filesystem-backends) 4. [Execution Limits](#execution-limits) 5. [Network Access](#network-access) 6. [Custom Commands](#custom-commands) 7. [Key Takeaways](#key-takeaways) ### Have a technical challenge? Tell me what you’re building. I reply within two working days. [Start a conversation](https://www.msaied.com#contact) Related articles ----------------- [ ![](https://cdn.msaied.com/772/751d21c9bbf4187742acfb130ad4b3c4.png) Laravel · 3 min read### Puzzle Party: A Laravel + Flutter App Built With the Help of the Community 12 Oct 2026 ](https://www.msaied.com/articles/puzzle-party-a-laravel-flutter-app-built-with-the-help-of-the-community) [ ![](https://cdn.msaied.com/774/9ffc1bfe88806626f495f3ef307e0b69.png) Composer Pacakge · 4 min read### BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP 11 Oct 2026 ](https://www.msaied.com/articles/bashbox-a-sandboxed-bash-interpreter-for-ai-agents-in-php-2) [ ![](https://cdn.msaied.com/771/c168cfa614dbed6663e8550e8d20a489.png) Composer Pacakge · 4 min read### BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP 11 Oct 2026 ](https://www.msaied.com/articles/bashbox-a-sandboxed-bash-interpreter-for-ai-agents-in-php-1) Have a technical challenge? ---------------------------- Tell me what you’re building. I reply within two working days. [Discuss your project ↗](https://www.msaied.com#contact) © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. - [Home](https://www.msaied.com) - [Articles](https://www.msaied.com/articles) - [Certificates](https://www.msaied.com/certificates) - [GitHub](https://github.com/EG-Mohamed) - [LinkedIn](https://www.linkedin.com/in/msaiedm/) - [WhatsApp](https://wa.me/201094619204) - [Email Address](mailto:hello@msaied.com) - [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) - [Sitemap](https://www.msaied.com/sitemap.xml)