palyra.process.run tool. It provides a multi-tiered isolation strategy for executing arbitrary shell commands and binaries, ranging from direct host execution with resource constraints to fully isolated containerized environments. It enforces strict security guardrails including executable allowlisting, path scoping, and egress network control.
Execution Tiers
Palyra implements a tiered isolation model to balance performance and security requirements. The runner selects the appropriate tier based on theSandboxProcessRunnerPolicy configured for the session crates/palyra-daemon/src/sandbox_runner.rs#5-13.
| Tier | Isolation Mechanism | Description |
|---|---|---|
| Tier B | Direct Spawn + rlimits | Spawns the child process directly on the host with a scrubbed environment, workspace-scoped path arguments, and Unix rlimit quotas crates/palyra-daemon/src/sandbox_runner.rs#6-7. |
| Tier C | Sandbox Backends | Delegates isolation to specialized backends like Docker, bubblewrap, or sandbox_exec. It fails closed if the requested network isolation cannot be enforced crates/palyra-daemon/src/sandbox_runner.rs#8-10. |
Tier B Implementation
Tier B relies on host-level OS primitives. On Unix-like systems, it appliesrlimit quotas to bound CPU and memory usage crates/palyra-daemon/src/sandbox_runner.rs#6-7. On Windows, it utilizes Job Objects to ensure process trees are managed together and terminated cleanly crates/palyra-daemon/src/sandbox_runner.rs#41-50.
Tier C Implementation
Tier C usespalyra-sandbox to build a TierCCommandPlan crates/palyra-daemon/src/sandbox_runner.rs#66-69. This plan abstracts the specific container or sandbox technology, ensuring that egress policies and filesystem mounts are applied consistently across different backends.
Sources: crates/palyra-daemon/src/sandbox_runner.rs#1-15, crates/palyra-daemon/src/sandbox_runner.rs#66-70.
Security Guardrails
The runner operates on a deny-by-default principle. Every validation failure results in a security rejection crates/palyra-daemon/src/sandbox_runner.rs#14-15.1. Input Validation and Caps
To prevent resource exhaustion or injection attacks at the invocation level, the runner enforces hard limits on the input shape:- Max Command Length: 256 characters crates/palyra-daemon/src/sandbox_runner.rs#75.
- Max Argument Count: 128 crates/palyra-daemon/src/sandbox_runner.rs#76.
- Max Environment Variables: 32 crates/palyra-daemon/src/sandbox_runner.rs#78.
2. Executable Allowlisting
The runner checks the requested command againstallowed_executables. Additionally, common interpreters (e.g., bash, python, node) are explicitly denylisted unless the allow_interpreters policy is enabled crates/palyra-daemon/src/sandbox_runner.rs#138-152.
3. Environment Scrubbing
To prevent the leakage of daemon secrets (like provider API keys or vault paths), the child process environment is rebuilt from a small allowlist of safe keys, such asHOME, USER, and LANG crates/palyra-daemon/src/sandbox_runner.rs#119-122.
4. Egress Enforcement
Outbound network access is policed viaEgressEnforcementMode crates/palyra-daemon/src/sandbox_runner.rs#156-157:
- Strict: Only explicitly allowed hosts are reachable.
- Block All: No network access permitted.
- Allow All: (Not recommended for untrusted code).
Process Lifecycle and Management
The runner supports both foreground (synchronous) and background (asynchronous) execution modes.Background Processes
Background processes are governed by aBackgroundLifetimeMode crates/palyra-common/src/process_runner_input.rs#12-24:
- RunOwned: Process is terminated when the agent run ends.
- Detached: Process continues until its bounded lifetime (max 30 minutes) expires crates/palyra-daemon/src/sandbox_runner.rs#113.
Output Capture and Redaction
The runner capturesstdout and stderr in chunks (default 4KB) crates/palyra-daemon/src/sandbox_runner.rs#86. Before output is returned to the model, it passes through a redaction pipeline that scrubs sensitive URL segments (e.g., token, password) crates/palyra-daemon/src/sandbox_runner.rs#130-133.
Execution Flow Diagram
Sources: crates/palyra-daemon/src/sandbox_runner.rs#1-3, crates/palyra-common/src/process_runner_input.rs#47-67, crates/palyra-daemon/src/sandbox_runner.rs#130-133.Windows Job Objects
On Windows, Palyra usesCreateJobObjectW and AssignProcessToJobObject to manage the lifecycle of spawned processes crates/palyra-daemon/src/sandbox_runner.rs#42-50.
Key features include:
- Kill on Close: Ensuring that if the daemon or the runner handle closes, the entire process tree is terminated crates/palyra-daemon/src/sandbox_runner.rs#48.
- Resource Accounting: Using
JobObjectBasicAccountingInformationto track CPU and memory usage across the process group crates/palyra-daemon/src/sandbox_runner.rs#47.
Tool Registration and Schema
Thepalyra.process.run tool is registered as a builtin tool with a specific JSON schema that defines the model’s interface.
Sources: crates/palyra-daemon/src/application/tool_registry/builtin.rs#23-25, crates/palyra-common/src/process_runner_input.rs#47-67.