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 12 Oct 2026 · 4 min read ShareCopy linkCopied ![BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP](https://cdn.msaied.com/770/9ffc1bfe88806626f495f3ef307e0b69.png) On this page +1. [What Is BashBox?](#what-is-bashbox) 2. [Running a Script](#running-a-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 PHP by [Pushpak Chhajed](https://github.com/pushpak1300). It is designed for one specific problem: AI agents that generate and run shell scripts need a safe execution environment. BashBox provides that without ever calling `proc_open`, `exec`, or `shell_exec`. Every command is a PHP class, every execution runs against a virtual filesystem, and every resource limit is configurable. Install it with Composer (PHP 8.4+ required, no other dependencies): ```bash composer require shipfastlabs/bashbox ``` Running a Script ---------------- Create a `Bash` instance and call `exec()`. The result 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 a syntax error on stderr rather than throwing an 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 cover real-file scenarios: - **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. - **MountableFs** — mounts different backends at different paths. All backends enforce a 64 MB disk quota and a 10,000-entry limit by default. BashBox also blocks path traversal and null-byte injection, and `OverlayFs` denies symlinks by default. Execution Limits ---------------- The `Limits` class exposes 18 settings. Exceeding any one 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. `ExecOptions` can override limits for a single `exec()` call. Network Access -------------- Network access is disabled by default. Pass a `NetworkConfig` to enable `curl`: ```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 at both the URL and the resolved IP level. 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 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 ------------- - BashBox runs AI-generated bash scripts in pure PHP — no system shell required. - 58 built-in commands cover the most common scripting needs out of the box. - Four filesystem backends range from fully in-memory to real disk with copy-on-write. - 18 configurable execution limits prevent runaway scripts from consuming resources. - Network access is opt-in and restricted to explicit URL prefixes by default. - Integrates directly with the Laravel AI SDK as an agent tool. - Requires PHP 8.4+, MIT licensed, currently at 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 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 exec or proc\_open?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 running against a virtual filesystem. 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. 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 disk access via OverlayFs, ReadWriteFs, or MountableFs. Network access requires passing a NetworkConfig with explicit allowed URL prefixes; private IP ranges are blocked by default. ![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) On this page ------------- 1. [What Is BashBox?](#what-is-bashbox) 2. [Running a Script](#running-a-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/757/f990951a1a0e14b4fece312bce644c29.png) · 4 min read### Read/Write Splitting and Sticky Reads in Laravel: A Production Guide 9 Oct 2026 ](https://www.msaied.com/articles/readwrite-splitting-and-sticky-reads-in-laravel-a-production-guide-1) [ ![](https://cdn.msaied.com/756/69efdf9ac9ec1e1f61378055f1cd6e92.png) · 4 min read### Eloquent at Scale: Chunked Iteration, Lazy Collections, and Cursor Pagination 9 Oct 2026 ](https://www.msaied.com/articles/eloquent-at-scale-chunked-iteration-lazy-collections-and-cursor-pagination) [ ![](https://cdn.msaied.com/769/2ba8b59dbd15bdf2ec2f7846da0f62d4.png) Laravel · 4 min read### Running Laravel's Scheduler on Multiple Servers with alwaysOnOneServer() and hasBeenInterruptedSince() 8 Oct 2026 ](https://www.msaied.com/articles/running-laravels-scheduler-on-multiple-servers-with-alwaysononeserver-and-hasbeeninterruptedsince-6) 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)