run_constrained_process function [crates/palyra-daemon/src/sandbox_runner.rs#147-151] which enforces policies defined in SandboxProcessRunnerPolicy [crates/palyra-daemon/src/sandbox_runner.rs#81-93].
Execution Tier Overview
| Tier | Technology | Isolation Level | Primary Use Case |
|---|---|---|---|
| Tier A | WebAssembly (Wasmtime) | Instruction-level (SFI) | Plugins, Skills, and lightweight tools. |
| Tier B | rlimit + Path Validation | OS Resource Limits | Local process execution on Unix-like systems. |
| Tier C | Bubblewrap / sandbox-exec | Kernel Namespaces / MAC | High-risk OS process execution with network/FS isolation. |
Tier A: WebAssembly Isolation
Tier A utilizes thepalyra-plugins-runtime crate, powered by wasmtime, to execute code in a Software Fault Isolation (SFI) environment [crates/palyra-plugins-runtime/src/lib.rs#105-108].
- Implementation: Uses
WasmRuntimeto manage engines and stores [crates/palyra-plugins-runtime/src/lib.rs#110-121]. - Guardrails: Enforces
RuntimeLimitsincluding fuel budget (CPU), memory allocation, and table elements [crates/palyra-plugins-runtime/src/lib.rs#24-29]. - Capabilities: Guest modules cannot access the host unless explicitly granted via
CapabilityGrantSet(e.g., specific HTTP hosts, secrets, or storage prefixes) [crates/palyra-plugins-runtime/src/lib.rs#42-48]. - Entry Point:
run_wasm_pluginhandles the lifecycle of loading, validating, and executing Wasm modules [crates/palyra-daemon/src/wasm_plugin_runner.rs#96-126].
Tier B: OS Resource Constraints
Tier B is designed for Unix-based systems where full kernel namespacing (Tier C) might be overkill or unavailable, but resource consumption must still be capped.- Resource Limits: Uses standard Unix
rlimitmechanisms (implemented vialibcin the runner) to enforce CPU time and memory quotas [crates/palyra-daemon/src/sandbox_runner.rs#159-165]. - Path Validation: Before spawning, the runner validates that the command and arguments do not escape the
workspace_root[crates/palyra-daemon/src/sandbox_runner.rs#175-180]. - Interpreter Guardrails: Prevents the execution of dangerous interpreters (e.g.,
bash,python,node) unless explicitly allowed by policy [crates/palyra-daemon/src/sandbox_runner.rs#30-44].
Tier C: Kernel-Level Sandboxing
Tier C provides the strongest isolation by leveraging platform-specific sandboxing tools to create a restricted view of the operating system.- Linux (Bubblewrap): Uses
bwrapto create new PID, network, and mount namespaces. It mounts a minimal/proc,/dev, and a read-only/usrscaffold, while binding only the specificworkspace_rootas writable [crates/palyra-sandbox/src/lib.rs#130-182]. - macOS (sandbox-exec): Uses the macOS Seatbelt (AppSandbox) framework. It generates a temporary
.sbprofile that restricts the process to the workspace directory and limits network access [crates/palyra-sandbox/src/lib.rs#8-10]. - Windows (Job Objects): (Planned/Partial) Uses Job Objects for resource accounting and basic restriction [crates/palyra-sandbox/src/lib.rs#11-13].
Sandbox Data Flow and Enforcement
The following diagram illustrates how a tool call is processed from a request into a sandboxed execution environment. Sandbox Execution Pipeline Sources:[crates/palyra-daemon/src/sandbox_runner.rs#147-209](http://crates/palyra-daemon/src/sandbox_runner.rs#147-209), [crates/palyra-daemon/src/tool_protocol.rs#20-26](http://crates/palyra-daemon/src/tool_protocol.rs#20-26), [crates/palyra-sandbox/src/lib.rs#81-91](http://crates/palyra-sandbox/src/lib.rs#81-91).
Key Security Components
1. Egress Enforcement Modes
TheEgressEnforcementMode [crates/palyra-daemon/src/sandbox_runner.rs#47-51] determines how network access is handled:
- None: No network restrictions.
- Preflight: Hosts are checked against
allowed_egress_hostsbefore the process starts, but not enforced at the kernel level [crates/palyra-daemon/src/sandbox_runner.rs#189-191]. - Strict: Requires the Tier C backend to support
runtime_network_isolation. If the backend cannot enforce it (e.g., on certain macOS versions), the execution fails [crates/palyra-daemon/src/sandbox_runner.rs#192-194].
2. Workspace Root Scoping
The sandbox ensures that all file operations are relative to a definedworkspace_root.
- Canonicalization: The root is canonicalized to prevent symlink attacks [crates/palyra-daemon/src/sandbox_runner.rs#172].
- Scoping:
validate_argument_workspace_scopechecks every argument passed to the process to ensure no paths point outside the workspace [crates/palyra-daemon/src/sandbox_runner.rs#175-180].
3. Interpreter Guardrails
To prevent “jailbreaking” the sandbox via shell escapes,INTERPRETER_EXECUTABLE_DENYLIST [crates/palyra-daemon/src/sandbox_runner.rs#30-44] blocks common shells and language runtimes unless allow_interpreters is explicitly set to true in the policy [crates/palyra-daemon/src/sandbox_runner.rs#86].
Implementation Mapping
The relationship between the sandbox configuration and the underlying system execution. Policy to Executor Mapping Sources:[crates/palyra-daemon/src/sandbox_runner.rs#81-93](http://crates/palyra-daemon/src/sandbox_runner.rs#81-93), [crates/palyra-sandbox/src/lib.rs#81-91](http://crates/palyra-sandbox/src/lib.rs#81-91), [crates/palyra-daemon/src/sandbox_runner.rs#147-151](http://crates/palyra-daemon/src/sandbox_runner.rs#147-151).
Summary of Constraints
The sandbox enforces several hard limits defined inSandboxProcessRunnerPolicy:
- CPU:
cpu_time_limit_ms[crates/palyra-daemon/src/sandbox_runner.rs#90]. - Memory:
memory_limit_bytes[crates/palyra-daemon/src/sandbox_runner.rs#91]. - Output:
max_output_bytesto prevent log-bombing or OOM during capture [crates/palyra-daemon/src/sandbox_runner.rs#92]. - Time: Execution timeout that terminates the process if it hangs [crates/palyra-daemon/src/sandbox_runner.rs#210-218].