Skip to main content

​
Sandbox Cheat Sheet

​
Core Entry Points

use Cognesy\Sandbox\Config\ExecutionPolicy;
use Cognesy\Sandbox\Enums\SandboxDriver;
use Cognesy\Sandbox\Sandbox;

$policy = ExecutionPolicy::in(__DIR__);
$sandbox = Sandbox::fromPolicy($policy)->using(SandboxDriver::Host);
Static constructors:
  • Sandbox::fromPolicy(ExecutionPolicy $policy): Sandbox
  • Sandbox::host(ExecutionPolicy $policy): CanExecuteCommand
  • Sandbox::docker(ExecutionPolicy $policy, ?string $image = null, ?string $dockerBin = null): CanExecuteCommand
  • Sandbox::podman(ExecutionPolicy $policy, ?string $image = null, ?string $podmanBin = null): CanExecuteCommand
  • Sandbox::firejail(ExecutionPolicy $policy, ?string $firejailBin = null): CanExecuteCommand
  • Sandbox::bubblewrap(ExecutionPolicy $policy, ?string $bubblewrapBin = null): CanExecuteCommand
Driver selection:
  • using(string|SandboxDriver $driver): CanExecuteCommand (uses default image/binary for container drivers)

​
Driver Enum

SandboxDriver values:
  • SandboxDriver::Host (host)
  • SandboxDriver::Docker (docker)
  • SandboxDriver::Podman (podman)
  • SandboxDriver::Firejail (firejail)
  • SandboxDriver::Bubblewrap (bubblewrap)

​
ExecutionPolicy

Create policy:
  • ExecutionPolicy::default(): ExecutionPolicy (baseDir: /tmp)
  • ExecutionPolicy::in(string $baseDir): ExecutionPolicy
Defaults: timeout 5s, memory 128M, no idle timeout, no network, no env inheritance, 1MB output caps. Accessors:
  • baseDir(): string
  • timeoutSeconds(): int
  • idleTimeoutSeconds(): ?int
  • memoryLimit(): string
  • readablePaths(): array
  • writablePaths(): array
  • env(): array
  • inheritEnv(): bool
  • networkEnabled(): bool
  • stdoutLimitBytes(): int
  • stderrLimitBytes(): int
Immutable mutators:
  • withTimeout(int $seconds): self
  • withIdleTimeout(?int $seconds): self
  • withMemory(string $limit): self
  • withReadablePaths(string ...$paths): self
  • withWritablePaths(string ...$paths): self
  • withEnv(array $env, ?bool $inherit = null): self
  • inheritEnvironment(bool $inherit = true): self
  • withNetwork(bool $enabled): self
  • withOutputCaps(int $stdoutBytes, int $stderrBytes): self
  • with(?string $baseDir, ?int $timeoutSeconds, ?int $idleTimeoutSeconds, ?string $memoryLimit, ?array $readablePaths, ?array $writablePaths, ?array $env, ?bool $inheritEnv, ?bool $networkEnabled, ?int $stdoutLimitBytes, ?int $stderrLimitBytes): self (all params nullable, unset params keep current values)

​
Command Execution API

Contract (CanExecuteCommand): 
interface CanExecuteCommand {
    public function policy(): ExecutionPolicy;
    public function execute(array $argv, ?string $stdin = null, ?callable $onOutput = null): ExecResult;
}
Streaming callback:
  • Signature: fn(string $type, string $chunk): void
  • $type is 'out' or 'err'
Example: 
$result = $sandbox->execute(
    ['ls', '-la'],
    null,
    function (string $type, string $chunk): void {
        echo $chunk;
    }
);

​
ExecResult

Constructor: 
new ExecResult(
    string $stdout,
    string $stderr,
    int $exitCode,
    float $duration,
    bool $timedOut = false,
    bool $truncatedStdout = false,
    bool $truncatedStderr = false,
)
Getters:
  • stdout(): string
  • stderr(): string
  • exitCode(): int
  • duration(): float
  • timedOut(): bool
  • truncatedStdout(): bool
  • truncatedStderr(): bool
  • success(): bool
  • combinedOutput(): string
  • toArray(): array

​
Value Objects

Argv:
  • Argv::of(array $items): Argv
  • with(string $value): Argv
  • toArray(): array
CommandSpec:
  • new CommandSpec(Argv $argv, ?string $stdin = null)
  • argv(): Argv
  • stdin(): ?string

​
Testing

FakeSandbox (implements CanExecuteCommand):
  • new FakeSandbox(ExecutionPolicy $policy, array $responses = [], ?ExecResult $defaultResponse = null)
  • FakeSandbox::fromResponses(array $responses, ?ExecResult $defaultResponse = null): FakeSandbox
Responses format: array<string, list<ExecResult|array>> — each entry can be an ExecResult or an associative array with keys: stdout, stderr, exit_code, duration, timed_out, truncated_stdout, truncated_stderr.
  • policy(): ExecutionPolicy
  • commands(): array (recorded argv calls)
  • enqueue(string $commandKey, ExecResult $result): void
  • execute(array $argv, ?string $stdin = null, ?callable $onOutput = null): ExecResult
Command key format for queued responses:
  • 'cmd arg1 arg2' (joined with spaces)

​
Mount (container drivers)

Mount (used by Docker/Podman drivers for volume binds):
  • new Mount(string $host, string $container, string $options)
  • host(): string
  • container(): string
  • options(): string
  • toVolumeArg(): string (returns host:container:options)

​
TimeoutReason Enum

TimeoutReason values:
  • TimeoutReason::WALL (wall) — wall-clock timeout exceeded
  • TimeoutReason::IDLE (idle) — idle timeout exceeded

​
Exit Code Constants

ExitCodes:
  • ExitCodes::TIMEOUT = 124 (GNU timeout convention)

​
Useful Environment Variables

Driver binary overrides:
  • DOCKER_BIN
  • PODMAN_BIN
  • FIREJAIL_BIN
  • BWRAP_BIN