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/774/9ffc1bfe88806626f495f3ef307e0b69.png) On this page +1. [What Is BashBox?](#what-is-bashbox) 2. [Running Scripts](#running-scripts) 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](https://github.com/pushpak1300). 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 control. It requires PHP 8.4 or later, has no additional Composer dependencies, and is MIT licensed (current release: v0.0.3). ```bash composer require shipfastlabs/bashbox ``` Running Scripts --------------- Create a `Bash` instance and pass a script 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 ``` 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: ```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 provide real-file access: - **`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 default quota of 64 MB and 10,000 entries. Exceeding the quota fails 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 allow 10,000 commands per script, 10,000 loop iterations, 10 MB of output, and a call depth of 100. Per-call overrides are available via `ExecOptions`. Network Access -------------- Network access is disabled by default. Pass a `NetworkConfig` to enable 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 `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 `exec`, `proc_open`, or `shell_exec`. - Ships 58 commands and a full set of bash builtins out of the box. - Four filesystem backends, from fully in-memory to real-disk mounts. - 18 configurable execution limits with per-call overrides. - Network access is opt-in with URL prefix allow-lists and private-range blocking. - Integrates directly with the Laravel AI SDK as an agent tool. - Requires PHP 8.4+, zero extra Composer dependencies, MIT licensed. --- *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 real shell binary like /bin/bash or /bin/sh?No. BashBox is a pure-PHP interpreter. It never calls proc\_open, exec, shell\_exec, or any shell binary. Every command is implemented as a PHP class operating against a virtual filesystem. Can BashBox scripts access the real server filesystem?Only if you configure it to. The default InMemoryFs backend never touches disk. You can opt in to real-file access via OverlayFs (copy-on-write reads), ReadWriteFs (confined to a root directory), or MountableFs (mixed backends at different mount points). What happens when an AI agent generates a script that exceeds execution limits?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, and override them per exec() call using ExecOptions. ![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 Scripts](#running-scripts) 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/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) [ ![](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) 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)