​

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);

• 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

• using(string|SandboxDriver $driver): CanExecuteCommand (uses default image/binary for container drivers)

​

Driver Enum

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

​

ExecutionPolicy

• ExecutionPolicy::default(): ExecutionPolicy (baseDir: /tmp)
• ExecutionPolicy::in(string $baseDir): ExecutionPolicy

• baseDir(): string
• timeoutSeconds(): int
• idleTimeoutSeconds(): ?int
• memoryLimit(): string
• readablePaths(): array
• writablePaths(): array
• env(): array
• inheritEnv(): bool
• networkEnabled(): bool
• stdoutLimitBytes(): int
• stderrLimitBytes(): int

• 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

interface CanExecuteCommand {
    public function policy(): ExecutionPolicy;
    public function execute(array $argv, ?string $stdin = null, ?callable $onOutput = null): ExecResult;
}

• Signature: fn(string $type, string $chunk): void
• $type is 'out' or 'err'

$result = $sandbox->execute(
    ['ls', '-la'],
    null,
    function (string $type, string $chunk): void {
        echo $chunk;
    }
);

​

ExecResult

new ExecResult(
    string $stdout,
    string $stderr,
    int $exitCode,
    float $duration,
    bool $timedOut = false,
    bool $truncatedStdout = false,
    bool $truncatedStderr = false,
)

• stdout(): string
• stderr(): string
• exitCode(): int
• duration(): float
• timedOut(): bool
• truncatedStdout(): bool
• truncatedStderr(): bool
• success(): bool
• combinedOutput(): string
• toArray(): array

​

Value Objects

• Argv::of(array $items): Argv
• with(string $value): Argv
• toArray(): array

• new CommandSpec(Argv $argv, ?string $stdin = null)
• argv(): Argv
• stdin(): ?string

​

Testing

• new FakeSandbox(ExecutionPolicy $policy, array $responses = [], ?ExecResult $defaultResponse = null)
• FakeSandbox::fromResponses(array $responses, ?ExecResult $defaultResponse = null): FakeSandbox

• policy(): ExecutionPolicy
• commands(): array (recorded argv calls)
• enqueue(string $commandKey, ExecResult $result): void
• execute(array $argv, ?string $stdin = null, ?callable $onOutput = null): ExecResult

• 'cmd arg1 arg2' (joined with spaces)

​

Mount (container drivers)

• new Mount(string $host, string $container, string $options)
• host(): string
• container(): string
• options(): string
• toVolumeArg(): string (returns host:container:options)

​

TimeoutReason Enum

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

​

Exit Code Constants

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

​

Useful Environment Variables

• DOCKER_BIN
• PODMAN_BIN
• FIREJAIL_BIN
• BWRAP_BIN