Three-Tier Sandbox Architecture
The execution environment is divided into three distinct tiers, each offering a different trade-off between capability and isolation.| Tier | Technology | Scope | Primary Use Case |
|---|---|---|---|
| Tier-A | Wasmtime (WebAssembly) | Full Instruction Isolation | Third-party skills, untrusted logic, and cross-platform plugins. |
| Tier-B | rlimits / POSIX | Resource Constraints | Local process execution with CPU/Memory/FD limits on Unix systems. |
| Tier-C | bwrap / sandbox-exec | OS-Level Namespacing | Hardened isolation for system commands (Bubblewrap on Linux, sandbox-exec on macOS). |
Tier-A: Wasm Runtime
Tier-A useswasmtime to execute WebAssembly modules. It provides the highest level of isolation by abstracting the entire instruction set and memory space. Execution is metered using “fuel” to prevent infinite loops and memory exhaustion.
Tier-B: Resource Limits
Tier-B is implemented incrates/palyra-daemon/src/sandbox_runner.rs. It focuses on restricting the impact of a process on the host system using standard Unix resource controls.
- CPU Time: Enforced via
RLIMIT_CPUcrates/palyra-daemon/src/sandbox_runner.rs#811-814. - Memory: Enforced via
RLIMIT_ASorRLIMIT_DATAcrates/palyra-daemon/src/sandbox_runner.rs#815-818. - Output Quota: Monitored via a background thread that polls and kills the process if
max_output_bytesis exceeded crates/palyra-daemon/src/sandbox_runner.rs#219-227.
Tier-C: Kernel Isolation
Tier-C leverages platform-specific sandboxing tools to create a restricted view of the filesystem and network.- Linux: Uses
bwrap(Bubblewrap) to create new PID, mount, and network namespaces crates/palyra-sandbox/src/lib.rs#130-144. - macOS: Uses
sandbox-execwith a generated Scheme profile to restrict file access and network sockets crates/palyra-sandbox/src/lib.rs#250-265.
Tool Execution Pipeline
When a model or agent requests a tool call (e.g.,palyra.process.run), the request passes through a validation and execution pipeline managed by the tool_protocol.
Execution Flow Diagram
This diagram bridges theToolCallConfig and PolicyDecision entities to the underlying execution functions.
“Tool Execution Flow”
Sources:
Validation and Guardrails
Before any process is spawned, thesandbox_runner performs a series of “Preflight” checks to ensure the command does not violate safety boundaries.
- Executable Denylist: Common shells (e.g.,
bash,powershell,node) are blocked by default to prevent script injection and escape crates/palyra-daemon/src/sandbox_runner.rs#30-44. - Workspace Anchoring: Commands and arguments are validated to ensure they only refer to paths within the configured
workspace_root. Any attempt to use..or absolute paths outside the root results in aWorkspaceScopeDeniederror crates/palyra-daemon/src/sandbox_runner.rs#172-180. - Input Shape: The JSON payload is parsed into
ProcessRunnerToolInputand checked for maximum argument counts and lengths crates/palyra-common/src/process_runner_input.rs#7-17.
Egress Enforcement Modes
Palyra manages network access through three modes defined inEgressEnforcementMode crates/palyra-daemon/src/sandbox_runner.rs#47-62:
- None: No network restrictions applied.
- Preflight: Validates the
requested_egress_hostsagainst theallowed_egress_hostslist in the policy before execution. - Strict: Requires the underlying Tier-C backend to support runtime network isolation (e.g.,
unshare-netin Bubblewrap). If the backend cannot enforce it, the execution is denied crates/palyra-daemon/src/sandbox_runner.rs#192-194.
crates/palyra-daemon/src/sandbox_runner.rs167-196crates/palyra-common/src/process_runner_input.rs26-31
Output Quota and Capture
To prevent Denial of Service (DoS) via log flooding or massive output, the sandbox capturesstdout and stderr with a strict quota.
Capture Mechanism
Theexecute_process function initializes a StreamCapture for both output pipes. A monitoring loop reads chunks of data (default 4KB) and increments an AtomicUsize counter.
“Output Capture & Quota Logic”
If the total bytes read from both streams exceed the max_output_bytes defined in the SandboxProcessRunnerPolicy, the child process is immediately terminated crates/palyra-daemon/src/sandbox_runner.rs#219-227.
Sources:
Implementation Details: Tier-C Backends
Thepalyra-sandbox crate abstracts the complexities of platform-specific isolation into the TierCBackend trait crates/palyra-sandbox/src/lib.rs#81-91.
Linux (Bubblewrap)
TheLinuxBubblewrapBackend builds a command plan that:
- Clears the environment variables crates/palyra-sandbox/src/lib.rs#165.
- Mounts a minimal
/proc,/dev, and/tmpcrates/palyra-sandbox/src/lib.rs#133-141. - Read-only binds essential system libraries (
/usr,/lib, etc.) crates/palyra-sandbox/src/lib.rs#145-147. - Binds the
workspace_rootwith write access crates/palyra-sandbox/src/lib.rs#158-163.
macOS (sandbox-exec)
TheMacosSandboxExecBackend generates a temporary profile using the (version 1) syntax, specifically allowing file-read* and file-write* only for the workspace directory and necessary system paths.
Sources: