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

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)
• Rust toolchain (stable channel with cargo)
• Git (any recent version)

The repository ships with a 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:

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

The repository root contains the monorepo definition in pnpm-workspace.yaml and the Rust workspace manifest Cargo.toml.

Install JavaScript Dependencies

Install all packages across the workspace using pnpm:

pnpm install

This reads the workspace definition (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:

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:

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.

Launch in Development Mode

Start the application with hot-reloading enabled:

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.

Verify Your Development Build

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

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.

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 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.
• 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:

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:

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:

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 – Defines the monorepo workspace boundaries.
• Cargo.toml – Rust workspace manifest for building the host core.
• crates/host-core/src/lib.rs – Core privileged APIs for SQLite, permissions, and tool execution.
• 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}