If you are building AI agents that need to run shell commands — installing packages, manipulating files, running tests — you quickly hit a security wall. Letting an LLM execute arbitrary bash on your host is a recipe for disaster. Containers help, but they add latency, complexity, and operational overhead.
BashBox takes a different approach: a pure-PHP 8.4+ bash interpreter that runs entirely in-process, with a virtual filesystem, hard resource limits, and network access off by default. No proc_open, no exec, no containers. It is designed specifically for AI agents (including those built with the Laravel AI SDK) to execute generated shell code safely.
How it works
Every bash command is implemented as a PHP class. Every file operation goes through a FileSystemInterface with multiple backends. Every execution is bounded by configurable limits: command count, loop iterations, output size, recursion depth, script size, and a disk quota (64 MB / 10,000 entries by default).
use Shipfastlabs\BashBox\BashBox;
use Shipfastlabs\BashBox\Filesystem\InMemoryFs;
use Shipfastlabs\BashBox\Execution\ExecutionLimits;
$bash = new BashBox(
filesystem: new InMemoryFs(),
limits: new ExecutionLimits(
maxCommands: 10_000,
maxLoopIterations: 1_000,
maxOutputSize: 1024 * 1024, // 1 MB
maxRecursionDepth: 50,
)
);
$result = $bash->execute('find . -name "*.php" -exec grep -l "TODO" {} \;');
echo $result->getOutput();The InMemoryFs backend never touches the real disk. For cases where you need to read existing files, OverlayFs provides copy-on-write access to a real directory. ReadWriteFs and MountableFs offer progressively more access, each explicitly opted into.
Bash compatibility
BashBox implements 58+ commands including grep, sed, sort, find, xargs, sha256sum, curl (when network is enabled), and shell builtins: cd, export, source, read, trap, set/shopt options. It supports pipes, file-descriptor redirections (2>&1), here-docs, process substitution (<(cmd)), arrays, functions, control flow, and parameter expansion.
This is not a toy subset — it runs real bash scripts. The test suite validates compatibility against Bash 5.2 behavior.
Network access: opt-in only
Network is disabled by default. When you do need it, you configure an allow-list:
use Shipfastlabs\BashBox\Network\NetworkConfig;
$bash = new BashBox(
filesystem: new InMemoryFs(),
network: new NetworkConfig(
allowedPrefixes: ['https://api.github.com', 'https://registry.npmjs.org'],
denyPrivateRanges: true, // SSRF protection
stripRedirectHeaders: true, // prevent header leakage
maxResponseSize: 5 * 1024 * 1024,
)
);The denyPrivateRanges flag blocks access to RFC 1918 addresses, localhost, and link-local ranges — a critical SSRF defense when agents fetch attacker-controlled URLs. There is a dangerouslyAllowFullInternetAccess escape hatch for trusted environments, but it is explicitly named to discourage casual use.
Integration with AI agents
BashBox is built for the Laravel AI SDK's agent loop. A typical pattern: the agent proposes a bash command, your code approves or modifies it, BashBox executes it in the sandbox, and the result (stdout, stderr, exit code, filesystem changes) feeds back to the agent.
// Simplified agent tool wrapper
$tool = new \Laravel\Ai\Facades\Ai()
->tool('bash', fn (string $command) => $bash->execute($command))
->withApprovalRequired(); // human-in-the-loop for sensitive opsBecause execution is in-process, the round-trip is sub-millisecond. There is no container cold start, no gRPC overhead, no separate orchestration layer. The virtual filesystem means each agent session gets a clean slate unless you deliberately persist state via OverlayFs or MountableFs.
When to use it (and when not to)
Good fit:
AI agents that need to run shell commands (file ops, linting, tests, package installs)
Code-execution platforms, playgrounds, CI steps where untrusted scripts run
Any scenario where you need bash semantics but cannot afford container latency
Not a fit:
Workloads requiring kernel-level isolation (seccomp, namespaces, cgroups)
Scripts that depend on external binaries not implemented in BashBox (e.g.,
docker,kubectl, database clients)Long-running daemons — BashBox is designed for request/response style execution
The project is early (v0.0.3, MIT licensed) by Pushpak Chhajed, author of the Grant permissions package. The API will evolve, but the security model — no syscalls, virtual FS, default-deny network, explicit limits — is sound and unusual in the PHP ecosystem.
Takeaway
Running AI-generated shell code safely has always meant choosing two of: fast, simple, secure. BashBox picks a different point in the trade-off space: it runs in your PHP process, starts instantly, and enforces safety at the interpreter level. For Laravel teams building agentic workflows, it is worth a close look.
Sources
Laravel News: BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP (Oct 12, 2026)
GitHub: shipfastlabs/bashbox