palyrad, palyra-browserd, palyra node) and the operator’s daily workflow by providing a native shell with local persistence, offline capabilities, and a guided setup experience.
Desktop State and Persistence
The desktop application manages its own persistent state independently of the daemon’s database. This state is stored in astate.json file located within the desktop state root directory.
DesktopStateFile Schema
TheDesktopStateFile is the primary container for persistent settings, rollout flags, and onboarding progress. It includes a schema version for migration handling.
- Schema Versioning: Defined by
DESKTOP_STATE_SCHEMA_VERSIONapps/desktop/src-tauri/src/lib.rs#9-9. - Rollout Flags: Managed via
DesktopCompanionRolloutState, which controls feature visibility for the companion shell, notifications, offline drafts, and voice capture apps/desktop/src-tauri/src/desktop_state.rs#71-79. - Preferences: Stores the
active_section,active_session_id, andactive_device_idto maintain UI continuity across restarts apps/desktop/src-tauri/src/desktop_state.rs#94-107.
DesktopSecretStore
The desktop maintains a small, specialized secret store for runtime tokens required to communicate with sidecars.- Admin Token:
desktop_admin_tokenused for/admin/v1and/console/v1authentication apps/desktop/src-tauri/src/lib.rs#11-11. - Browser Auth Token:
desktop_browser_auth_tokenused for browser sidecar authentication apps/desktop/src-tauri/src/lib.rs#12-12. - Implementation: Secrets are loaded via
load_runtime_secretsand can be migrated from legacy state files if necessary apps/desktop/src-tauri/src/desktop_state.rs#36-38.
Offline Drafts and Notifications
To handle intermittent connectivity, the desktop implements a bounded local buffer for drafts and notifications.- Offline Drafts: Captured when the gateway is unreachable. Limited to
DESKTOP_COMPANION_OFFLINE_DRAFT_LIMIT(20) apps/desktop/src-tauri/src/desktop_state.rs#21-21. - Notifications: Bounded to
DESKTOP_COMPANION_NOTIFICATION_LIMIT(40) apps/desktop/src-tauri/src/desktop_state.rs#20-20.
[apps/desktop/src-tauri/src/desktop_state.rs#1-205](http://apps/desktop/src-tauri/src/desktop_state.rs#1-205), [apps/desktop/src-tauri/src/lib.rs#1-41](http://apps/desktop/src-tauri/src/lib.rs#1-41)
Onboarding Wizard and Lifecycle
The onboarding system guides the user through environment configuration, sidecar initialization, and external provider authentication (OpenAI, Discord).DesktopOnboardingStep
The flow is modeled as a linear sequence of steps defined inDesktopOnboardingStep apps/desktop/src-tauri/src/desktop_state.rs#209-216:
- Welcome: Initial introduction.
- Environment: Selection of the runtime state root.
- Sidecars: Initializing and starting
palyradandpalyra-browserd. - Operator: Establishing the initial admin session.
- Providers: Configuring LLM backends and channel connectors.
- Node: Optional enrollment of the local desktop node host.
Data Flow: Onboarding Status
TheControlCenter captures raw inputs which are then transformed into an OnboardingStatusSnapshot for the UI.
Onboarding Status Resolution
Sources: [apps/desktop/src-tauri/src/onboarding.rs#81-115](http://apps/desktop/src-tauri/src/onboarding.rs#81-115), [apps/desktop/src-tauri/src/commands.rs#97-106](http://apps/desktop/src-tauri/src/commands.rs#97-106), [apps/desktop/src-tauri/src/onboarding.rs#141-165](http://apps/desktop/src-tauri/src/onboarding.rs#141-165)
Companion UI Architecture
The Companion UI is a React application hosted within Tauri that interacts with theControlCenter via Tauri commands (invoke). It provides a streamlined “ambient” interface for the platform.
Component Mapping
The UI maps internal state to visual components:- ProcessMonitorCard: Visualizes the
ServiceProcessSnapshotfor Gateway, Browserd, and NodeHost apps/desktop/ui/src/App.tsx#8-8. - QuickFactsCard: Displays versioning, uptime, and dashboard access modes apps/desktop/ui/src/App.tsx#9-9.
- HealthStrip: Provides a high-level status bar for the runtime apps/desktop/ui/src/App.tsx#6-6.
API Integration (desktopApi.ts)
The frontend uses a typed bridge to communicate with the Rust backend:get_desktop_companion_snapshot: Fetches the aggregate state including sessions, approvals, and rollout flags apps/desktop/src-tauri/src/commands.rs#122-135.send_companion_chat_message: Routes messages through the local supervisor, handling offline queuing if the gateway is down apps/desktop/src-tauri/src/companion.rs#157-168.decide_companion_approval: Allows the operator to resolve pendingApprovalRecordsdirectly from the desktop shell apps/desktop/src-tauri/src/companion.rs#11-11.
State Reconciliation
The UI maintains local state for sections but reconciles it with the backend during theget_desktop_companion_snapshot call to ensure consistency across window reloads apps/desktop/src-tauri/src/commands.rs#129-133.
Entity Association Diagram
Sources: [apps/desktop/ui/src/App.tsx#60-169](http://apps/desktop/ui/src/App.tsx#60-169), [apps/desktop/ui/src/lib/desktopApi.ts#17-50](http://apps/desktop/ui/src/lib/desktopApi.ts#17-50), [apps/desktop/src-tauri/src/companion.rs#80-101](http://apps/desktop/src-tauri/src/companion.rs#80-101)
Feature Flags and Rollout
The desktop implements “Experimental Governance” to manage new features like the Native Canvas and Ambient Voice mode.Rollout Logic
Rollout state is defined inDesktopCompanionRolloutState apps/desktop/src-tauri/src/desktop_state.rs#72-79. These flags are toggled via the update_desktop_companion_rollout command apps/desktop/src-tauri/src/commands.rs#194-202.
| Flag | Purpose |
|---|---|
companion_shell_enabled | Controls the visibility of the rich chat/approval UI. |
offline_drafts_enabled | Enables the local queuing of messages when offline. |
voice_capture_enabled | Enables the push-to-talk audio attachment pipeline. |
tts_playback_enabled | Enables local speech synthesis for assistant narration. |
Diagnostics Integration
The desktop UI surfaces experiment metadata from/console/v1/diagnostics, including:
- Rollout Stage: (e.g., “preview”).
- Security Review: A list of completed security audits for the feature.
- Exit Criteria: Conditions required to move the feature out of experimental status.
[apps/desktop/src-tauri/src/snapshot.rs#181-208](http://apps/desktop/src-tauri/src/snapshot.rs#181-208), [apps/desktop/src-tauri/src/desktop_state.rs#71-92](http://apps/desktop/src-tauri/src/desktop_state.rs#71-92), [apps/desktop/README.md#100-118](http://apps/desktop/README.md#100-118)