Library Ecosystem Overview
The Palyra workspace is built upon several core libraries that abstract complex logic away from the main application binaries.Component Relationship
The following diagram illustrates how the shared libraries serve as the foundation for the higher-level applications. Shared Library Dependency Map Sources: crates/palyra-common/Cargo.toml#1-23, crates/palyra-vault/src/lib.rs#1-20palyra-common: Core Utilities
Thepalyra-common crate is the lowest-level dependency in the workspace. It defines the fundamental data structures and validation logic used across all Rust components.
- Daemon Configuration: Defines the
RootFileConfigandDaemonConfigschemas used forpalyra.tomlvalidation. It includesredact_secret_config_valuesto ensure sensitive keys aren’t leaked in logs. - Workspace Patching: Implements
apply_workspace_patchcrates/palyra-common/src/workspace_patch.rs#207-211, a fail-closed mechanism for applying atomic file changes within sandboxed workspace roots. - Validation: Provides
validate_canonical_idcrates/palyra-common/src/ids.rs#24-24 for ensuring ULID-compatible identifiers andparse_daemon_bind_socketcrates/palyra-common/src/net.rs#25-25 for network address parsing. - Redaction: Contains utilities in
palyra_common::redactionfor masking sensitive strings in diagnostic outputs.
palyra-auth and palyra-control-plane
These crates manage the identity and external communication requirements of the Palyra ecosystem.- palyra-auth: Handles authentication primitives, including API key management, OAuth refresh state persistence, and the
openai_authintegration used for proxying requests to LLM providers. - palyra-control-plane: Provides the client and models for communicating with the Palyra Control Plane. This includes managing high-level “Objectives” and reporting daemon health/telemetry if configured.
palyra-vault: Secure Secret Storage
Thepalyra-vault crate provides a unified API for sensitive data persistence, abstracting over platform-specific secure enclaves.
Vault Backend Architecture
- Platform Integration: Automatically selects the best available backend, such as
MacosKeychaincrates/palyra-vault/src/backend.rs#44-44 orWindowsDpapicrates/palyra-vault/src/backend.rs#48-48. - Security: Enforces owner-only directory permissions crates/palyra-vault/src/filesystem.rs#15-15 and uses
SensitiveBytescrates/palyra-vault/src/crypto.rs#14-14 to prevent accidental logging of secrets.
Node Runtime and Remote Nodes
Palyra supports distributed execution through remote nodes. This functionality is powered by gRPC and mTLS.- NodeService: The gRPC interface that allows the daemon to execute
DeviceCapabilityon remote hardware. - Pairing Flow: Implements secure device association using
PairingMethod(e.g., QR codes or proof-of-possession) crates/palyra-cli/tests/pairing_flow.rs#32-70. - palyra-transport-quic: A custom transport layer that uses QUIC for low-latency, mTLS-encrypted communication between nodes, featuring pinned server fingerprints for TOFU (Trust On First Use) security.
Configuration and Validation Flow
The following table summarizes how configuration is handled across the shared libraries.| Feature | Code Entity | Purpose |
|---|---|---|
| Path Parsing | parse_config_path | Resolves ~/.config/palyra vs CWD paths. |
| Validation | config_validate | CLI command to verify palyra.toml integrity. |
| Redaction | redact_secret_config_values | Masks api_key in config dumps. |
| ID Safety | validate_canonical_id | Prevents path traversal via malformed IDs. |