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 14 Oct 2026 · 4 min read ShareCopy linkCopied ![BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP](https://cdn.msaied.com/777/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). It is designed to let AI agents generate and execute shell scripts without ever calling `proc_open`, `exec`, or `shell_exec`. Every command is a PHP class that operates against a virtual filesystem, and every execution runs under limits you control. Install it with Composer — it requires PHP 8.4 or later and has no other dependencies: ```bash composer require shipfastlabs/bashbox ``` Running Your First Script ------------------------- Create a `Bash` instance and pass a script string to `exec()`. The 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 ``` The interpreter 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 a syntax error on stderr rather than throwing an exception. You can seed the sandbox with 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 controlled 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. Each backend enforces a 64 MB disk quota and a 10,000-entry limit by default. Exceeding the quota returns `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 allow 10,000 commands per script, 10,000 loop iterations, 10 MB of output, a call depth of 100, and 1 MB of script text. Network Access -------------- Network access is disabled by default. Passing a `NetworkConfig` enables the `curl` command with an explicit allow-list: ```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. Redirects are only followed with `-L`, and each redirect target is checked against the allow-list. Custom Commands --------------- Extend `AbstractCommand` and register it on the `Bash` instance to add commands BashBox does not 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 required. - Ships 58 commands and full bash feature support (pipes, here-docs, arrays, functions). - Four filesystem backends from fully in-memory to real disk with copy-on-write. - 18 configurable execution limits plus per-call overrides via `ExecOptions`. - Network access is opt-in with URL prefix allow-lists and private-range blocking. - Requires PHP 8.4+, zero Composer dependencies, MIT licensed (v0.0.3). --- *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 8.4](https://www.msaied.com/articles?search=PHP%208.4) - [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 --------------------------- Why use BashBox instead of calling proc\_open or shell\_exec directly?BashBox runs scripts entirely in PHP without spawning a real shell process. This means AI-generated scripts execute in a controlled virtual environment with configurable limits on commands, loop iterations, output size, and filesystem access — eliminating the risk of arbitrary command execution on the host system. Can BashBox scripts access the real filesystem or make HTTP requests?Both are opt-in. By default, BashBox uses an in-memory filesystem. You can enable real filesystem access via OverlayFs, ReadWriteFs, or MountableFs backends. Network access requires passing a NetworkConfig with an explicit URL prefix allow-list; private IP ranges are blocked by default. What happens when a script exceeds an execution limit?BashBox throws a BashBox\\Exceptions\\ExecutionLimitException when any configured limit is breached — such as maxCommandCount, maxLoopIterations, or maxOutputSize. Filesystem quota violations return a 'No space left on device' error instead of an exception, mirroring real disk behavior. ![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/776/8e8ee70ebeedf358233b53e19ecae4a1.png) Laravel · 4 min read### Filament v5.10.2 Released: Accessibility Fixes, RTL Support, and New Features 13 Oct 2026 ](https://www.msaied.com/articles/filament-v5102-released-accessibility-fixes-rtl-support-and-new-features) [ ![](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/775/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-3) 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)