palyrad), handles profile-specific isolation of data, and provides a “Companion Shell” for ambient interactions such as push-to-talk, offline message queuing, and system notifications.
Onboarding State Machine
The onboarding process is governed by theDesktopOnboardingStep state machine. This flow ensures that the local environment is correctly configured before the daemon is allowed to perform high-risk operations.
Onboarding Steps
The state machine progresses through several distinct phases:- Welcome: Initial landing and acknowledgement apps/desktop/src-tauri/src/desktop_state.rs#210-210.
- Environment: Preflight checks for system dependencies apps/desktop/src-tauri/src/desktop_state.rs#211-211.
- StateRoot: Selection and validation of the
runtime_rootwhere all daemon data (Journal, Vault, etc.) is stored apps/desktop/src-tauri/src/desktop_state.rs#212-212. - Operator: Authentication of the local user and generation of the
admin_tokenapps/desktop/src-tauri/src/desktop_state.rs#213-213. - Providers: Configuration of model providers (e.g., OpenAI) apps/desktop/src-tauri/src/desktop_state.rs#214-214.
- Connectors: Setup of external communication channels like Discord apps/desktop/src-tauri/src/desktop_state.rs#215-215.
- Completion: Finalization and handoff to the main dashboard apps/desktop/src-tauri/src/desktop_state.rs#216-216.
Preflight and Validation
Before transitioning steps, theControlCenter executes build_onboarding_status, which aggregates results from probe_dashboard_reachability and port availability checks apps/desktop/src-tauri/src/onboarding.rs#161-165.
| Component | Check | Source |
|---|---|---|
| Ports | Validates 7142, 7443, 7444 are free | apps/desktop/src-tauri/src/lib.rs#16-18 |
| StateRoot | Ensures path is writable and not inside a system dir | apps/desktop/src-tauri/src/desktop_state.rs#38-41 |
| Operator | Verifies admin_token presence in DesktopSecretStore | apps/desktop/src-tauri/src/lib.rs#11-11 |
Profile Isolation and Runtime Switching
Palyra Desktop supports multiple isolated profiles. Each profile maps to a specificruntime_root, allowing users to switch between different agent identities, journal histories, and security contexts.
Profile Registry
Profiles are managed via theDesktopProfileCatalog apps/desktop/src-tauri/src/supervisor.rs#223-223. If no profile is explicitly selected, the system defaults to desktop-local apps/desktop/src-tauri/src/desktop_state.rs#23-23.
Runtime Root Switching
When a user switches profiles viaswitchDesktopCompanionProfile apps/desktop/ui/src/lib/desktopApi.ts#38-38, the ControlCenter performs the following:
- Shutdown: Stops all managed services (
palyrad,browserd) apps/desktop/src-tauri/src/supervisor.rs#227-229. - Re-resolve: Calls
resolve_desktop_state_rootto locate the new profile’s data directory apps/desktop/src-tauri/src/desktop_state.rs#38-38. - Migration: If legacy secrets exist in the
state.jsonfile, they are migrated into thepalyra-vaultviamigrate_legacy_runtime_secrets_from_state_fileapps/desktop/src-tauri/src/desktop_state.rs#37-37. - Restart: Re-initializes the supervisor with the new paths and restarts services apps/desktop/src-tauri/src/commands.rs#147-163.
Onboarding and Profile Entity Mapping
The following diagram illustrates how the natural language concept of “Onboarding” maps to the underlying code entities. Diagram: Onboarding Entity Map Sources: apps/desktop/src-tauri/src/desktop_state.rs#209-217, apps/desktop/src-tauri/src/onboarding.rs#161-165, apps/desktop/src-tauri/src/supervisor.rs#223-223Companion Shell and React Frontend
The “Companion Shell” is the React-based frontend (apps/desktop/ui) hosted within Tauri. It provides a lightweight interface for agent interaction without requiring the full Console UI.
Key Features
- Offline Drafts: If the daemon is unreachable, messages are stored locally as
DesktopCompanionOfflineDraftapps/desktop/src-tauri/src/desktop_state.rs#62-68. These are managed viaqueue_offline_draftand can be re-sent once connectivity is restored apps/desktop/src-tauri/src/desktop_state.rs#179-200. - Push-to-Talk: Implemented in
App.tsxusing the browser’sMediaRecorderAPI apps/desktop/ui/src/App.tsx#90-92. Audio is sent to the daemon viatranscribe_companion_audioapps/desktop/src-tauri/src/companion.rs#184-190. - System Notifications: The shell tracks unread notifications of various types (Approval, Connection, Run) apps/desktop/src-tauri/src/desktop_state.rs#43-49. These are stored in
DesktopCompanionStateand synchronized with the OS notification system apps/desktop/src-tauri/src/desktop_state.rs#96-107.
Data Flow: Message Dispatch
The following diagram shows the flow of a message from the UI through the Desktop bridge to the daemon. Diagram: Message Dispatch Flow Sources: apps/desktop/ui/src/App.tsx#34-34, apps/desktop/src-tauri/src/commands.rs#12-12, apps/desktop/src-tauri/src/companion.rs#157-180, apps/desktop/src-tauri/src/desktop_state.rs#179-200Secret Management and Migration
The Desktop app manages a set of “Runtime Secrets” separate from the daemon’s internal vault. These include thedesktop_admin_token used for authenticating the UI to the daemon and the desktop_browser_auth_token for the browser extension apps/desktop/src-tauri/src/lib.rs#11-12.
DesktopSecretStore
Secrets are stored in an encrypted SQLite backend provided bypalyra-vault. The DesktopSecretStore manages access to these tokens using the admin:desktop-control-center principal apps/desktop/src-tauri/src/lib.rs#7-7.
Legacy Migration
During the transition topalyra-vault, the function migrate_legacy_runtime_secrets_from_state_file handles the extraction of plaintext tokens from the old state.json file and their insertion into the secure vault apps/desktop/src-tauri/src/desktop_state.rs#37-37. This is a critical path during the StateRoot onboarding step.
Sources: apps/desktop/src-tauri/src/lib.rs#7-12, apps/desktop/src-tauri/src/desktop_state.rs#36-41, apps/desktop/src-tauri/src/supervisor.rs#25-27