Codebase Documentation

Palyra is a high-performance, secure agentic framework designed for executing complex tasks across local and remote environments. It provides a robust daemon-based architecture that orchestrates LLM interactions, tool execution, and long-term memory while maintaining a strict security posture. The system is designed to bridge the gap between “Natural Language Space” (agent goals and user intent) and “Code Entity Space” (sandboxed processes, filesystem operations, and browser automation).

​

System Architecture

Palyra is structured as a hub-and-spoke model centered around the palyrad daemon. The daemon acts as the central gateway, managing sessions, enforcing security policies via the Cedar engine, and dispatching tasks to various executors.

​

Core Architecture Components

The following diagram illustrates the relationship between the primary code entities and their functional roles in the system: Diagram: Palyra System Topology Sources: crates/palyra-daemon/Cargo.toml#1-67, crates/palyra-daemon/src/bin/palyrad.rs#11-13

​

Key Subsystems

​

1. The Gateway Daemon (palyrad)

The central process responsible for session lifecycle, transport handling (HTTP/gRPC/QUIC), and the core agent orchestration loop. It coordinates with the palyra-policy crate to ensure every tool invocation is authorized.

• Crate: palyra-daemon crates/palyra-daemon/Cargo.toml#2-2
• Entry Point: src/bin/palyrad.rs crates/palyra-daemon/Cargo.toml#11-13

​

2. Tool Runtime & Sandboxing

Tools are executed in isolated environments to prevent unauthorized system access. This includes filesystem scoping, process limits, and browser automation via a dedicated gRPC service.

• Crates: palyra-sandbox, palyra-browserd, palyra-skills Cargo.toml#10-22

​

3. Security & Safety

Palyra employs a “deny-by-default” posture. The safety boundary scans for prompt injections and secret leaks, while the identity system manages mTLS and device pairing.

• Crates: palyra-policy, palyra-safety, palyra-identity, palyra-vault Cargo.toml#14-20

​

4. Client Interfaces

Users interact with Palyra through a CLI, a web-based console, or a desktop application (Tauri).

• CLI: palyra-cli (binary: palyra) crates/palyra-cli/Cargo.toml#2-13
• Web/Desktop: React-based frontends located in the apps/ directory. package.json#11-15

​

Code Entity Mapping

The following table maps conceptual system components to their specific implementations in the codebase: Sources: Cargo.toml#1-23, crates/palyra-daemon/Cargo.toml#25-41

​

Deployment Profiles

Palyra supports multiple deployment modes defined in palyra-common. These profiles determine the default security posture and connectivity options:

• local (or local_desktop): Optimized for single-user workstation use.
• single-vm (or remote_vps): Designed for deployment on a single remote server.
• worker-enabled: Supports a fleet of networked workers for horizontal scaling.

Sources: crates/palyra-common/src/deployment_profiles.rs#25-50

​

Child Pages

For detailed technical documentation on specific subsystems, refer to the following pages:

• Repository Structure and Crate Map: A deep dive into the monorepo layout, crate dependencies, and the purpose of each directory (apps, crates, schemas, etc.).
• Getting Started: Setup and Configuration: Instructions for developer bootstrapping, using the onboarding wizard, and configuring palyra.toml for different deployment profiles.

​

Child Pages

• Repository Structure and Crate Map
• Getting Started: Setup and Configuration