Skip to main content
The Sandbox Process Runner is a security-critical component responsible for executing arbitrary system commands and scripts on behalf of agents. It implements a multi-tiered defense-in-depth strategy to isolate processes, enforce resource quotas, and restrict network and filesystem access.

​
Architecture Overview

The runner operates by transforming a ProcessRunnerToolInput into a constrained OS process. It uses two distinct tiers of isolation:
  • Tier B: Uses standard Unix rlimit controls and environment scrubbing.
  • Tier C: Leverages platform-specific containerization or sandboxing technologies (Bubblewrap, sandbox-exec, Job Objects).

​
Process Execution Flow

The following diagram illustrates the lifecycle of a constrained process from validation to termination. Sandbox Execution Pipeline Sources: [crates/palyra-daemon/src/sandbox_runner.rs#147-210](http://crates/palyra-daemon/src/sandbox_runner.rs#147-210), [crates/palyra-daemon/src/sandbox_runner.rs#120-126](http://crates/palyra-daemon/src/sandbox_runner.rs#120-126)

​
Workspace Scope and Validation

Before execution, the runner performs several “fail-closed” validation steps to ensure the process cannot escape its intended context.

​
Workspace Validation

The workspace_root is canonicalized using canonical_workspace_root [crates/palyra-daemon/src/sandbox_runner.rs#172-172](http://crates/palyra-daemon/src/sandbox_runner.rs#172-172). All arguments passed to the command are scanned for paths; any path that resolves outside the workspace_root results in a WorkspaceScopeDenied error [crates/palyra-daemon/src/sandbox_runner.rs#175-180](http://crates/palyra-daemon/src/sandbox_runner.rs#175-180).

​
Interpreter Guardrails

To prevent agents from bypassing allowed_executables via shell scripts, the runner enforces strict guardrails on interpreters.
  • Denylist: Common shells and runtimes (e.g., bash, python, node) are blocked unless allow_interpreters is explicitly true [crates/palyra-daemon/src/sandbox_runner.rs#30-44](http://crates/palyra-daemon/src/sandbox_runner.rs#30-44).
  • Argument Scrubbing: validate_interpreter_argument_guardrails checks for dangerous flags like -c or --eval that would allow arbitrary code execution through an allowed interpreter [crates/palyra-daemon/src/sandbox_runner.rs#170-170](http://crates/palyra-daemon/src/sandbox_runner.rs#170-170).
Sources: [crates/palyra-daemon/src/sandbox_runner.rs#81-93](http://crates/palyra-daemon/src/sandbox_runner.rs#81-93), [crates/palyra-daemon/src/sandbox_runner.rs#168-170](http://crates/palyra-daemon/src/sandbox_runner.rs#168-170)

​
Egress Enforcement Modes

The runner manages network access via the EgressEnforcementMode enum [crates/palyra-daemon/src/sandbox_runner.rs#47-51](http://crates/palyra-daemon/src/sandbox_runner.rs#47-51).
ModeDescriptionEnforcement Mechanism
NoneNo network restrictions.None.
PreflightValidates requested hosts against an allowlist before spawning.collect_requested_egress_hosts parses CLI args.
StrictCombines Preflight with runtime kernel-level blocking.Requires Tier C (e.g., Bubblewrap --unshare-net).
In Strict mode, if the platform backend cannot enforce network isolation (e.g., TierCBackendCapabilities.runtime_network_isolation is false), the process will fail to spawn [crates/palyra-daemon/src/sandbox_runner.rs#192-194](http://crates/palyra-daemon/src/sandbox_runner.rs#192-194). Sources: [crates/palyra-daemon/src/sandbox_runner.rs#181-194](http://crates/palyra-daemon/src/sandbox_runner.rs#181-194), [crates/palyra-sandbox/src/lib.rs#59-63](http://crates/palyra-sandbox/src/lib.rs#59-63)

​
Tier C Backends

Tier C provides the strongest isolation by wrapping the command in platform-native sandbox utilities. Tier C Entity Mapping

​
Linux: Bubblewrap (bwrap)

Uses bwrap to create a new namespace. It unshares PIDs, mounts a minimal /proc, and provides a read-only bind mount for system libraries (/usr, /lib) while bind-mounting the workspace as the only writable area [crates/palyra-sandbox/src/lib.rs#130-175](http://crates/palyra-sandbox/src/lib.rs#130-175).

​
macOS: sandbox-exec

Uses the native Seatbelt (sandbox-exec) facility. It generates a temporary .sb profile that denies all network access and restricts filesystem operations to the workspace root [crates/palyra-sandbox/src/lib.rs#10-10](http://crates/palyra-sandbox/src/lib.rs#10-10).

​
Windows: Job Objects

Utilizes WindowsJobObject to group the child process and its descendants, allowing for strict memory limits and ensuring all sub-processes are terminated when the parent handle closes [crates/palyra-sandbox/src/lib.rs#20-26](http://crates/palyra-sandbox/src/lib.rs#20-26). Sources: [crates/palyra-sandbox/src/lib.rs#8-35](http://crates/palyra-sandbox/src/lib.rs#8-35), [crates/palyra-sandbox/src/lib.rs#107-184](http://crates/palyra-sandbox/src/lib.rs#107-184)

​
Resource Quotas and Output Limits

The runner enforces three primary resource constraints:
  1. CPU/Memory: In Tier B (Unix), rlimit is used. In Tier C, platform-specific limits (like bwrap cgroups or Windows Job Objects) are applied [crates/palyra-daemon/src/sandbox_runner.rs#90-91](http://crates/palyra-daemon/src/sandbox_runner.rs#90-91).
  2. Timeout: A Duration is enforced via execute_process. If exceeded, the child is killed and SandboxProcessRunErrorKind::TimedOut is returned [crates/palyra-daemon/src/sandbox_runner.rs#210-217](http://crates/palyra-daemon/src/sandbox_runner.rs#210-217).
  3. Output Quota: The max_output_bytes policy [crates/palyra-daemon/src/sandbox_runner.rs#92-92](http://crates/palyra-daemon/src/sandbox_runner.rs#92-92) is enforced by StreamCapture.

​
Output Enforcement Implementation

The runner does not wait for process completion to check output size. Instead, it polls stdout and stderr in chunks defined by CAPTURE_CHUNK_BYTES (4KB) [crates/palyra-daemon/src/sandbox_runner.rs#29-29](http://crates/palyra-daemon/src/sandbox_runner.rs#29-29). If the cumulative byte count exceeds max_output_bytes, the runner immediately terminates the child process and returns QuotaExceeded [crates/palyra-daemon/src/sandbox_runner.rs#219-227](http://crates/palyra-daemon/src/sandbox_runner.rs#219-227). Sources: [crates/palyra-daemon/src/sandbox_runner.rs#25-29](http://crates/palyra-daemon/src/sandbox_runner.rs#25-29), [crates/palyra-daemon/src/sandbox_runner.rs#203-227](http://crates/palyra-daemon/src/sandbox_runner.rs#203-227)

​
Tool Protocol Integration

The SandboxProcessRunnerPolicy is a sub-component of the ToolCallConfig [crates/palyra-daemon/src/tool_protocol.rs#24-24](http://crates/palyra-daemon/src/tool_protocol.rs#24-24). When a tool requires ProcessExec capabilities [crates/palyra-daemon/src/tool_protocol.rs#48-48](http://crates/palyra-daemon/src/tool_protocol.rs#48-48), the tool_protocol invokes run_constrained_process. The resulting ToolAttestation includes the executor (e.g., sandbox_tier_c_linux_bubblewrap) and the sandbox_enforcement level to provide an audit trail of how the process was isolated [crates/palyra-daemon/src/tool_protocol.rs#73-80](http://crates/palyra-daemon/src/tool_protocol.rs#73-80). Sources: [crates/palyra-daemon/src/tool_protocol.rs#19-26](http://crates/palyra-daemon/src/tool_protocol.rs#19-26), [crates/palyra-daemon/src/tool_protocol.rs#151-172](http://crates/palyra-daemon/src/tool_protocol.rs#151-172)