Execution Architecture Overview
When an agent requests a tool call, thepalyrad daemon orchestrates a multi-stage validation and execution pipeline:
- Authorization: The request is evaluated against Cedar policies to check if the principal (agent/user) has the required capabilities for the specific tool.
- Resource Allocation: Budget tracking ensures the run does not exceed the maximum allowed tool calls.
- Sandbox Selection: Based on the
ToolCallConfig, the execution is routed to the appropriate sandbox tier (B or C) or the WASM runtime. - Attestation: Upon completion, a
ToolAttestationis generated, capturing the executor used and the execution’s cryptographic hash.
System Flow: Tool Request to Sandbox
The following diagram illustrates how a natural language intent results in a sandboxed process execution via thepalyrad daemon.
Diagram: Tool Execution Lifecycle
Sources: crates/palyra-daemon/src/tool_protocol.rs#19-26, crates/palyra-daemon/src/tool_protocol.rs#322-330, crates/palyra-policy/src/lib.rs#217-220
Core Components
1. Tool Protocol and Authorization
TheToolCallConfig defines the boundaries for tool execution, including timeouts and allowed capabilities like ProcessExec or Network. Every tool call must pass through decide_tool_call, which uses the Cedar policy engine to evaluate the request context (principal, device, channel) against a set of rules.
- Capabilities: Tools are tagged with capabilities such as
SecretsReadorFilesystemWritecrates/palyra-daemon/src/tool_protocol.rs#47-52. - Budgeting: The system tracks
max_calls_per_runto prevent infinite loops or resource exhaustion crates/palyra-daemon/src/tool_protocol.rs#22-22.
2. Sandbox Process Runner (Tiers B & C)
For executing shell commands and external binaries, Palyra uses a tiered sandboxing approach managed byrun_constrained_process crates/palyra-daemon/src/sandbox_runner.rs#147-151.
| Tier | Enforcement Mechanism | Platform |
|---|---|---|
| Tier B | Unix rlimit (CPU/Memory) and workspace scope validation. | Unix-like crates/palyra-daemon/src/sandbox_runner.rs#65-66 |
| Tier C | OS-level namespaces/containers (e.g., bwrap, sandbox-exec). | Linux, macOS, Windows crates/palyra-sandbox/src/lib.rs#8-13 |
None, Preflight, Strict) to control network access during execution crates/palyra-daemon/src/sandbox_runner.rs#47-51.
For details, see Sandbox Process Runner (Tier B and Tier C).
3. WASM Plugin Runtime
Palyra supports extensible “Skills” implemented as WebAssembly (WASM) plugins. This provides a high-performance, language-agnostic way to add capabilities without granting full shell access.- Runtime: Built on
wasmtime, providing fine-grained “fuel” budgeting and memory limits crates/palyra-daemon/src/tool_protocol.rs#115-127. - Isolation: Plugins are restricted to the WIT (Wasm Interface Type) surface, preventing unauthorized system calls.
Security Guardrails
The execution environment includes several hardcoded safety measures to prevent common exploitation patterns:- Interpreter Denylist: Common shells and interpreters (e.g.,
bash,python,node) are blocked unless explicitly allowed by policy to prevent arbitrary code execution via tool arguments crates/palyra-daemon/src/sandbox_runner.rs#30-44. - Output Quotas: Processes are terminated if they exceed
max_output_bytesto prevent log-filling attacks crates/palyra-daemon/src/sandbox_runner.rs#92-92. - Workspace Scoping: Filesystem access is strictly limited to the
workspace_rootcrates/palyra-daemon/src/sandbox_runner.rs#84-84.
Child Pages
- Tool Protocol and Cedar Policy Authorization: Detailed look at
ToolCallConfig,ToolAttestation, and Cedar evaluation. - Sandbox Process Runner (Tier B and Tier C): Technical implementation of
bwrap,rlimit, and egress enforcement. - WASM Plugin Runtime and Skills: Plugin SDK, lifecycle, and the
palyra-plugins-runtime.