System Architecture
The execution pipeline follows a strict Decide → Approve → Execute flow. When an orchestrator receives a tool call request, it passes through thetool_protocol.rs logic which coordinates with the Policy Engine and the Sandbox Runner.
Tool Execution Flow
The following diagram illustrates how a tool call moves from theGatewayService through the safety checks to final execution.
Sources: crates/palyra-daemon/src/tool_protocol.rs#210-215, crates/palyra-daemon/src/tool_protocol.rs#335-345, crates/palyra-policy/src/lib.rs#211-215
3.1 Tool Protocol & Approval Flow
Thetool_protocol.rs module defines the contract for tool execution. Every tool call is assigned a ToolAttestation palyra-daemon/src/tool_protocol.rs#73-80, which includes a SHA-256 hash of the execution results and details about the sandbox enforcement used.
If a tool is marked as “sensitive” or involves capabilities like ProcessExec or Network palyra-daemon/src/tool_protocol.rs#46-52, the system triggers an approval flow. This requires a human operator to grant permission via the Web Console or CLI before the execute_tool_call function palyra-daemon/src/tool_protocol.rs#446-450 is invoked.
For details, see Tool Protocol & Approval Flow.
Sources: crates/palyra-daemon/src/tool_protocol.rs#1-150, crates/palyra-daemon/src/tool_protocol.rs#446-550
3.2 Policy Engine (Cedar)
Palyra uses the Cedar Policy Language (via thepalyra-policy crate) to define fine-grained access control. The engine evaluates a PolicyRequest palyra-policy/src/lib.rs#11-15 against a set of store policies.
| Policy Component | Description |
|---|---|
| Principal | The identity requesting the tool (e.g., a specific user or device) palyra-policy/src/lib.rs#36-38. |
| Action | The operation being performed (e.g., tool.execute, memory.search) palyra-policy/src/lib.rs#108-115. |
| Resource | The target of the action (e.g., a specific skill or tool name). |
| Context | Metadata such as channel_id, device_id, and capabilities palyra-policy/src/lib.rs#18-26. |
3.3 Sandbox Tiers & Process Runner
Execution safety is enforced through tiered sandboxing provided bysandbox_runner.rs and the palyra-sandbox crate.
- Tier-B: Uses OS-level resource limits (
rlimitson Unix) to constrain CPU and memory palyra-daemon/src/sandbox_runner.rs#65-68. - Tier-C: Provides strong isolation using platform-specific technologies:
bubblewrap(bwrap) on Linux andsandbox-execon macOS palyra-sandbox/src/lib.rs#8-14.
bash or pwsh) and strict Egress Enforcement Modes palyra-daemon/src/sandbox_runner.rs#47-51 to prevent data exfiltration.
For details, see Sandbox Tiers & Process Runner.
Sources: crates/palyra-daemon/src/sandbox_runner.rs#25-60, crates/palyra-sandbox/src/lib.rs#1-100
3.4 WASM Plugin System & Skills
The most secure way to extend Palyra is through Skills. Skills are packaged as WebAssembly (WASM) modules and executed by thewasm_plugin_runner.rs using wasmtime.
The WASM environment is “deny-by-default.” Plugins can only access host functions (like networking or filesystem) if explicitly granted in the skill.toml manifest and allowed by the WasmPluginRunnerPolicy palyra-daemon/src/tool_protocol.rs#115-127. This provides Tier-A isolation, where the code has no direct access to the host OS.
For details, see WASM Plugin System & Skills.
Sources: crates/palyra-daemon/src/tool_protocol.rs#173-185, crates/palyra-daemon/src/wasm_plugin_runner.rs#1-50