Ehsan Bagherzadegan
Back to articles
4 min read

BashBox: Running AI-Generated Bash Safely in Pure PHP

BashBox is a pure-PHP 8.4+ sandboxed bash interpreter for AI agents — no exec, no containers, virtual filesystem, hard resource limits, and network off by default.

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 ops

Because 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