Skip to main content
The Palyra Desktop Companion is a Tauri-based application that serves as the primary local supervisor and operator shell for the Palyra ecosystem. It manages the lifecycle of essential sidecar processes and provides a native user interface for quick interactions, approvals, and system monitoring.

​
Purpose and Scope

The Desktop Companion acts as a bridge between the low-level Rust daemons (palyrad, palyra-browserd) and the high-level operator experience. Its primary responsibilities include:
  1. Process Supervision: Ensuring the availability of the core gateway and browser services.
  2. Operator Shell: Providing a session-aware chat interface and approval inbox without requiring a full browser tab.
  3. Local Node Management: Supervising the enrollment and runtime of the local palyra node host.
  4. Secure Handoff: Facilitating the transition from the local desktop context to the full Web Dashboard using a secure token-based flow.

​
System Context Diagram

The following diagram illustrates how the Desktop Companion (Tauri) orchestrates the local environment. “Desktop Companion Architecture” Sources: apps/desktop/src-tauri/src/supervisor.rs#212-234, apps/desktop/src-tauri/src/lib.rs#44-47, apps/desktop/ui/src/App.tsx#60-64

​
Process Supervisor and Lifecycle Management

The core of the desktop application is the ControlCenter, which manages ManagedService instances for the gateway, browser daemon, and node host. It handles binary path resolution, port binding, and automated restarts with exponential backoff.
  • Service Management: Defines ServiceKind (Gateway, Browserd, NodeHost) and tracks their liveness via PIDs and health checks.
  • Log Aggregation: Captures stdout and stderr from sidecars, streaming them into a bounded LogLine buffer for diagnostic visibility.
  • State Persistence: Manages DesktopStateFile, which tracks onboarding progress, rollout flags, and user preferences across app restarts.
For details, see Process Supervisor and Lifecycle Management.

​
Supervisor Code Entity Mapping

“Supervisor Code Entities” Sources: apps/desktop/src-tauri/src/supervisor.rs#37-41, apps/desktop/src-tauri/src/supervisor.rs#108-118, apps/desktop/src-tauri/src/supervisor.rs#212-234, apps/desktop/src-tauri/src/desktop_state.rs#215-227

​
Desktop Companion Shell and Onboarding

The UI layer is a React-based SPA hosted within Tauri. It provides a “Companion Shell” that allows operators to interact with the system without leaving their native desktop environment.
  • Companion Shell: Features a session-aware chat interface, an approvals inbox for security decisions, and a notification system for system events.
  • Onboarding Flow: A multi-step wizard (DesktopOnboardingStep) that guides the user through environment setup, sidecar initialization, and initial provider authentication (e.g., OpenAI, Discord).
  • Offline Support: Implements DesktopCompanionOfflineDraft to allow users to compose messages even when the local gateway is temporarily unreachable.
  • Dashboard Handoff: Provides a secure mechanism to open the full Web Dashboard in a standard browser, passing the necessary authentication context (admin_token and csrf_token).
For details, see Desktop Companion Shell and Onboarding.

​
UI and Command Mapping

FeatureTauri CommandUI Component / Hook
Snapshot Pollingget_desktop_companion_snapshotuseDesktopCompanion
Lifecycle Controlstart_palyra, stop_palyraLifecycleActionBar
Chat Interactionsend_companion_chat_messageApp.tsx (sendBusy state)
Approvalsdecide_companion_approvalApp.tsx (approvalBusy state)
Handoffopen_desktop_companion_handoffopenDashboard helper
Sources: apps/desktop/src-tauri/src/commands.rs#122-135, apps/desktop/src-tauri/src/commands.rs#197-205, apps/desktop/ui/src/App.tsx#21-48, apps/desktop/ui/src/lib/desktopApi.ts#1-48

​
Configuration and Secrets

The desktop app manages its own set of runtime secrets and configuration overrides to ensure the sidecars operate in a secure, isolated environment.
  • State Root: Users can override the default runtime directory during onboarding, which is then persisted in the state file.
  • Runtime Secrets: The app generates and stores unique tokens like DESKTOP_SECRET_KEY_ADMIN_TOKEN and DESKTOP_SECRET_KEY_BROWSER_AUTH_TOKEN to secure the communication between the UI, the supervisor, and the sidecars.
  • Rollout Flags: Feature flags like voice_capture_enabled and offline_drafts_enabled are managed via DesktopCompanionRolloutState to safely introduce experimental features.
Sources: apps/desktop/src-tauri/src/lib.rs#9-12, apps/desktop/src-tauri/src/desktop_state.rs#72-79, apps/desktop/src-tauri/src/desktop_state.rs#241-255

​
Child Pages