sandbox-exec.
Overview of Sandbox Tiers
Palyra categorizes its execution environments into three tiers, though the process runner specifically handles Tiers B and C.| Tier | Technology | Isolation Level | Primary Use Case |
|---|---|---|---|
| Tier A | WASM (Wasmtime) | Highest (Instruction-level) | Inline plugins, portable skills, high-density tools. |
| Tier B | rlimits / Unix | Medium (Resource-level) | Local scripts requiring native execution but constrained CPU/RAM. |
| Tier C | Bubblewrap / sandbox-exec | High (Namespace/Kernel) | OS-native binaries requiring filesystem and network virtualization. |
[crates/palyra-daemon/src/sandbox_runner.rs#64-78](http://crates/palyra-daemon/src/sandbox_runner.rs#64-78), [crates/palyra-daemon/src/tool_protocol.rs#13-18](http://crates/palyra-daemon/src/tool_protocol.rs#13-18)
Sandbox Process Runner Architecture
Thesandbox_runner.rs module in palyra-daemon is the primary orchestrator for non-WASM tool execution. It validates inputs, enforces egress policies, and dispatches commands to the appropriate backend via the palyra-sandbox crate.
Data Flow: Tool Call to Execution
The following diagram illustrates how a tool request is transformed into a sandboxed process. Process Execution Flow Sources:[crates/palyra-daemon/src/sandbox_runner.rs#147-209](http://crates/palyra-daemon/src/sandbox_runner.rs#147-209), [crates/palyra-sandbox/src/lib.rs#86-91](http://crates/palyra-sandbox/src/lib.rs#86-91)
Key Entities and Functions
run_constrained_process: The entry point for executing a tool in a sandbox. It performs all security checks before spawning.[crates/palyra-daemon/src/sandbox_runner.rs#147-151](http://crates/palyra-daemon/src/sandbox_runner.rs#147-151)SandboxProcessRunnerPolicy: A struct defining the constraints for the runner, includingcpu_time_limit_ms,memory_limit_bytes, andegress_enforcement_mode.[crates/palyra-daemon/src/sandbox_runner.rs#81-93](http://crates/palyra-daemon/src/sandbox_runner.rs#81-93)TierCBackend: A trait implemented for platform-specific sandboxing (e.g.,LinuxBubblewrapBackend,MacosSandboxExecBackend).[crates/palyra-sandbox/src/lib.rs#81-91](http://crates/palyra-sandbox/src/lib.rs#81-91)
Egress Enforcement Modes
Palyra provides granular control over network access for sandboxed processes throughEgressEnforcementMode.
- None: No network restrictions are applied at the sandbox level.
[crates/palyra-daemon/src/sandbox_runner.rs#48-48](http://crates/palyra-daemon/src/sandbox_runner.rs#48-48) - Preflight: The runner inspects the tool arguments (e.g., URLs passed to
curl) and validates them against an allowlist before execution.[crates/palyra-daemon/src/sandbox_runner.rs#49-49](http://crates/palyra-daemon/src/sandbox_runner.rs#49-49) - Strict: Combines Preflight checks with runtime kernel-level isolation (e.g.,
unshare-netin Bubblewrap).[crates/palyra-daemon/src/sandbox_runner.rs#50-50](http://crates/palyra-daemon/src/sandbox_runner.rs#50-50)
[crates/palyra-daemon/src/sandbox_runner.rs#47-62](http://crates/palyra-daemon/src/sandbox_runner.rs#47-62), [crates/palyra-daemon/src/sandbox_runner.rs#181-194](http://crates/palyra-daemon/src/sandbox_runner.rs#181-194)
Security Guardrails
Interpreter Denylist
To prevent shell injection and escape, Palyra maintains a denylist of common interpreters. These cannot be used as the primary executable unlessallow_interpreters is explicitly enabled in the policy.
The denylist includes: bash, sh, zsh, powershell, python, node, ruby, and others.
Sources: [crates/palyra-daemon/src/sandbox_runner.rs#30-44](http://crates/palyra-daemon/src/sandbox_runner.rs#30-44)
Path Traversal & Workspace Guards
The runner enforces that all file operations remain within the designatedworkspace_root.
canonical_workspace_root: Resolves the absolute path of the workspace.[crates/palyra-daemon/src/sandbox_runner.rs#172-172](http://crates/palyra-daemon/src/sandbox_runner.rs#172-172)validate_argument_workspace_scope: Iterates through all command-line arguments and ensures no path components attempt to traverse above the workspace root (e.g., using..).[crates/palyra-daemon/src/sandbox_runner.rs#175-180](http://crates/palyra-daemon/src/sandbox_runner.rs#175-180)
Tier-C Implementation (Platform Specifics)
Tier-C uses the most robust isolation available on the host operating system.| Platform | Backend | Code Entity | Isolation Mechanism |
|---|---|---|---|
| Linux | Bubblewrap | LinuxBubblewrapBackend | User namespaces, mount namespaces, seccomp. |
| macOS | sandbox-exec | MacosSandboxExecBackend | Seatbelt (AppSandbox) profiles. |
| Windows | Job Objects | WindowsJobObjectBackend | Resource limits and process grouping. |
bwrap is used to create a minimal environment. It mounts /usr, /bin, and /lib as read-only, provides a private /tmp, and binds the workspace root. If enforce_network_isolation is true, it adds the --unshare-net flag.
Sources: [crates/palyra-sandbox/src/lib.rs#8-13](http://crates/palyra-sandbox/src/lib.rs#8-13), [crates/palyra-sandbox/src/lib.rs#107-183](http://crates/palyra-sandbox/src/lib.rs#107-183)
Resource Quotas & Monitoring
The runner monitors process execution in real-time to enforce limits defined in theSandboxProcessRunnerPolicy.
- CPU/Memory: Tier-B uses Unix
rlimits. Tier-C uses backend-specific controls.[crates/palyra-daemon/src/sandbox_runner.rs#159-165](http://crates/palyra-daemon/src/sandbox_runner.rs#159-165) - Output Quota: The runner captures
stdoutandstderrin chunks. If the total bytes exceedmax_output_bytes, the process is immediately terminated.[crates/palyra-daemon/src/sandbox_runner.rs#219-227](http://crates/palyra-daemon/src/sandbox_runner.rs#219-227) - Timeouts: Processes are wrapped in a timer. If the
execution_timeoutis reached, the child process is killed.[crates/palyra-daemon/src/sandbox_runner.rs#210-218](http://crates/palyra-daemon/src/sandbox_runner.rs#210-218)
[crates/palyra-daemon/src/sandbox_runner.rs#203-227](http://crates/palyra-daemon/src/sandbox_runner.rs#203-227)