Skip to main content
This page describes the organization of the Palyra monorepo, detailing the Cargo workspace, the internal crate ecosystem, application directories, and supporting infrastructure. The repository is designed to support a multi-process AI agent architecture with strict security boundaries and cross-platform compatibility.

​
Cargo Workspace Overview

Palyra is managed as a single Cargo workspace containing 18 internal Rust crates. This structure allows for shared dependency management, atomic cross-crate refactoring, and a unified build pipeline. The workspace configuration is defined in the root Cargo.toml, which specifies the member crates and shared workspace-level dependencies Cargo.toml#1-21. It uses the Rust 2021 edition and targets Rust version 1.91 Cargo.toml#25-28.

​
Internal Crates (crates/)

The core logic is partitioned into specialized crates to enforce modularity and reduce compile times for individual components.
Crate NamePurposeKey Dependencies
palyra-daemonThe central orchestrator (palyrad). Manages sessions, LLM flow, and persistence.tonic, axum, rusqlite, quinn
palyra-cliThe primary operator interface (palyra). Includes the TUI and ACP bridge.ratatui, clap, agent-client-protocol
palyra-browserdHeadless browser automation daemon using Chromium.headless_chrome
palyra-sandboxExecution isolation for tools (WASM, rlimit, bwrap).wasmtime, libc
palyra-policyCedar-based policy evaluation engine.cedar-policy (implied by context)
palyra-vaultPlatform-specific secret management (Keychain, Secret Service, DPAPI).ring, aes
palyra-identitymTLS and device identity management.rcgen, ed25519-dalek
palyra-plugins-runtimeWASM execution environment for agent skills.wasmtime
palyra-commonShared types, utilities, and error definitions.serde, ulid
palyra-authAuthentication providers and OAuth bootstrap logic.reqwest
palyra-skillsSkill manifest parsing and lifecycle management.toml, zip
palyra-connector-coreTrait definitions for external messaging adapters.async-trait
palyra-connector-discordDiscord-specific bot implementation.tokio-tungstenite
Sources: Cargo.toml#1-21, crates/palyra-daemon/Cargo.toml#1-55, crates/palyra-cli/Cargo.toml#1-45

​
Application Directory (apps/)

The apps/ directory contains the various user-facing interfaces and platform-specific stubs.
  • Web Console: Located in apps/web, this is a React-based dashboard for monitoring and interacting with the daemon.
  • Desktop App: Located in apps/desktop, a Tauri-based application that acts as a process supervisor for palyrad and palyra-browserd.
  • Browser Extension: Located in apps/browser-extension, providing integration between the user’s browser and the automation daemon.
  • Mobile Stubs: apps/android and apps/ios (implied by linting scripts) contain platform-specific logic for mobile integration justfile#27.

​
Protocol Schemas (schemas/)

The communication between all components (CLI, Daemon, Browser, Web) is governed by Protobuf definitions located in schemas/proto/palyra/v1/. The build process for crates like palyra-daemon and palyra-cli uses tonic-build to generate Rust stubs from these schemas during compilation crates/palyra-daemon/build.rs#3-35, crates/palyra-cli/build.rs#3-35. Sources: crates/palyra-daemon/build.rs#7-14, crates/palyra-cli/build.rs#7-14

​
Dependency Graph and Data Flow

The following diagram illustrates how the primary binaries interact and which internal crates they depend on to fulfill their roles.

​
System Architecture and Crate Association

Sources: crates/palyra-daemon/Cargo.toml#19-32, crates/palyra-cli/Cargo.toml#22-29, crates/palyra-daemon/build.rs#8-14

​
Infrastructure and Tooling

The repository includes several top-level directories for maintenance and quality assurance:
  • scripts/: Contains shell and PowerShell scripts for protocol generation, release packaging, and security hygiene justfile#97-106, justfile#133-141.
  • fuzz/: Contains cargo-fuzz targets for stress-testing parsers, including a2ui_json_parser, webhook_payload_parser, and auth_profile_registry_parser justfile#154-167.
  • infra/: Configuration for CI/CD pipelines and security scanning.

​
Developer Workflow Commands

Project tasks are orchestrated via a justfile (and a mirrored Makefile). Key targets include:
  • just doctor: Runs environment checks to ensure all prerequisites are met justfile#7-11.
  • just dev: Bootstraps the local development environment, including building the workspace and checking UI readiness justfile#16-21.
  • just protocol: Validates .proto files and regenerates Rust stubs justfile#103-107.
  • just security: Aggregates cargo-audit, cargo-deny, and custom pattern scans justfile#130-136.

​
Crate Dependency Mapping (Natural Language to Code)

This table bridges the conceptual subsystems with their physical implementation in the codebase.
SubsystemCode Implementation (Crate/File)Role
Identity Managementcrates/palyra-identityManages Ed25519 keys and mTLS certs Cargo.toml#18
Tool Sandboxcrates/palyra-sandboxImplements resource-constrained execution Cargo.toml#11
Secret Storagecrates/palyra-vaultInterfaces with OS-level secret stores Cargo.toml#19
Policy Enginecrates/palyra-policyEvaluates Cedar policies for tool access Cargo.toml#14
Agent UIcrates/palyra-a2uiHandles JSON-patch based UI updates Cargo.toml#15
WASM Runtimecrates/palyra-plugins/runtimeHost for skill execution via wasmtime Cargo.toml#16
Sources: Cargo.toml#1-21, justfile#1-171, Makefile#1-164