# Core Technologies Used in PI-Desktop: React, Rust, and Electron Architecture

> Explore the core technologies of PI-Desktop: React, Rust, and Electron. Discover how this AI coding workspace leverages a powerful tech stack for security and local-first operation.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: architecture
- Published: 2026-09-11

---

**PI-Desktop combines a React TypeScript frontend, Electron orchestration layer, Rust system core, and Node.js agent side-car to create a secure, local-first AI coding workspace.**

PI-Desktop is a local-first desktop workspace designed specifically for AI coding agents. Understanding the core technologies used in PI-Desktop reveals how the architecture deliberately separates unprivileged UI components from privileged system services. This hybrid stack unites modern web technologies with native Rust components to deliver both developer experience and security.

## Frontend Stack: React, Vite, and TypeScript

The user interface layer leverages standard modern web technologies while maintaining strict isolation from system resources.

### Renderer Architecture

The renderer is a standard React single-page application built with **Vite** and styled using **Tailwind CSS**. It uses **i18next** for internationalisation and **Shiki** for syntax highlighting. Crucially, the renderer operates with **no Node integration**, ensuring complete isolation from the host runtime. All communication with privileged layers occurs through typed IPC channels defined in [`apps/desktop/src/App.tsx`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/App.tsx).

### Build Configuration

The build pipeline uses [`apps/desktop/electron.vite.config.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron.vite.config.ts) to bundle both the renderer and Electron main process. This configuration ensures that the React application is compiled into static assets that the Electron shell can load securely.

## Electron Main Process

**Electron** serves as the thin orchestration layer that creates application windows, routes IPC messages, and manages the desktop lifecycle. The main process spawns two critical child processes: the **Rust host binary** and the **Node side-car**. When the environment variable `PI_DESKTOP_MCP_CONTROL=1` is set, Electron also launches a loopback MCP control server for advanced integrations.

The entry point for this orchestration lives in [`apps/desktop/main.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/main.ts), which coordinates communication between the renderer, Rust host, and agent runtime through structured message passing.

## Rust Host Core

The `host-core` crate represents the privileged backbone of PI-Desktop, handling all sensitive operations through memory-safe Rust code.

### Workspace Management

Path resolution and filesystem containment logic reside in [`crates/host-core/src/workspace.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/workspace.rs). The `resolve_in_workspace` function performs lexical and symlink-aware path containment, ensuring that agent operations stay within approved workspace boundaries.

```rust
use std::path::Path;
use host_core::workspace::resolve_in_workspace;

// Assume `workspace_root` is the path to the current workspace.
let workspace_root = Path::new("/home/user/project");

// Resolve a user-provided relative path, safely confined to the workspace.
match resolve_in_workspace(workspace_root, "src/lib.rs") {
    Ok(abs_path) => println!("Resolved path: {}", abs_path.display()),
    Err(err) => eprintln!("Failed to resolve: {}", err),
}

```

### Permission and Persistence

The Rust layer owns the **SQLite** databases that store conversations, settings, and audit logs. It also implements the **permission gateway**, evaluating user-approved actions before allowing filesystem writes, network fetches, or desktop operations. This ensures that even if the agent side-car is compromised, it cannot access resources without explicit host approval.

## Agent Side-car: Node.js Runtime

The **Node.js** side-car executes the model-driven agent loop using packages from the *pi-mono* project (**pi-ai** and **pi-agent-core**). Running independently from the renderer, this component handles streaming responses and issues tool-call requests to the Rust host via **JSON-RPC over NDJSON**.

The side-car entry point at [`packages/agent-runtime/src/sidecar.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/agent-runtime/src/sidecar.ts) is bundled as [`Resources/agent-runtime/sidecar.js`](https://github.com/vastsa/PI-Desktop/blob/main/Resources/agent-runtime/sidecar.js) inside the final Electron package. Core agent logic lives in [`packages/agent-runtime/src/runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/agent-runtime/src/runtime.ts), which manages model interaction and transcript streaming.

## Plugin SDK and Extensibility

PI-Desktop exposes a **TypeScript Plugin SDK** that allows third-party extensions to integrate safely with the host system. The SDK defines the `PluginManifest` schema, permission model (`PLUGIN_PERMISSIONS`), and the `PluginHostApi` interface.

Plugins can contribute commands, tools, views, skills, themes, and MCP servers. The SDK validates manifests and exposes controlled APIs such as `fs.readText`, `models.list`, and `desktop.invoke`.

```ts
import { PluginHostApi, PluginTool } from "plugin-sdk";

export async function onLoad(api: PluginHostApi) {
  const echoTool: PluginTool = {
    name: "echo",
    description: "Returns the supplied text",
    execute: async (args) => {
      // `args` is whatever the agent passed.
      return { result: args };
    },
  };

  // Register the tool with the agent runtime.
  await api.agent.registerTool(echoTool);
}

```

## Build System and Tooling

The repository uses **pnpm workspaces** defined in [`pnpm-workspace.yaml`](https://github.com/vastsa/PI-Desktop/blob/main/pnpm-workspace.yaml) to coordinate multiple packages across the monorepo. Release orchestration scripts in `scripts/release.mjs` ensure that compiled assets—including renderer JavaScript, native Rust binaries, and the side-car bundle—are packaged correctly for distribution.

Additional development tools include **TypeBox** for runtime type validation, **Mermaid** for documentation diagrams, and **KaTeX** for mathematical rendering within the chat interface.

## Summary

- **React + Vite**: Powers the isolated renderer UI with TypeScript, Tailwind CSS, and i18next support.
- **Electron**: Orchestrates window management and IPC routing between UI, Rust core, and Node side-car.
- **Rust Host Core**: Handles privileged operations including filesystem enforcement, SQLite persistence, and permission evaluation in [`crates/host-core/src/workspace.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/workspace.rs).
- **Node.js Side-car**: Runs the agent loop and communicates with models via JSON-RPC, bundled from [`packages/agent-runtime/src/runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/agent-runtime/src/runtime.ts).
- **TypeScript Plugin SDK**: Enables safe extension through manifest validation and the `PluginHostApi` interface defined in [`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts).
- **pnpm Workspaces**: Manages the multi-package build process and dependency coordination.

## Frequently Asked Questions

### What frontend framework does PI-Desktop use?

PI-Desktop uses **React** with **TypeScript** for its frontend interface, built using **Vite** as the bundler. The UI layer is strictly isolated from Node.js APIs and can only communicate with system resources through Electron's IPC channels. Styling is handled by **Tailwind CSS**, while **i18next** manages internationalization.

### How does PI-Desktop secure file system access?

All file system operations route through the **Rust host core**, specifically the `resolve_in_workspace` function in [`crates/host-core/src/workspace.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/workspace.rs). This function enforces lexical path containment and symlink-aware resolution, ensuring agents cannot escape the approved workspace directory. The system also maintains an audit log in SQLite and requires explicit user approval for sensitive operations.

### What is the purpose of the Node.js side-car?

The Node.js side-car runs the **pi-agent** loop that interacts with AI models, streams responses, and manages tool execution. It operates as a separate process from the UI and communicates with the privileged Rust core via JSON-RPC over NDJSON streams. This separation prevents model-generated code from directly accessing the file system without Host approval.

### Can developers extend PI-Desktop with custom functionality?

Yes, developers can build plugins using the **TypeScript Plugin SDK** exposed through [`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts). Plugins declare capabilities through a `PluginManifest` and can register tools, commands, and UI panels via the `PluginHostApi` interface. The SDK enforces strict permission boundaries, requiring plugins to request specific capabilities like file system or network access.