palyrad), the browser automation service (palyra-browserd), and the local node host (palyra node). Beyond process management, it layers a native “Companion Shell” that includes ambient runtime features like a tray-based quick panel, voice overlay, and global hotkeys.
Architecture Overview
The application follows a standard Tauri split: a Rust-based backend (“src-tauri”) for system-level supervision and a React/Vite frontend (“ui”) for the operator interface.Component Relationship
The following diagram illustrates how the desktop application bridges the user’s desktop environment with the Palyra core services. Title: Desktop Application Bridge Architecture Sources: apps/desktop/src-tauri/src/lib.rs#1-45, apps/desktop/src-tauri/src/supervisor.rs#1-15, apps/desktop/README.md#45-57The Supervisor (ControlCenter)
The ControlCenter is the central struct in the Rust backend responsible for the lifecycle of local Palyra services. It maintains the ManagedService state for each sidecar and performs periodic reconciliation.
Managed Services
The supervisor manages three primary service kinds:- Gateway (
palyrad): The central daemon. - Browserd (
palyra-browserd): The gRPC-based browser automation engine. - NodeHost (
palyra node host): The first-party execution node for local capabilities.
Implementation Details
- Process Management: Services are spawned using
tokio::process::CommandwithStdio::piped()to capture logs apps/desktop/src-tauri/src/supervisor.rs#127-139. - Log Buffering: The supervisor maintains a
VecDeque<LogLine>for each service, capped atMAX_LOG_LINES_PER_SERVICE(400 lines) to provide diagnostic visibility in the UI apps/desktop/src-tauri/src/lib.rs#8-9, apps/desktop/src-tauri/src/supervisor.rs#137-138. - Health Monitoring: The supervisor performs a “tick” every 500ms to check process liveness and reconcile desired state vs. actual state apps/desktop/src-tauri/src/lib.rs#7-7.
- Config Reloading: A
DesktopConfigReloadWatchStatemonitors thepalyra.tomlfile. If the configuration changes, the supervisor triggers a restart of the affected sidecars apps/desktop/src-tauri/src/supervisor.rs#156-162.
Desktop State and Profile Registry
The application maintains its own persisted state separate from the daemon’s configuration. This is stored in a JSON state file (typicallydesktop-state.json).
Key State Entities
DesktopStateFile: The root persistence object containing onboarding status, rollout flags, and companion preferences apps/desktop/src-tauri/src/desktop_state.rs#214-230.DesktopProfileCatalog: Manages the mapping between desktop profiles and their underlying runtime roots. It supports an “implicit” profile nameddesktop-localapps/desktop/src-tauri/src/desktop_state.rs#35-35, apps/desktop/src-tauri/src/profile_registry.rs#15-25.DesktopRuntimeSecrets: Handles sensitive tokens (e.g.,desktop_admin_token) usingpalyra-vaultfor envelope encryption apps/desktop/src-tauri/src/desktop_state.rs#350-360.
Onboarding Flow
The desktop application guides the user through a multi-step onboarding process:- Welcome: Introduction to the companion.
- State Root Selection: Choosing where Palyra data will be stored.
- Profile Initialization: Setting up the default local profile.
- Connector Setup: Guided flow for Discord or other communication channels apps/desktop/src-tauri/src/onboarding.rs#15-35.
Companion Shell and UI (React)
The frontend is a React application built with Vite and HeroUI, communicating with the Rust backend via Tauri’sinvoke API.
Domain Architecture
The UI is structured around theuseDesktopCompanion hook, which provides a DesktopCompanionSnapshot containing:
control_center: Status of the supervised processes and local ports.session_catalog: Recent chat sessions retrieved from the local gateway.approvals: Pending tool execution requests requiring operator intervention.inventory: Available devices and capabilities apps/desktop/ui/src/lib/desktopApi.ts#223-264.
Ambient Runtime Features
The application provides “ambient” surfaces that are accessible outside the main window:- Quick Panel: A tray-based menu for rapid session switching and approval management apps/desktop/README.md#116-118.
- Voice Overlay: A structured interface for the voice lifecycle:
idle->recording->transcribing->review->sendingapps/desktop/src-tauri/src/desktop_state.rs#92-104. - Global Hotkeys: Configurable shortcuts (default:
Cmd/Ctrl+Shift+Space) to reveal the companion surfaces apps/desktop/src-tauri/src/desktop_state.rs#131-136.
Snapshot and Redaction
To ensure security, thesnapshot.rs module redacts sensitive information before sending it to the UI. It uses redact_url_strict and redact_auth_error_strict from palyra-common to sanitize log lines and error messages apps/desktop/src-tauri/src/snapshot.rs#18-23.
Title: Desktop UI Data Flow
Sources: apps/desktop/ui/src/App.tsx#117-160, apps/desktop/src-tauri/src/snapshot.rs#1-15, apps/desktop/src-tauri/src/commands.rs#146-162
Desktop Node Enrollment
The desktop application automates the enrollment of the local machine as a Palyra node.- Code Generation: It requests a pairing code from the local gateway via
/console/v1/pairing/requests/codeapps/desktop/README.md#57-63. - Installation: It executes
palyra node installusing the generated code. - Supervision: Once enrolled, the supervisor keeps
palyra node run --jsonalive and parses its output to surface device health in the UI apps/desktop/README.md#63-65, apps/desktop/src-tauri/src/supervisor.rs#51-55.