Execution Tier Overview
| Tier | Technology | Scope | Primary Use Case |
|---|---|---|---|
| Tier A | WASM (Wasmtime) | Language Runtime | High-performance plugins, portable skills, inline logic. |
| Tier B | Unix rlimit | OS Process | Native binaries on Unix systems with basic resource caps. |
| Tier C | bwrap / sandbox-exec | OS Virtualization | Strict filesystem/network isolation for native binaries. |
Tier A: WASM Plugin Runtime
Tier A execution leverages thewasmtime engine to provide a memory-safe, capability-based environment. This tier is managed by the WasmPluginRunnerPolicy and executed via run_wasm_plugin.
Capability-Based Security
Unlike native processes, WASM modules in Palyra have zero access to the host system by default. Access is granted throughCapabilityGrantSet, which maps specific host resources to virtual handles within the WASM guest.
- Fuel Budget: Execution is metered using Wasmtime “fuel” to prevent infinite loops crates/palyra-plugins/runtime/src/lib.rs#25-40.
- Memory Limits: Strict
max_memory_bytesenforcement crates/palyra-plugins/runtime/src/lib.rs#35-35. - Host Imports: The runtime provides specific imports for HTTP, Secrets, Storage, and Channels crates/palyra-plugins/runtime/src/lib.rs#3-9.
Code Entity Mapping: Tier A Execution
The following diagram shows the flow from a tool call to the WASM runtime. Title: Tier A WASM Execution Flow Sources: crates/palyra-daemon/src/wasm_plugin_runner.rs#96-126, crates/palyra-plugins/runtime/src/lib.rs#105-186Tier B & C: Process Sandboxing
For native binaries that cannot run in WASM, Palyra uses theSandboxProcessRunner. This component handles validation, workspace scoping, and execution via run_constrained_process.
Tier B: Resource Limits (Unix)
Tier B uses standard Unixsetrlimit (via the rlimit crate) to constrain CPU time and memory usage. It does not provide filesystem isolation beyond standard permission checks. It is primarily used when Tier C backends are unavailable or when lightweight isolation is sufficient.
Tier C: OS-Level Virtualization
Tier C provides the highest level of isolation for native processes by using platform-specific “jails”:- Linux: Uses
bwrap(Bubblewrap) to create new namespaces (PID, Network, Mount). It mounts a minimal root filesystem and bind-mounts only the required workspace crates/palyra-sandbox/src/lib.rs#130-182. - macOS: Uses
sandbox-execwith Seatbelt profiles to restrict syscalls and file access.
Execution Lifecycle
- Validation: The
execute_tool_callfunction validates the input againstMAX_PROCESS_RUNNER_TOOL_INPUT_BYTEScrates/palyra-daemon/src/tool_protocol.rs#144-144. - Workspace Scoping:
validate_argument_workspace_scopeensures all file paths in arguments reside within theworkspace_rootcrates/palyra-daemon/src/sandbox_runner.rs#175-180. - Interpreter Guardrails: A denylist (e.g.,
bash,python,node) prevents agents from escaping the sandbox via shell injection unless explicitly allowed by policy crates/palyra-daemon/src/sandbox_runner.rs#30-44.
Code Entity Mapping: Process Execution
Title: Native Process Sandbox Orchestration Sources: crates/palyra-daemon/src/sandbox_runner.rs#147-210, crates/palyra-sandbox/src/lib.rs#81-91Egress Enforcement Modes
Network isolation is managed throughEgressEnforcementMode, which determines how outbound requests from tools are handled:
- None: No network restrictions applied.
- Preflight: The daemon parses tool arguments to find URLs and checks them against
allowed_egress_hostsbefore spawning the process crates/palyra-daemon/src/sandbox_runner.rs#189-191. - Strict: Requires the underlying sandbox (Tier C) to enforce network isolation at the kernel/namespace level (e.g.,
--unshare-netinbwrap) crates/palyra-daemon/src/sandbox_runner.rs#192-194, crates/palyra-sandbox/src/lib.rs#176-178.
Quota and Output Enforcement
To prevent Denial of Service (DoS) attacks via log-flooding or memory exhaustion, the sandbox runner implements active monitoring of process output:- Output Quota:
max_output_bytesdefines the total allowed size forstdoutandstderr. - Chunked Capture: The runner polls the process pipes in
CAPTURE_CHUNK_BYTESincrements crates/palyra-daemon/src/sandbox_runner.rs#29-29. - Termination: If the cumulative output exceeds the quota, the runner immediately kills the child process and returns
SandboxProcessRunErrorKind::QuotaExceededcrates/palyra-daemon/src/sandbox_runner.rs#219-227.