Skip to main content
The Tool Runtime and Execution Subsystems manage the lifecycle of tool calls proposed by agents. This includes catalog validation, security policy enforcement via the Cedar engine, operator approval gating, and final execution across a variety of specialized backends. The system is designed with a “deny-by-default” posture, ensuring that every tool invocation is attested and recorded for auditability.

​
Tool Registry and Dispatch Pipeline

The tool_registry serves as the central authority for available tools, mapping them to their required capabilities and sensitive-tool classifications crates/palyra-common/src/tool_catalog.rs#1-6. When an agent proposes a tool call, it enters a multi-stage dispatch pipeline:
  1. Validation & Normalization: The proposal is validated against the ModelVisibleToolCatalogSnapshot and arguments are normalized crates/palyra-daemon/src/application/run_stream/tool_flow.rs#46-54.
  2. Security Evaluation: The system evaluates the call against the Cedar policy engine, checking for required capabilities like ProcessExec or Network crates/palyra-daemon/src/tool_protocol.rs#4-11.
  3. Approval Gating: If the tool is marked as sensitive or the policy requires it, an interactive approval request is sent to the operator crates/palyra-daemon/src/application/run_stream/tool_flow.rs#3-10.
  4. Runtime Dispatch: Once approved, the call is routed to the appropriate executor (e.g., Sandbox, Browser, or Wasm) crates/palyra-daemon/src/application/run_stream/tool_flow.rs#64-71.

​
Tool Execution Flow Diagram

This diagram maps the logical flow of a tool proposal to the code entities responsible for each stage. Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#1-11, crates/palyra-daemon/src/tool_protocol.rs#1-15, crates/palyra-daemon/src/application/run_stream/tool_flow.rs#40-54

​
Security Posture and Attestation

Palyra implements a tamper-evident audit trail for all tool executions. Every outcome—whether a success, a policy denial, or a timeout—is bundled with a ToolAttestation crates/palyra-daemon/src/tool_protocol.rs#89-97. This attestation includes a SHA-256 hash that binds the proposal ID, input, output, and the specific executor metadata together crates/palyra-daemon/src/tool_protocol.rs#83-88. The system also supports “Tool Posture” overrides, allowing operators to set tools to AlwaysAllow, AskEachTime, or Disabled at various scopes (Global, Workspace, Agent, or Session) crates/palyra-daemon/src/tool_posture.rs#91-98.

​
Security and Posture Entities

Sources: crates/palyra-daemon/src/tool_protocol.rs#73-107, crates/palyra-daemon/src/tool_posture.rs#1-11

​
Tool Executors

Palyra utilizes several specialized executors to provide a secure and functional environment for agents.

​
Sandbox Process Runner

Executes arbitrary shell commands and binaries. It supports multiple isolation tiers, including direct execution with rlimits (Tier B) and containerized/sandboxed execution via Docker or Bubblewrap (Tier C). For details, see Sandbox Process Runner.

​
Filesystem Tools: Workspace and OS File Access

Provides structured access to the filesystem. The palyra.fs tool family includes scoped workspace operations like directory listing, file reading, and atomic patching using the Palyra Patch Document format. For details, see Filesystem Tools: Workspace and OS File Access.

​
Browser Automation (palyra-browserd)

Manages a separate palyra-browserd service for Chromium-based web automation. It handles session management, SSRF protection, and provides tools for navigation, screenshots, and DOM interaction. For details, see Browser Automation (palyra-browserd).

​
Skills and Wasm Plugin System

A plugin architecture using WebAssembly (wasmtime). It allows for extensible “Skills” that run in a highly constrained environment with strictly defined fuel and memory limits. For details, see Skills and Wasm Plugin System.

​
Additional Tool Executors

Covers utility tools such as palyra.http.fetch (with egress proxying), memory management tools, and system routine controls. For details, see Additional Tool Executors.

​
Tool Protocol Constants

The system enforces strict quotas and budgets on tool inputs and execution latency to prevent resource exhaustion.
ConstantValueDescription
TOOL_EXECUTION_LATENCY_BUDGET_MS200msBudget for tool dispatch overhead crates/palyra-daemon/src/gateway.rs#132-132
MAX_PROCESS_RUNNER_TOOL_INPUT_BYTES128 KBMaximum size for process execution arguments crates/palyra-daemon/src/tool_protocol.rs#177-177
MAX_HTTP_FETCH_TOOL_INPUT_BYTES64 KBMaximum size for HTTP request parameters crates/palyra-daemon/src/tool_protocol.rs#176-176
TOOL_MAX_SLEEP_MS30,000msMaximum duration for the palyra.sleep tool crates/palyra-daemon/src/tool_protocol.rs#160-160
Sources: crates/palyra-daemon/src/gateway.rs#128-145, crates/palyra-daemon/src/tool_protocol.rs#158-185

​
Child Pages