palyrad, palyra-browserd, and the node-host) while providing a React-based “Companion Shell” for direct operator interaction apps/desktop/README.md#3-5. It bridges the gap between the local native environment and the web-based dashboard, offering session-aware chat, approval management, and automated node enrollment apps/desktop/README.md#18-35.
Companion Shell Architecture
The companion shell is implemented as a React SPA hosted within a Tauri webview. It communicates with the Rust-basedControlCenter via Tauri commands to fetch state snapshots and dispatch actions apps/desktop/src-tauri/src/commands.rs#67-135.
State Management and Snapshots
The UI is driven by a comprehensive snapshot pattern. Theget_desktop_companion_snapshot command aggregates data from the local supervisor, the daemon’s /console/v1 APIs, and persisted local state apps/desktop/src-tauri/src/commands.rs#122-135.
| Entity | Role |
|---|---|
DesktopCompanionSnapshot | The root data structure containing metrics, session catalogs, and rollout state apps/desktop/src-tauri/src/companion.rs#80-101. |
DesktopCompanionState | Persisted local state including notifications and offline drafts apps/desktop/src-tauri/src/desktop_state.rs#96-107. |
DesktopCompanionMetrics | Real-time counts of unread notifications, pending approvals, and active runs apps/desktop/src-tauri/src/companion.rs#43-51. |
Navigation and Sections
The shell is organized into five primary sections, tracked by theDesktopCompanionSection enum apps/desktop/src-tauri/src/desktop_state.rs#25-33:
- Home: Overview of system health, quick facts, and attention items apps/desktop/ui/src/App.tsx#51.
- Chat: Session-aware interface for interacting with the agent apps/desktop/ui/src/App.tsx#52.
- Approvals: Inbox for pending tool execution requests apps/desktop/ui/src/App.tsx#53.
- Access: Inventory management and node enrollment status apps/desktop/ui/src/App.tsx#54.
- Onboarding: Multi-step wizard for initial environment setup apps/desktop/ui/src/App.tsx#55.
Interaction Flow: Chat and Approvals
The companion reuses the same control-plane contracts as the web dashboard but adds desktop-specific features like offline drafts and audio transcription.Chat and Offline Drafts
When an operator sends a message, the shell attempts to dispatch it to the daemon. If the daemon is unreachable, the message can be stored as aDesktopCompanionOfflineDraft apps/desktop/src-tauri/src/desktop_state.rs#62-68. These drafts are persisted locally and can be resent once connectivity is restored apps/desktop/src-tauri/src/desktop_state.rs#179-200.
Audio Transcription
The companion supports push-to-talk voice capture. Audio is captured in the UI, converted to base64, and sent to the Rust backend viatranscribe_companion_audio apps/desktop/src-tauri/src/companion.rs#184-190. The backend proxies this to the configured provider’s transcription service apps/desktop/src-tauri/src/companion.rs#218-230.
Approval Pipeline
Theapprovals section lists requests requiring operator mediation. The shell calls decide_companion_approval to approve or deny a request apps/desktop/src-tauri/src/commands.rs#11-15, which then communicates with the ApprovalsService on the daemon apps/desktop/src-tauri/src/companion.rs#340-350.
Sources: apps/desktop/src-tauri/src/desktop_state.rs#62-200, apps/desktop/src-tauri/src/companion.rs#184-230, apps/desktop/src-tauri/src/commands.rs#11-21
Desktop Node Enrollment
The desktop supervises a first-partypalyra node host. Enrollment automates the mTLS pairing flow apps/desktop/README.md#53-58.
Enrollment Lifecycle
- Request: The UI triggers enrollment via
enrollDesktopNodeapps/desktop/ui/src/lib/desktopApi.ts#23. - Pairing: The Rust backend fetches a pairing code from the local gateway apps/desktop/README.md#56-57.
- Installation: The supervisor runs
palyra node installwith the generated code apps/desktop/README.md#57. - Mediation: The operator approves the new node pairing through the authenticated control-plane session apps/desktop/README.md#57-58.
- Execution: Once enrolled, the supervisor keeps
palyra node run --jsonalive as a managed service apps/desktop/README.md#58.
Onboarding and Preflight Checks
The onboarding flow ensures the environment is correctly configured before the daemon starts.Preflight Checks
Thebuild_preflight_snapshot function executes a series of checks apps/desktop/src-tauri/src/onboarding.rs#201-205:
- Binary Resolution: Ensures
palyrad,palyra-browserd, andpalyra(CLI) are present in the expected paths apps/desktop/src-tauri/src/onboarding.rs#206-210. - Port Availability: Verifies that the required ports (Gateway Admin, gRPC, QUIC) are not in use apps/desktop/src-tauri/src/onboarding.rs#211-215.
- State Root: Validates that the runtime state directory is writable apps/desktop/src-tauri/src/onboarding.rs#216-220.
Dashboard Handoff Flow
The final step of onboarding is the “Dashboard Handoff”. This flow generates a secure, short-lived token to open the full web dashboard in the operator’s default browser apps/desktop/README.md#48.- The
open_desktop_companion_handoffcommand builds a URL containing the admin token and CSRF state apps/desktop/src-tauri/src/commands.rs#215-225. - The browser console uses this token to establish a session without requiring manual credential entry apps/desktop/README.md#48.
Rollout and Feature Flags
The companion uses local feature flags to control the availability of experimental features apps/desktop/src-tauri/src/desktop_state.rs#72-79.Rollout State
TheDesktopCompanionRolloutState struct tracks enabled features apps/desktop/src-tauri/src/desktop_state.rs#72-79:
companion_shell_enabled: Global toggle for the React UI.voice_capture_enabled: Enables the push-to-talk audio pipeline.tts_playback_enabled: Enables local Text-to-Speech narration.offline_drafts_enabled: Enables the local draft queue.
Technical Diagrams
Desktop Companion Component Mapping
This diagram maps UI components and Tauri commands to their corresponding Rust implementations in thesrc-tauri crate.
Sources: apps/desktop/ui/src/App.tsx#60-84, apps/desktop/src-tauri/src/commands.rs#122-135, apps/desktop/src-tauri/src/companion.rs#80-101, apps/desktop/src-tauri/src/desktop_state.rs#62-68