Execution Tier Overview
Tool execution is governed by theToolCallConfig crates/palyra-daemon/src/tool_protocol.rs#20-26, which defines the available tiers and their respective policies.
| Tier | Technology | Enforcement Mechanism | Use Case |
|---|---|---|---|
| Tier-A | WebAssembly (WASM) | wasmtime fuel, memory limits, and capability grants. | Plugins, untrusted logic, and cross-platform skills. |
| Tier-B | Unix rlimits | setrlimit for CPU time and memory consumption. | Local process execution on Unix-like systems. |
| Tier-C | Kernel Sandboxing | bwrap (Linux) or sandbox-exec (macOS). | High-risk CLI tools, filesystem isolation, and network egress control. |
Sandbox Tier Logic Flow
The following diagram illustrates how thepalyrad daemon dispatches a tool call to the appropriate sandbox tier based on the SandboxProcessRunnerTier crates/palyra-daemon/src/sandbox_runner.rs#65-68.
Title: Tool Execution Dispatch Pipeline
Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-69, crates/palyra-daemon/src/sandbox_runner.rs#147-151, crates/palyra-sandbox/src/lib.rs#86-91
Tier-A: WebAssembly (WASM) Sandbox
Tier-A execution uses thepalyra-plugins runtime, powered by wasmtime. It enforces strict resource quotas and capability-based security.
- Fuel Budgeting: Limits the number of instructions executed to prevent infinite loops crates/palyra-daemon/src/tool_protocol.rs#119.
- Memory Limits: Caps the linear memory available to the WASM instance crates/palyra-daemon/src/tool_protocol.rs#120.
- Capability Grants: WASM modules are denied all I/O by default. Access to HTTP hosts, secrets, or specific filesystem prefixes must be explicitly granted in the
WasmPluginRunnerPolicycrates/palyra-daemon/src/tool_protocol.rs#123-126.
Tier-B & Tier-C: Process Sandboxing
For native binaries, Palyra provides two levels of process isolation. Both tiers share common validation logic inrun_constrained_process crates/palyra-daemon/src/sandbox_runner.rs#147-210.
Workspace Scope Guards
Before execution, the runner validates that the command and its arguments do not escape the designatedworkspace_root crates/palyra-daemon/src/sandbox_runner.rs#172-180.
- Interpreter Denylist: Common shells and runtimes like
bash,python, andnodeare blocked by default unlessallow_interpretersis set crates/palyra-daemon/src/sandbox_runner.rs#30-44. - Path Canonicalization: All paths are resolved to their absolute forms to prevent symlink attacks crates/palyra-daemon/src/sandbox_runner.rs#172.
Tier-C Backends
Tier-C utilizes platform-specific tools to create a restricted environment:- Linux (Bubblewrap): Uses
bwrapto create new namespaces (PID, mount, network). It binds the workspace as a read-write mount while keeping the rest of the filesystem read-only or hidden crates/palyra-sandbox/src/lib.rs#130-182. - macOS (sandbox-exec): Uses the native Seatbelt profile system to restrict file and network access crates/palyra-sandbox/src/lib.rs#10-20.
Egress Enforcement Modes
Network access for sandboxed processes is controlled viaEgressEnforcementMode crates/palyra-daemon/src/sandbox_runner.rs#47-51:
- None: No network restrictions applied.
- Preflight: Arguments are scanned for URLs/hostnames and checked against an allowlist before spawning crates/palyra-daemon/src/sandbox_runner.rs#189-191.
- Strict: The process is executed in a network namespace with no egress, or restricted via the kernel sandbox backend crates/palyra-daemon/src/sandbox_runner.rs#192-194.
Attestation & Integrity
Every tool execution generates aToolAttestation crates/palyra-daemon/src/tool_protocol.rs#73-80. This record includes:
- Execution SHA256: A hash of the tool input and execution context.
- Executor: The specific backend used (e.g.,
sandbox_tier_c_linux_bubblewrap) crates/palyra-sandbox/src/lib.rs#27-34. - Sandbox Enforcement: A string describing the active security constraints during the run.
Human-in-the-Loop (HITL) Approvals
When a tool is deemed “sensitive” by the policy engine (e.g.,process_exec or secrets_read capabilities), execution is suspended until a user provides approval crates/palyra-daemon/src/tool_protocol.rs#148-150.
Approval Workflow
- Proposal: The LLM proposes a tool call.
- Security Evaluation:
evaluate_tool_proposal_securitydetermines if HITL is required crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-134. - Pending State: An
ApprovalPromptRecordis created and sent to the client via theRunStreamcrates/palyra-daemon/src/application/approvals/mod.rs#111-128. - Decision: The user selects a scope (
Once,Session, orTimeboxed) crates/palyra-daemon/src/application/approvals/mod.rs#158-182. - Resolution: The
palyradruntime applies the decision, either proceeding with execution or returning a denial to the LLM crates/palyra-daemon/src/application/approvals/mod.rs#32-64.