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/771/c168cfa614dbed6663e8550e8d20a489.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](https://github.com/shipfastlabs/bashbox) is a bash interpreter written entirely in PHP by Pushpak Chhajed. It is designed to run shell scripts that AI agents generate 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. It requires PHP 8.4 or later, has zero additional Composer dependencies, and is MIT licensed (current release: v0.0.3). ```bash composer require shipfastlabs/bashbox ``` Running a Script ---------------- Instantiate `Bash`, pass a script string to `exec()`, and read `stdout` and `exitCode` from the result: ```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 bash's syntax error on stderr rather than throwing an exception. You can seed the sandbox with files and environment variables at construction time using `BashOptions`: ```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 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. - **`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 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 iterations per loop, 10 MB of output, and a function call depth of 100. Network Access -------------- Network access is disabled by default. Pass a `NetworkConfig` to enable `curl` 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 `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 ------------- - Runs AI-generated bash scripts in pure PHP—no system shell required. - 58 built-in commands plus full bash builtins, pipes, and redirections. - Four filesystem backends with quota enforcement and path-traversal protection. - 18 configurable execution limits; violations throw a typed exception. - Network access is opt-in and restricted to explicit URL prefixes. - Integrates directly with the Laravel AI SDK as an agent tool. - Requires PHP 8.4+; zero additional Composer dependencies. --- *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) - [Sandboxing](https://www.msaied.com/articles?search=Sandboxing) - [Laravel AI SDK](https://www.msaied.com/articles?search=Laravel%20AI%20SDK) 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 operating against a virtual filesystem. How do you prevent a BashBox script from running indefinitely or consuming too many resources?The Limits class provides 18 configurable settings including maxCommandCount, maxLoopIterations, maxOutputSize, and maxCallDepth. Exceeding any limit throws a BashBox\\Exceptions\\ExecutionLimitException. You can also override limits per exec() call using ExecOptions. Can BashBox scripts make HTTP requests, and how is that controlled?Network access is disabled by default. You enable it by passing a NetworkConfig with an explicit allowedUrlPrefixes list and allowed HTTP methods. The denyPrivateRanges option (on by default) blocks loopback and private IP ranges, and each redirect target is validated against the allow-list. ![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/770/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) [ ![](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) 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)