Skip to main content
This page documents the state management, multi-step onboarding flow, and the React-based Companion UI of the Palyra Desktop application. These systems bridge the gap between the local Tauri supervisor and the user’s operational needs, providing offline capabilities and a streamlined setup experience.

​
Desktop State & Persistence

The desktop application maintains a persistent state in state.json, managed by the DesktopStateFile struct. This file tracks the onboarding progress, rollout flags, and companion preferences.

​
Schema & Migration

The state follows a versioned schema defined by DESKTOP_STATE_SCHEMA_VERSION apps/desktop/src-tauri/src/lib.rs#9-9. The load_or_initialize_state_file function handles the lifecycle of this file, including automatic migrations when the schema version increments apps/desktop/src-tauri/src/desktop_state.rs#250-280.

​
Vault-Backed Secret Storage

Sensitive runtime secrets, such as the desktop_admin_token and desktop_browser_auth_token, are stored in the DesktopSecretStore. This store utilizes the palyra-vault crate with an EncryptedFile backend apps/desktop/src-tauri/src/desktop_state.rs#434-450.
Secret KeyPurpose
desktop_admin_tokenAuthenticates the Desktop Control Center against the palyrad admin API.
desktop_browser_auth_tokenAuthenticates the palyra-browserd sidecar.
Sources: apps/desktop/src-tauri/src/lib.rs#9-12, apps/desktop/src-tauri/src/desktop_state.rs#216-240, apps/desktop/src-tauri/src/desktop_state.rs#434-460.

​
Onboarding Flow

The onboarding process is a linear state machine defined by DesktopOnboardingStep. It ensures the local environment is prepared before handing off to the web dashboard.

​
Onboarding Steps

  1. Welcome: Initial landing and EULA acknowledgement.
  2. Environment: Preflight checks for dependencies (ports, binaries).
  3. State Root: Selection and validation of the runtime data directory.
  4. Gateway Init: Bootstrapping the palyrad daemon.
  5. Operator Auth: Generating and pinning the local operator identity.
  6. Model Provider (OpenAI): Connecting API keys or OAuth.
  7. Connector (Discord): Optional setup of chat platform integrations.
  8. Dashboard Handoff: Generating a secure token to open the Web Console.
  9. Completion: Finalizing the setup.

​
Preflight Checks

The build_preflight_snapshot function performs non-blocking and blocking checks on the host system, verifying port availability (7142, 7443, 7444) and binary existence for palyrad and palyra-browserd apps/desktop/src-tauri/src/onboarding.rs#201-240.

​
Data Flow: Onboarding Logic

Sources: apps/desktop/src-tauri/src/onboarding.rs#78-112, apps/desktop/src-tauri/src/commands.rs#95-104, apps/desktop/src-tauri/src/desktop_state.rs#205-215.

​
Companion UI & Polling Model

The Companion UI is a React application (apps/desktop/ui) embedded within Tauri. It provides a “lite” version of the console, focused on approvals, notifications, and local status.

​
The Polling Model

The UI uses the useDesktopCompanion hook to synchronize state. Instead of complex WebSocket management for the desktop-to-daemon link, it relies on a high-frequency polling of the get_desktop_companion_snapshot Tauri command apps/desktop/ui/src/hooks/useDesktopCompanion.ts. The snapshot includes:
  • Control Center Status: Process health and logs.
  • Approval Inbox: Pending tool calls requiring human-in-the-loop (HITL) consent.
  • Notification Feed: Real-time alerts for runs, connections, and trust events.
  • Offline Drafts: Messages queued when the daemon is unreachable.

​
Offline Drafts & Queueing

When the palyrad gateway is down or unreachable, the Companion UI allows users to “draft” messages. These are stored in the DesktopCompanionState apps/desktop/src-tauri/src/desktop_state.rs#175-196. Once the gateway returns to a Healthy state, the UI prompts the user to sync these drafts apps/desktop/ui/src/App.tsx#100-104.

​
Companion State Management

Sources: apps/desktop/src-tauri/src/desktop_state.rs#92-120, apps/desktop/src-tauri/src/companion.rs#80-101, apps/desktop/ui/src/lib/desktopApi.ts#256-275.

​
Dashboard Handoff

The transition from the Desktop App to the Web Console (running in a standard browser) is secured via a handoff token.
  1. Request: The user clicks “Open Dashboard” in the Companion UI.
  2. Token Generation: The ControlCenter requests a short-lived admin session from the local palyrad instance apps/desktop/src-tauri/src/snapshot.rs#213-230.
  3. URL Construction: The build_dashboard_open_url function appends the admin_token and a csrf_token to the dashboard URL apps/desktop/src-tauri/src/snapshot.rs#232-250.
  4. Launch: The desktop app invokes the system’s default browser with the authenticated URL.
Sources: apps/desktop/src-tauri/src/commands.rs#191-205, apps/desktop/src-tauri/src/snapshot.rs#213-250.