Skip to main content
Palyra implements a defense-in-depth security architecture designed to protect sensitive credentials while enabling autonomous agent operations. The system balances “Trust on First Use” (TOFU) convenience for device pairing with strict mTLS-backed identity, hardware-backed secret storage, and fine-grained Cedar policy enforcement.

​
Security Architecture Overview

The security model is built on four primary pillars that coordinate to ensure that only authorized devices can issue commands and that agents only access the minimum necessary secrets to fulfill a request.
  1. Identity & Pairing: Establishes trust between the daemon and clients (CLI, Desktop, Mobile) using Ed25519 keys and x509 certificates.
  2. Vault: Provides encrypted storage for API keys and credentials, leveraging OS-native backends like macOS Keychain or Windows DPAPI.
  3. Policy Enforcement: Uses the Cedar policy language to evaluate every tool call and management action against a set of rules.
  4. Sandbox Isolation: Executes high-risk tools (like arbitrary shell commands) in multi-tiered sandboxes to prevent lateral movement or filesystem escape.
The following diagram illustrates the relationship between these security components during a typical authenticated request: Security Component Interaction Flow Sources: crates/palyra-daemon/src/tool_protocol.rs#20-88, crates/palyra-policy/src/lib.rs#200-218, crates/palyra-vault/src/lib.rs#12-20

​
5.1 Identity, mTLS, and Device Pairing

The palyra-identity subsystem manages the Root Certificate Authority (CA) and the lifecycle of device identities. All communication between Palyra components is secured via Mutual TLS (mTLS). Devices pair with the daemon using a TOFU (Trust on First Use) flow where a unique device_id and proof are verified before a certificate is issued.
  • Key Entities: IdentityManager, DeviceIdentity, Ed25519 keys.
  • Pairing: Supports QR codes or manual proof entry via CLI.
  • For details, see Identity, mTLS, and Device Pairing.
Sources: crates/palyra-cli/tests/pairing_flow.rs#17-70, crates/palyra-common/src/lib.rs#18-22

​
5.2 Vault: Secret Storage and Credential Management

The palyra-vault crate provides a secure abstraction for storing sensitive data. Instead of passing raw API keys in configuration files, Palyra uses “Vault Refs” (e.g., vault://openai/api_key). The vault automatically selects the most secure backend available on the host platform.
PlatformBackend ImplementationCode Reference
macOSKeychain ServicesBackendKind::MacosKeychain
LinuxSecret Service (libsecret)BackendKind::LinuxSecretService
WindowsDPAPIBackendKind::WindowsDpapi
FallbackEncrypted SQLite/FileBackendKind::EncryptedFile
Sources: crates/palyra-vault/src/backend.rs#39-80, crates/palyra-vault/src/backend.rs#135-158, crates/palyra-vault/src/lib.rs#12-16

​
5.3 Authentication and Auth Profiles

palyra-auth manages the high-level authentication state for external services (like OpenAI, Discord, or Slack). It handles OAuth2 flows, token refresh logic, and organizes these credentials into “Auth Profiles.” This allows a single Palyra instance to switch between different personas or organizational contexts.
  • Core Concepts: AuthProfileRegistry, SessionManager, OAuth token persistence.
  • Integration: Connects the palyrad gateway to the palyra-vault for secure token storage.
  • For details, see Authentication and Auth Profiles.
Sources: crates/palyra-policy/src/lib.rs#159-166

​
5.4 Tool Approvals and Access Control

Palyra uses a “Human-in-the-loop” model for high-risk operations. The palyra-policy engine, powered by Amazon Cedar, evaluates every action. If an action is marked as sensitive (e.g., process_exec or filesystem_write), the system pauses execution and generates an ApprovalRequest. Policy Evaluation Logic
  • Decision Types: Allow, Deny, and DenyByDefault (which triggers the approval flow).
  • Capability Scopes: ProcessExec, Network, SecretsRead, and FilesystemWrite.
  • For details, see Tool Approvals and Access Control.
Sources: crates/palyra-policy/src/lib.rs#11-38, crates/palyra-policy/src/lib.rs#99-187, crates/palyra-daemon/src/tool_protocol.rs#46-64

​
Child Pages