> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Desktop Application (Tauri)

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * apps/desktop/README.md
  * apps/desktop/src-tauri/Cargo.lock
  * apps/desktop/src-tauri/Cargo.toml
  * apps/desktop/src-tauri/src/commands.rs
  * apps/desktop/src-tauri/src/companion.rs
  * apps/desktop/src-tauri/src/desktop\_state.rs
  * apps/desktop/src-tauri/src/lib.rs
  * apps/desktop/src-tauri/src/onboarding.rs
  * apps/desktop/src-tauri/src/profile\_registry.rs
  * apps/desktop/src-tauri/src/snapshot.rs
  * apps/desktop/src-tauri/src/supervisor.rs
  * apps/desktop/src-tauri/src/tests.rs
  * apps/desktop/src-tauri/src/tests/support.rs
  * apps/desktop/ui/index.html
  * apps/desktop/ui/src/App.tsx
  * apps/desktop/ui/src/lib/desktopApi.ts
  * apps/desktop/ui/src/styles.css
  * apps/web/README.md
  * apps/web/src/console/sections/OverviewSection.tsx
  * crates/palyra-egress-proxy/Cargo.toml
  * crates/palyra-workerd/Cargo.toml
  * fuzz/Cargo.lock
  * fuzz/Cargo.toml
  * scripts/test/run-critical-attack-scenarios.ps1
</details>

The Palyra Desktop Application (the "Desktop Companion") is a Tauri-based distribution that provides a local control-center for supervising Palyra services. It acts as a supervisor for the core daemon (`palyrad`), the browser automation service (`palyra-browserd`), and the local node host (`palyra node`). Beyond process management, it layers a native "Companion Shell" that includes ambient runtime features like a tray-based quick panel, voice overlay, and global hotkeys.

## Architecture Overview

The application follows a standard Tauri split: a Rust-based backend ("src-tauri") for system-level supervision and a React/Vite frontend ("ui") for the operator interface.

### Component Relationship

The following diagram illustrates how the desktop application bridges the user's desktop environment with the Palyra core services.

**Title: Desktop Application Bridge Architecture**

```mermaid theme={null}
graph TD
    subgraph "Desktop App (Tauri)"
        UI["React Frontend (apps/desktop/ui)"]
        CMD["Tauri Commands (commands.rs)"]
        SUP["Supervisor (supervisor.rs)"]
        STATE["Desktop State (desktop_state.rs)"]
    end

    subgraph "Supervised Sidecars"
        DAEMON["palyrad (Gateway)"]
        BROWSER["palyra-browserd"]
        NODE["palyra node host"]
    end

    UI -- "invoke()" --> CMD
    CMD -- "delegate" --> SUP
    SUP -- "spawn/monitor" --> DAEMON
    SUP -- "spawn/monitor" --> BROWSER
    SUP -- "spawn/monitor" --> NODE
    SUP -- "persist" --> STATE
    DAEMON -- "API" --> UI
```

Sources: [apps/desktop/src-tauri/src/lib.rs#1-45](http://apps/desktop/src-tauri/src/lib.rs#1-45), [apps/desktop/src-tauri/src/supervisor.rs#1-15](http://apps/desktop/src-tauri/src/supervisor.rs#1-15), [apps/desktop/README.md#45-57](http://apps/desktop/README.md#45-57)

***

## The Supervisor (`ControlCenter`)

The `ControlCenter` is the central struct in the Rust backend responsible for the lifecycle of local Palyra services. It maintains the `ManagedService` state for each sidecar and performs periodic reconciliation.

### Managed Services

The supervisor manages three primary service kinds:

1. **Gateway (`palyrad`)**: The central daemon.
2. **Browserd (`palyra-browserd`)**: The gRPC-based browser automation engine.
3. **NodeHost (`palyra node host`)**: The first-party execution node for local capabilities.

### Implementation Details

* **Process Management**: Services are spawned using `tokio::process::Command` with `Stdio::piped()` to capture logs [apps/desktop/src-tauri/src/supervisor.rs#127-139](http://apps/desktop/src-tauri/src/supervisor.rs#127-139).
* **Log Buffering**: The supervisor maintains a `VecDeque<LogLine>` for each service, capped at `MAX_LOG_LINES_PER_SERVICE` (400 lines) to provide diagnostic visibility in the UI [apps/desktop/src-tauri/src/lib.rs#8-9](http://apps/desktop/src-tauri/src/lib.rs#8-9), [apps/desktop/src-tauri/src/supervisor.rs#137-138](http://apps/desktop/src-tauri/src/supervisor.rs#137-138).
* **Health Monitoring**: The supervisor performs a "tick" every 500ms to check process liveness and reconcile desired state vs. actual state [apps/desktop/src-tauri/src/lib.rs#7-7](http://apps/desktop/src-tauri/src/lib.rs#7-7).
* **Config Reloading**: A `DesktopConfigReloadWatchState` monitors the `palyra.toml` file. If the configuration changes, the supervisor triggers a restart of the affected sidecars [apps/desktop/src-tauri/src/supervisor.rs#156-162](http://apps/desktop/src-tauri/src/supervisor.rs#156-162).

**Title: Service Lifecycle State Machine**

```mermaid theme={null}
stateDiagram-v2
    [*] --> Stopped
    Stopped --> Starting: desired_running = true
    Starting --> Running: Child process spawned
    Running --> Restarting: Config Change / Crash
    Restarting --> Starting: Exponential Backoff
    Running --> Stopped: desired_running = false
    Restarting --> Stopped: desired_running = false
```

Sources: [apps/desktop/src-tauri/src/supervisor.rs#128-140](http://apps/desktop/src-tauri/src/supervisor.rs#128-140), [apps/desktop/src-tauri/src/supervisor.rs#190-199](http://apps/desktop/src-tauri/src/supervisor.rs#190-199), [apps/desktop/src-tauri/src/tests.rs#130-136](http://apps/desktop/src-tauri/src/tests.rs#130-136)

***

## Desktop State and Profile Registry

The application maintains its own persisted state separate from the daemon's configuration. This is stored in a JSON state file (typically `desktop-state.json`).

### Key State Entities

* **`DesktopStateFile`**: The root persistence object containing onboarding status, rollout flags, and companion preferences [apps/desktop/src-tauri/src/desktop\_state.rs#214-230](http://apps/desktop/src-tauri/src/desktop_state.rs#214-230).
* **`DesktopProfileCatalog`**: Manages the mapping between desktop profiles and their underlying runtime roots. It supports an "implicit" profile named `desktop-local` [apps/desktop/src-tauri/src/desktop\_state.rs#35-35](http://apps/desktop/src-tauri/src/desktop_state.rs#35-35), [apps/desktop/src-tauri/src/profile\_registry.rs#15-25](http://apps/desktop/src-tauri/src/profile_registry.rs#15-25).
* **`DesktopRuntimeSecrets`**: Handles sensitive tokens (e.g., `desktop_admin_token`) using `palyra-vault` for envelope encryption [apps/desktop/src-tauri/src/desktop\_state.rs#350-360](http://apps/desktop/src-tauri/src/desktop_state.rs#350-360).

### Onboarding Flow

The desktop application guides the user through a multi-step onboarding process:

1. **Welcome**: Introduction to the companion.
2. **State Root Selection**: Choosing where Palyra data will be stored.
3. **Profile Initialization**: Setting up the default local profile.
4. **Connector Setup**: Guided flow for Discord or other communication channels [apps/desktop/src-tauri/src/onboarding.rs#15-35](http://apps/desktop/src-tauri/src/onboarding.rs#15-35).

Sources: [apps/desktop/src-tauri/src/desktop\_state.rs#1-30](http://apps/desktop/src-tauri/src/desktop_state.rs#1-30), [apps/desktop/src-tauri/src/onboarding.rs#40-60](http://apps/desktop/src-tauri/src/onboarding.rs#40-60)

***

## Companion Shell and UI (React)

The frontend is a React application built with Vite and HeroUI, communicating with the Rust backend via Tauri's `invoke` API.

### Domain Architecture

The UI is structured around the `useDesktopCompanion` hook, which provides a `DesktopCompanionSnapshot` containing:

* **`control_center`**: Status of the supervised processes and local ports.
* **`session_catalog`**: Recent chat sessions retrieved from the local gateway.
* **`approvals`**: Pending tool execution requests requiring operator intervention.
* **`inventory`**: Available devices and capabilities [apps/desktop/ui/src/lib/desktopApi.ts#223-264](http://apps/desktop/ui/src/lib/desktopApi.ts#223-264).

### Ambient Runtime Features

The application provides "ambient" surfaces that are accessible outside the main window:

* **Quick Panel**: A tray-based menu for rapid session switching and approval management [apps/desktop/README.md#116-118](http://apps/desktop/README.md#116-118).
* **Voice Overlay**: A structured interface for the voice lifecycle: `idle` -> `recording` -> `transcribing` -> `review` -> `sending` [apps/desktop/src-tauri/src/desktop\_state.rs#92-104](http://apps/desktop/src-tauri/src/desktop_state.rs#92-104).
* **Global Hotkeys**: Configurable shortcuts (default: `Cmd/Ctrl+Shift+Space`) to reveal the companion surfaces [apps/desktop/src-tauri/src/desktop\_state.rs#131-136](http://apps/desktop/src-tauri/src/desktop_state.rs#131-136).

### Snapshot and Redaction

To ensure security, the `snapshot.rs` module redacts sensitive information before sending it to the UI. It uses `redact_url_strict` and `redact_auth_error_strict` from `palyra-common` to sanitize log lines and error messages [apps/desktop/src-tauri/src/snapshot.rs#18-23](http://apps/desktop/src-tauri/src/snapshot.rs#18-23).

**Title: Desktop UI Data Flow**

```mermaid theme={null}
graph LR
    subgraph "Rust Backend"
        CC["ControlCenter (supervisor.rs)"]
        SNAP["build_companion_snapshot (snapshot.rs)"]
        RED["Redaction Logic"]
    end

    subgraph "React Frontend"
        HOOK["useDesktopCompanion (hooks/useDesktopCompanion.ts)"]
        APP["App Component (App.tsx)"]
        API["desktopApi.ts"]
    end

    CC --> SNAP
    SNAP --> RED
    RED -- "DesktopCompanionSnapshot" --> API
    API -- "Tauri Invoke" --> HOOK
    HOOK --> APP
```

Sources: [apps/desktop/ui/src/App.tsx#117-160](http://apps/desktop/ui/src/App.tsx#117-160), [apps/desktop/src-tauri/src/snapshot.rs#1-15](http://apps/desktop/src-tauri/src/snapshot.rs#1-15), [apps/desktop/src-tauri/src/commands.rs#146-162](http://apps/desktop/src-tauri/src/commands.rs#146-162)

***

## Desktop Node Enrollment

The desktop application automates the enrollment of the local machine as a Palyra node.

1. **Code Generation**: It requests a pairing code from the local gateway via `/console/v1/pairing/requests/code` [apps/desktop/README.md#57-63](http://apps/desktop/README.md#57-63).
2. **Installation**: It executes `palyra node install` using the generated code.
3. **Supervision**: Once enrolled, the supervisor keeps `palyra node run --json` alive and parses its output to surface device health in the UI [apps/desktop/README.md#63-65](http://apps/desktop/README.md#63-65), [apps/desktop/src-tauri/src/supervisor.rs#51-55](http://apps/desktop/src-tauri/src/supervisor.rs#51-55).

Sources: [apps/desktop/README.md#87-106](http://apps/desktop/README.md#87-106), [apps/desktop/src-tauri/src/supervisor.rs#68-74](http://apps/desktop/src-tauri/src/supervisor.rs#68-74)