Skip to main content

​
Introduction

The Sandbox package provides a unified API for executing shell commands with controlled resource limits and configurable isolation. Whether you need to run a quick script on the host machine or execute untrusted code inside a locked-down container, Sandbox gives you a single, consistent interface backed by pluggable drivers. Every execution is governed by an immutable ExecutionPolicy that defines timeout limits, memory caps, network access, environment variables, and file-system boundaries. The policy travels with the sandbox instance, ensuring that your constraints are always enforced regardless of which driver you choose.

​
Core Architecture

The package is built around four primary components:

​
Sandbox

The Sandbox class is the main entry point. It accepts an ExecutionPolicy and produces a driver instance that implements the CanExecuteCommand contract. You can select a driver through static factory methods (Sandbox::host(), Sandbox::docker(), etc.) or dynamically via the SandboxDriver enum. 
use Cognesy\Sandbox\Sandbox;
use Cognesy\Sandbox\Config\ExecutionPolicy;

// Static factory
$sandbox = Sandbox::host(ExecutionPolicy::in('/tmp'));

// Dynamic selection
$sandbox = Sandbox::fromPolicy($policy)->using('docker');
// @doctest id="a971"

​
ExecutionPolicy

The ExecutionPolicy is an immutable configuration object that controls every aspect of command execution. Each with*() method returns a new instance, making policies safe to share and compose without side effects. 
$policy = ExecutionPolicy::in('/tmp')
    ->withTimeout(30)
    ->withMemory('256M')
    ->withNetwork(false);
// @doctest id="d83b"

​
CanExecuteCommand

All drivers implement the CanExecuteCommand interface, which exposes an execute() method and a policy() accessor. This contract guarantees that you can swap drivers without changing any calling code, making it straightforward to use the host driver in development and a container driver in production. 
use Cognesy\Sandbox\Contracts\CanExecuteCommand;

function runScript(CanExecuteCommand $sandbox): string {
    $result = $sandbox->execute(['php', 'script.php']);
    return $result->stdout();
}
// @doctest id="1574"

​
ExecResult

Every execution returns an ExecResult — a readonly value object that provides access to stdout, stderr, the exit code, wall-clock duration, and flags indicating whether the output was truncated or the command timed out. 
$result = $sandbox->execute(['php', '-v']);

$result->stdout();          // Captured standard output
$result->stderr();          // Captured standard error
$result->exitCode();        // Process exit code (0 = success)
$result->success();         // true when exit code is 0 and no timeout
$result->duration();        // Wall-clock seconds as float
$result->timedOut();        // true if wall or idle timeout was hit
$result->truncatedStdout(); // true if stdout exceeded the cap
$result->truncatedStderr(); // true if stderr exceeded the cap
$result->combinedOutput();  // stdout + stderr joined
$result->toArray();         // Full result as associative array
// @doctest id="a583"

​
Supported Drivers

The package ships with five drivers, each offering a different level of isolation:
DriverIsolationPlatformUse Case
HostNone (process-level only)AllDevelopment, trusted scripts
DockerFull containerLinux, macOS, WindowsProduction workloads, untrusted code
PodmanFull container (rootless)LinuxRootless container execution
FirejailLinux namespaces + seccompLinuxLightweight sandboxing without containers
BubblewrapLinux namespacesLinuxMinimal sandbox with namespace isolation
All drivers enforce the same ExecutionPolicy constraints and return the same ExecResult type, so your application code remains driver-agnostic.

​
Security Defaults

The package ships with secure defaults that apply across all drivers:
  • Network disabled — Commands cannot reach external services unless you explicitly call withNetwork(true).
  • Environment scrubbed — Security-sensitive variables (AWS_*, LD_PRELOAD, GOOGLE_APPLICATION_CREDENTIALS, etc.) are always stripped, even when environment inheritance is enabled.
  • Output bounded — Both stdout and stderr are capped at 1 MB by default. When exceeded, only the most recent bytes are retained.
  • Timeout enforced — Commands are terminated after 5 seconds by default. Both wall-clock and idle timeouts are supported.
  • Container hardening — Docker and Podman drivers run with a read-only root filesystem, all capabilities dropped, no-new-privileges set, and commands execute as the nobody user (UID 65534).

​
Documentation

  • Getting Started — Run your first sandboxed command in three steps.
  • Execution Policy — Configure timeouts, memory, paths, environment, network, and output limits.
  • Drivers — Choose and configure the right isolation backend.
  • Streaming and Results — Consume output in real time and inspect execution results.
  • Testing — Use FakeSandbox for fast, deterministic tests.
  • Troubleshooting — Diagnose and resolve common issues.