# How to Set Up PI-Desktop for Local Development: Complete Setup Guide

> Learn how to set up PI-Desktop for local development with this complete guide. Install Node.js, pnpm, and Rust, clone the repo, and run simple commands to launch the application.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-12

---

**Setting up PI-Desktop requires installing Node.js ≥22.19, pnpm ≥10, and Rust stable, then cloning the repository and running `pnpm install`, `cargo build -p host-core`, `pnpm build:js`, and finally `pnpm dev` to launch the multi-process Electron application.**

PI-Desktop is a multi-process desktop application combining a **React renderer**, **Electron main process**, **Rust host core**, and **Node pi-agent sidecar**. This guide walks through the complete local development setup for the vastsa/PI-Desktop repository, ensuring you can build and run the full stack while respecting the architectural boundaries defined in the specification.

## Prerequisites

Before cloning the repository, install the following toolchains:

- **Node.js** ≥ `22.19` (the CI pipeline uses Node 24)
- **pnpm** ≥ `10` (the repository pins pnpm 11 via [`package.json`](https://github.com/vastsa/PI-Desktop/blob/main/package.json))
- **Rust toolchain** (stable channel with `cargo`)
- **Git** (any recent version)

The repository ships with a [`pnpm-lock.yaml`](https://github.com/vastsa/PI-Desktop/blob/main/pnpm-lock.yaml) that pins exact package versions. Using the bundled pnpm version ensures dependency parity with the maintainers.

## Step-by-Step Installation Guide

### Clone the Repository

Start by cloning the monorepo and changing into the directory:

```bash
git clone https://github.com/vastsa/PI-Desktop.git
cd PI-Desktop

```

The repository root contains the monorepo definition in [`pnpm-workspace.yaml`](https://github.com/vastsa/PI-Desktop/blob/main/pnpm-workspace.yaml) and the Rust workspace manifest [`Cargo.toml`](https://github.com/vastsa/PI-Desktop/blob/main/Cargo.toml).

### Install JavaScript Dependencies

Install all packages across the workspace using pnpm:

```bash
pnpm install

```

This reads the workspace definition ([`pnpm-workspace.yaml`](https://github.com/vastsa/PI-Desktop/blob/main/pnpm-workspace.yaml)) and installs dependencies for all packages under `packages/` and `apps/desktop/`.

### Build the Rust Host Core

Compile the privileged host core that provides filesystem, SQLite, and secret storage APIs:

```bash
cargo build -p host-core

```

The host core lives in `crates/host-core/` and provides the privileged API used by the Electron and agent processes according to the architecture spec.

### Build the JavaScript Bundles

Compile the React renderer and Electron main process TypeScript sources:

```bash
pnpm build:js

```

This runs Vite to bundle the renderer assets and transpiles the Electron main process code defined in [`apps/desktop/main/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/main/index.ts).

### Launch in Development Mode

Start the application with hot-reloading enabled:

```bash
pnpm dev

```

This command starts Electron and spawns the Rust host binary and Node pi-agent sidecar, reproducing the production process model described in [`docs/spec/02-architecture/01-architecture.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/02-architecture/01-architecture.md).

## Verify Your Development Build

After the initial setup, validate the health of your environment with the built-in verification scripts:

```bash
pnpm typecheck   # TypeScript type checking across the codebase

pnpm lint        # ESLint validation

pnpm test        # Unit and integration tests

```

All test suites must pass before committing changes. Additional end-to-end suites are documented in [`docs/spec/06-delivery/04-e2e-test-plan.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/04-e2e-test-plan.md).

## Understanding the Architecture

PI-Desktop uses a **layered architecture** that strictly separates UI, privileged capabilities, and the agent loop:

```

Renderer (React UI) → preload IPC → Electron Main → Rust Host Core ↔ Node pi-Agent Sidecar

```

- **Renderer**: Unprivileged React code in `apps/desktop/src/` never accesses SQLite or the filesystem directly.
- **Electron Main**: Thin orchestrator in [`apps/desktop/main/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/main/index.ts) routes IPC and supervises processes.
- **Rust Host Core**: Owns persistence (SQLite), secret storage (OS keychain), and permission enforcement via [`crates/host-core/src/lib.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/lib.rs).
- **pi-Agent Sidecar**: Executes model providers and runs the planning loop via `packages/agent-runtime/src/*`.

When you run `pnpm dev`, Electron launches the renderer and spawns the Rust host binary and Node sidecar, mirroring the production architecture.

## Common Development Workflows

### Opening a Project Programmatically

From the React renderer, trigger a folder selection through the IPC layer:

```typescript
import { openProject } from '@pi-desktop/app-store';

await openProject('/path/to/your/local/repo');

```

The call traverses the preload IPC to Electron Main, which asks the Rust host core to verify the path and create the workspace directory (`.pi/`).

### Configuring a Model Provider

Add a provider like Ollama via the settings API:

```typescript
await fetch('/api/model-config', {
  method: 'POST',
  body: JSON.stringify({
    provider: 'ollama',
    endpoint: 'http://localhost:11434',
    apiKey: '' // stored securely by the host core
  })
});

```

The request forwards to the pi-agent sidecar, which builds a `ProviderConfig` object. Secrets are stored in the OS keychain by the Rust host core.

### Running Agent Tools

Trigger sandboxed shell commands from the agent runtime:

```typescript
await piAgent.callTool('shell.exec', {
  command: 'git status',
  cwd: '/path/to/project'
});

```

The agent emits a tool-call RPC, the host core validates the permission (`agent.extension`), executes the command in a sandboxed workspace, and streams output back to the renderer.

## Key Source Files to Reference

Familiarize yourself with these critical paths:

- **[`pnpm-workspace.yaml`](https://github.com/vastsa/PI-Desktop/blob/main/pnpm-workspace.yaml)** – Defines the monorepo workspace boundaries.
- **[`Cargo.toml`](https://github.com/vastsa/PI-Desktop/blob/main/Cargo.toml)** – Rust workspace manifest for building the host core.
- **[`crates/host-core/src/lib.rs`](https://github.com/vastsa/PI-Desktop/blob/main/crates/host-core/src/lib.rs)** – Core privileged APIs for SQLite, permissions, and tool execution.
- **[`apps/desktop/main/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/main/index.ts)** – Electron main process entry point.
- **`apps/desktop/src/*`** – React renderer components (chat, Composer, etc.).
- **`packages/agent-runtime/src/*`** – pi-agent sidecar implementation for tool calls and planning.

## Summary

- Install **Node.js ≥22.19**, **pnpm ≥10**, and **Rust stable** before starting.
- Run `cargo build -p host-core` to compile the privileged Rust layer before launching the app.
- Use `pnpm dev` to start Electron with the Rust host core and pi-agent sidecar attached.
- Verify builds with `pnpm typecheck`, `pnpm lint`, and `pnpm test` to ensure code quality.
- The architecture enforces strict boundaries: React never touches the filesystem directly; all privileged operations route through the Rust host core.

## Frequently Asked Questions

### What are the minimum Node.js and pnpm versions required?

The repository requires **Node.js ≥22.19** and **pnpm ≥10**, though the CI environment uses Node 24 and the repository pins pnpm 11. Using older versions may cause lockfile mismatches or build failures in the `apps/desktop` workspace.

### Why does PI-Desktop require both Rust and Node.js?

The **Rust host core** (`crates/host-core/`) handles privileged operations like SQLite persistence, secret storage via the OS keychain, and sandboxed tool execution, while the **Node.js/Electron** layer manages the UI renderer and main process orchestration. This separation prevents the web-based renderer from accessing sensitive system resources directly, enforcing the security model defined in the architecture specification.

### How do I troubleshoot build errors in the Rust host core?

Ensure you have the **stable Rust toolchain** installed via rustup. Run `cargo check -p host-core` to get detailed compiler diagnostics without performing a full build. If linking errors occur, verify that system dependencies (like `libssl-dev` on Linux or Xcode tools on macOS) are present, as the host core may link against native libraries for SQLite and cryptography.

### Can I run PI-Desktop without building the Rust components?

No. The **Electron main process** ([`apps/desktop/main/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/main/index.ts)) spawns the Rust host core binary at runtime to handle all persistence and permission logic. Without `cargo build -p host-core`, the application will fail to initialize the backend services required for project management and agent execution.