Skip to main content
The Palyra Desktop application (Companion Shell) manages the lifecycle of the local daemon (palyrad) and the browser daemon (palyra-browserd), providing a guided onboarding experience for new users and sophisticated profile isolation for advanced users.

​
Desktop Onboarding State Machine

Onboarding is managed via a state machine defined by the DesktopOnboardingStep enum apps/desktop/src-tauri/src/desktop_state.rs#205-215. The ControlCenter tracks the current step and any failures in the DesktopStateFile apps/desktop/src-tauri/src/desktop_state.rs#217-233.

​
Onboarding Steps

StepPurpose
WelcomeInitial greeting and risk acknowledgment.
EnvironmentVerification of binary paths and system requirements.
StateRootSelection of the directory for data persistence (Journal, Vault, etc.).
GatewayInitBootstrapping the palyrad configuration and initial start.
OperatorAuthBootstrapGenerating the desktop_admin_token and setting up mTLS.
OpenAiConnectOAuth or API Key configuration for the primary LLM provider.
DiscordConnect(Optional) Setting up the Discord connector for remote access.
DashboardHandoffTransitioning the user to the full Web Console.
CompletionFinalizing the setup and marking the profile as active.
Sources: apps/desktop/src-tauri/src/desktop_state.rs#205-215, apps/desktop/src-tauri/src/onboarding.rs#78-112

​
Profile Isolation & Management

Palyra supports multiple isolated profiles, allowing users to switch between different environments (e.g., “local-dev”, “production-admin”). Profiles are managed through the DesktopProfileCatalog apps/desktop/src-tauri/src/profile_registry.rs#135-141.

​
DesktopStateFile Persistence

The DesktopStateFile is the primary persistence mechanism for the Desktop app, stored in the state.json file within the Desktop state root apps/desktop/src-tauri/src/supervisor.rs#211-212. It tracks:

​
Profile Switching Logic

When a profile is switched via switch_desktop_companion_profile apps/desktop/src-tauri/src/companion.rs#245-263, the following flow occurs:
  1. The ControlCenter stops all running services (palyrad, browserd).
  2. The active_profile_name is updated in DesktopStateFile.
  3. The runtime_root is re-resolved based on the new profile’s configuration.
  4. Secrets are re-loaded from the new profile’s Vault.
  5. Services are restarted using the new profile’s environment.
Sources: apps/desktop/src-tauri/src/desktop_state.rs#217-233, apps/desktop/src-tauri/src/supervisor.rs#205-226, apps/desktop/src-tauri/src/companion.rs#245-263

​
Secret Migration to Vault

Historically, the Desktop app stored administrative tokens in plain text within state.json. Modern versions migrate these to the palyra-vault apps/desktop/src-tauri/src/desktop_state.rs#259-284.

​
Migration Process

The function migrate_legacy_runtime_secrets_from_state_file apps/desktop/src-tauri/src/desktop_state.rs#320-357 performs the following:
  1. Checks if legacy_admin_token or legacy_browser_auth_token exist in the DesktopStateFile.
  2. Initializes a Vault using the DesktopSecretStore backend apps/desktop/src-tauri/src/desktop_state.rs#260-265.
  3. Writes the tokens to the Vault under the VaultScope::Runtime apps/desktop/src-tauri/src/desktop_state.rs#343-352.
  4. Clears the legacy fields from the state file and increments the schema_version.
Sources: apps/desktop/src-tauri/src/desktop_state.rs#259-284, apps/desktop/src-tauri/src/desktop_state.rs#320-357

​
Offline Drafts

The Desktop Companion Shell allows users to compose messages even when the daemon is offline or unreachable. These are managed as DesktopCompanionOfflineDraft objects apps/desktop/src-tauri/src/desktop_state.rs#62-68.

​
Draft Lifecycle

  1. Queueing: If a message fails to send and queue_on_failure is true, queue_offline_draft is called apps/desktop/src-tauri/src/desktop_state.rs#175-196.
  2. Persistence: Drafts are stored in the notifications array within DesktopCompanionState apps/desktop/src-tauri/src/desktop_state.rs#101.
  3. Removal: Once a draft is successfully sent or manually deleted, remove_offline_draft purges it by ID apps/desktop/src-tauri/src/desktop_state.rs#198-200.
Sources: apps/desktop/src-tauri/src/desktop_state.rs#62-68, apps/desktop/src-tauri/src/desktop_state.rs#175-201

​
Technical Diagrams

​
Onboarding Data Flow

This diagram illustrates how the ControlCenter orchestrates the onboarding process and persists state. Sources: apps/desktop/src-tauri/src/commands.rs#84-93, apps/desktop/src-tauri/src/supervisor.rs#205-226, apps/desktop/src-tauri/src/desktop_state.rs#217-233

​
Profile Registry & Resolution

This diagram shows the relationship between profile definitions and the active runtime environment. Sources: apps/desktop/src-tauri/src/profile_registry.rs#135-141, apps/desktop/src-tauri/src/supervisor.rs#410-440, crates/palyra-cli/src/app/mod.rs#82-89

​
Key Implementation Details

​
DesktopStateFile Schema

The DesktopStateFile versioning is tracked by DESKTOP_STATE_SCHEMA_VERSION apps/desktop/src-tauri/src/lib.rs#9. It contains the DesktopOnboardingState apps/desktop/src-tauri/src/desktop_state.rs#217-233 and the DesktopCompanionState apps/desktop/src-tauri/src/desktop_state.rs#92-103.

​
Runtime Secret Keys

The following keys are used for storing secrets in the Vault: Sources: apps/desktop/src-tauri/src/lib.rs#9-12, apps/desktop/src-tauri/src/desktop_state.rs#92-103, apps/desktop/src-tauri/src/desktop_state.rs#217-233