palyrad) and the browser automation service (palyra-browserd). It provides a React-based interface for initial setup (onboarding), real-time process monitoring, and a “Companion Shell” for interacting with agent sessions, managing approvals, and handling offline drafts.
Onboarding Wizard Flow
The onboarding process is a multi-step state machine managed by theControlCenter supervisor. It transitions through several phases to ensure the local environment is prepared, the daemon is initialized, and model providers are configured.
Onboarding Steps
The flow is defined by theDesktopOnboardingStep enum apps/desktop/src-tauri/src/desktop_state.rs#209-219:
- Welcome: Initial landing and acknowledgement.
- Environment: Validation of system requirements and paths.
- State Root: Selection and confirmation of the data directory apps/desktop/src-tauri/src/commands.rs#135-151.
- Gateway Init: Bootstrapping the
palyra.tomlconfiguration and internal database. - Operator Auth: Generating and securing the administrative tokens.
- OpenAI/Discord Connect: Optional steps for connecting external providers and communication channels.
- Dashboard Handoff: Transitioning the user to the full Web Console.
Data Flow: Onboarding Status
The UI polls the onboarding state via theget_onboarding_status Tauri command, which aggregates data into an OnboardingStatusSnapshot apps/desktop/src-tauri/src/onboarding.rs#78-110.
Onboarding State Transitions
| Function | Purpose | File Reference |
|---|---|---|
set_onboarding_state_root_command | Sets the runtime_root where all data is stored. | apps/desktop/src-tauri/src/commands.rs#135-151 |
acknowledge_onboarding_welcome | Marks the initial step as complete in DesktopStateFile. | apps/desktop/src-tauri/src/commands.rs#126-132 |
build_onboarding_status | Computes progress based on persisted state and connectivity. | apps/desktop/src-tauri/src/onboarding.rs#156-160 |
Desktop UI Architecture
The frontend is a React application built with Vite and Tailwind CSS, utilizing@heroui/react for UI components. It communicates with the Rust backend via Tauri’s invoke API.
Key UI Components
App.tsx: The main entry point that manages theactiveSectionstate (“home”, “chat”, “approvals”, etc.) and handles notification permissions apps/desktop/ui/src/App.tsx#52-72.useDesktopCompanion: A custom hook that handles polling for theDesktopCompanionSnapshot, which contains the entire state of the supervisor, processes, and active sessions apps/desktop/ui/src/hooks/useDesktopCompanion.ts.ProcessMonitorCard: Displays real-time status ofpalyradandpalyra-browserdprocesses, including PID and uptime apps/desktop/ui/src/App.tsx#8-8.
UI-to-Code Mapping
The following diagram maps UI concepts to the underlying Rust implementation structures. UI Entity to Code Mapping Sources: apps/desktop/ui/src/App.tsx, apps/desktop/src-tauri/src/commands.rs, apps/desktop/src-tauri/src/supervisor.rsCompanion Shell Features
The Companion Shell provides advanced desktop integration features that extend the capabilities of the headless daemon.Offline Drafts
When the daemon is unreachable or the user wants to queue a message for later, the Desktop UI stores “Offline Drafts” in theDesktopStateFile apps/desktop/src-tauri/src/desktop_state.rs#60-66.
- Implementation: Drafts are stored in a
Vec<DesktopCompanionOfflineDraft>within the persisted state apps/desktop/src-tauri/src/desktop_state.rs#99-99. - Limit: The system maintains a maximum of 20 drafts, after which the oldest are pruned apps/desktop/src-tauri/src/desktop_state.rs#21-21.
Desktop Notifications
The supervisor monitors the daemon’s event stream and pushes notifications to the OS.- Kinds: Notifications cover approvals, connection changes, run status, and trust events apps/desktop/src-tauri/src/desktop_state.rs#41-47.
- Logic: The UI uses a
Setto trackannouncedNotificationIdsRefto prevent duplicate OS alerts during polling cycles apps/desktop/ui/src/App.tsx#170-185.
Handoff and Session Management
The Desktop UI can “handoff” a session to the full Web Console by generating a signed URL using theadmin_token.
build_companion_handoff_url: Generates a local URL with the necessary credentials to bypass standard login when launching from the desktop app apps/desktop/src-tauri/src/companion.rs.
Platform Considerations
The Desktop app handles several OS-specific requirements, particularly regarding process management and path resolution.Process Supervision (Windows vs. macOS/Linux)
TheControlCenter uses tokio::process::Command to manage sidecars. On Windows, it applies specific flags to prevent console windows from appearing.
CREATE_NO_WINDOW: Applied viacommand.creation_flags(0x0800_0000)on Windows apps/desktop/src-tauri/src/lib.rs#21-22.- Path Resolution: The app uses
executable_file_nameto append.exeon Windows when looking for thepalyradsidecar apps/desktop/src-tauri/src/supervisor.rs#50-52.
State and Secret Storage
- State Root: Resolved via
resolve_desktop_state_root, which defaults to standard OS data directories (e.g.,AppData/Localon Windows,Library/Application Supporton macOS) apps/desktop/src-tauri/src/desktop_state.rs#222-225. - Secret Store: Uses
palyra-vaultwith a local backend to store thedesktop_admin_tokenanddesktop_browser_auth_tokenapps/desktop/src-tauri/src/lib.rs#11-12.
Implementation Detail: Supervisor Logic
TheControlCenter is the heart of the desktop application, responsible for process health and log aggregation.
Process Lifecycle & Log Flow
Key Functions
| Function | Description |
|---|---|
ControlCenter::new() | Initializes the state file, secret store, and creates the log channels apps/desktop/src-tauri/src/supervisor.rs#221-233. |
ManagedService::running() | Checks if the child process handle exists and is active apps/desktop/src-tauri/src/supervisor.rs#124-126. |
sanitize_log_line | Redacts sensitive information (tokens, keys) from process logs before they are sent to the UI apps/desktop/src-tauri/src/snapshot.rs#31-33. |