Skip to main content
Palyra implements a multi-layered security model for tool execution, combining fine-grained authorization via Cedar policies, human-in-the-loop approvals, and multi-tier process isolation. This architecture ensures that LLM-driven tool calls are constrained by resource quotas, network isolation, and explicit permission boundaries.

​
Multi-Tier Sandboxing Architecture

The system categorizes tool execution into three tiers of isolation, depending on the required capabilities and the host platform’s support.
TierNameTechnologyIsolation Level
Tier-AWASM RuntimewasmtimeFull instruction-level sandboxing; capability-based security for host imports.
Tier-BIn-Process Unixstd::process + Unix ControlsBasic process isolation with OS-level resource limits (CPU/Memory) on Unix systems.
Tier-COS-Level Sandboxbwrap (Linux) / sandbox-exec (macOS)Strong namespace isolation, filesystem remapping, and network unsharing.

​
Tier-C Backend Dispatch

The palyra-sandbox crate provides a unified interface for platform-specific Tier-C backends. It detects the host OS and selects the appropriate executor: LinuxBubblewrap, MacosSandboxExec, or WindowsJobObject crates/palyra-sandbox/src/lib.rs#8-13. Diagram: Sandbox Backend Selection and Command Planning The TierCBackend trait abstracts the complexity of constructing sandboxed command lines across different operating systems. Sources: crates/palyra-daemon/src/sandbox_runner.rs#147-210, crates/palyra-sandbox/src/lib.rs#81-91, crates/palyra-sandbox/src/lib.rs#107-184

​
Tool Approval Lifecycle

Before a tool is executed, it must pass through a security pipeline that evaluates the ToolProposal. This process checks if the tool is allowlisted, if it requires human approval, and if it has exceeded its execution budget.
  1. Proposal Evaluation: The evaluate_tool_proposal_security function determines if the tool is “sensitive” based on its capabilities (e.g., ProcessExec, Network) crates/palyra-daemon/src/tool_protocol.rs#47-52, crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-134.
  2. Approval Resolution: If approval is required, the system first checks the cache via resolve_cached_tool_approval_for_proposal crates/palyra-daemon/src/application/approvals/mod.rs#67-76.
  3. Human-in-the-Loop: If no valid cached approval exists, a PendingToolApproval is created and sent to the user via the RunStream crates/palyra-daemon/src/application/approvals/mod.rs#100-135.
  4. Decision Enforcement: The apply_tool_approval_outcome function merges the user’s decision into the final ToolDecision crates/palyra-daemon/src/application/approvals/mod.rs#32-64.
Diagram: Tool Proposal to Execution Flow This diagram maps the lifecycle of a tool call from the initial proposal to the final execution outcome. Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-101, crates/palyra-daemon/src/application/approvals/mod.rs#100-135, crates/palyra-daemon/src/sandbox_runner.rs#147-151

​
Cedar Policy Evaluation

Palyra uses the Cedar policy language for fine-grained authorization. Policies are evaluated within palyra-policy using a PolicyRequestContext that includes details like device_id, run_id, and requested capabilities crates/palyra-policy/src/lib.rs#17-26.

​
Default Policy Logic

The system enforces several baseline rules defined in DEFAULT_POLICY_SRC crates/palyra-policy/src/lib.rs#99-187: Sources: crates/palyra-policy/src/lib.rs#217-230, crates/palyra-daemon/src/tool_protocol.rs#3-6

​
Egress Enforcement Modes

Network access for tools (especially in Tier-C) is controlled by EgressEnforcementMode crates/palyra-daemon/src/sandbox_runner.rs#47-51:
  • None: No network restrictions applied.
  • Preflight: Requested hosts are checked against an allowlist before the process starts, but the sandbox does not enforce host-level blocking at runtime.
  • Strict: The sandbox enforces network isolation (e.g., bwrap --unshare-net) and only allows traffic to specific hosts if the backend supports it crates/palyra-daemon/src/sandbox_runner.rs#186-194.
If a tool requests an egress host not present in the allowed_egress_hosts policy, the execution is denied with SandboxProcessRunErrorKind::EgressDenied crates/palyra-daemon/src/sandbox_runner.rs#112. Sources: crates/palyra-daemon/src/sandbox_runner.rs#80-93, crates/palyra-sandbox/src/lib.rs#37-44

​
Execution Attestation

Every tool execution generates a ToolAttestation which is recorded in the run’s journal. This provides a cryptographic and metadata-rich audit trail of what happened inside the sandbox.
FieldDescription
attestation_idUnique identifier for the execution event.
execution_sha256SHA256 hash of the tool’s output crates/palyra-daemon/src/tool_protocol.rs#75.
executorThe name of the runner used (e.g., sandbox_tier_c_linux_bubblewrap) crates/palyra-daemon/src/tool_protocol.rs#78.
sandbox_enforcementDescription of the enforcement level applied (e.g., “strict”) crates/palyra-daemon/src/tool_protocol.rs#79.
The attestation is sent back to the client via the RunStream using send_tool_attestation_with_tape to ensure the UI can display the security posture of the result crates/palyra-daemon/src/application/run_stream/tool_flow.rs#40. Sources: crates/palyra-daemon/src/tool_protocol.rs#73-80, crates/palyra-daemon/src/sandbox_runner.rs#120-126