How to Set Up the agegr/pi-web Project Locally: Complete Development Guide

Clone the repository, ensure Node.js ≥22.19.0 is installed, run npm install followed by npm run dev, then open http://127.0.0.1:30141 to access the Pi Web UI.

The agegr/pi-web repository provides a Next.js-based browser interface for the pi coding agent, enabling real-time chat, file browsing, and session management. Setting up the project locally requires Node.js 22.19.0 or newer and follows a standard Node-based workflow with additional environment configuration options for security and networking. This guide covers the complete installation process, environment configuration, and verification steps based on the current source tree.

Prerequisites

Before installing, verify your environment meets the following requirements:

• Node.js ≥22.19.0: Check your version with node --version. The package.json explicitly specifies this minimum version in the engines field.
• Git: Required to clone the repository.
• Optional: HTTP proxy: If your network routes server-side API calls through a proxy, prepare HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.

Clone and Install

Execute the following commands to download the source and install dependencies:

git clone https://github.com/agegr/pi-web.git
cd pi-web
npm install

The npm install command installs all production and development dependencies listed in package.json. This repository uses Next.js along with React hooks and TypeScript tooling.

Start the Development Server

Launch the local development server using the npm script defined in package.json (lines 30-38):

npm run dev

By default, this binds to http://127.0.0.1:30141 and automatically opens your browser. The server supports hot reloading for rapid development.

To expose the server on your LAN for access from other devices:

npm run dev:lan

This variant binds to 0.0.0.0 instead of 127.0.0.1, allowing connections from other machines on your network.

Install the Global CLI (Optional)

If you prefer a system-wide command rather than running npm scripts from the project directory, install the package globally:

npm install -g @agegr/pi-web@latest
pi-web

The global pi-web command uses the same default configuration (-H 127.0.0.1 -p 30141) as npm run dev. Uninstall with npm uninstall -g @agegr/pi-web if needed.

Configure Environment Variables

The application respects several environment variables for runtime configuration. Set these before running the dev server or prefix your command:

Variable	Purpose	Example
PI_WEB_PASSWORD	Enables HTTP Basic Auth (user: pi) for all endpoints	PI_WEB_PASSWORD='secure-pass' npm run dev
PI_WEB_HOSTNAME	Hostname to bind (default 127.0.0.1)	PI_WEB_HOSTNAME=0.0.0.0 npm run dev
PI_WEB_ALLOWED_HOSTS	Comma-separated hostnames allowed behind reverse proxies	PI_WEB_ALLOWED_HOSTS=pi-web.internal npm run dev
PI_WEB_NO_OPEN	Disables automatic browser launch	PI_WEB_NO_OPEN=1 npm run dev
HTTP_PROXY / HTTPS_PROXY / NO_PROXY	Proxy configuration for server-side fetches	HTTP_PROXY=http://proxy:8080 npm run dev

For example, to run with password protection and LAN access without auto-opening:

PI_WEB_PASSWORD='my-secret' PI_WEB_HOSTNAME=0.0.0.0 PI_WEB_NO_OPEN=1 npm run dev

Verify the Installation

Open http://127.0.0.1:30141 (or your configured host/port) in a browser. The UI should display three primary interface regions:

• components/AppShell.tsx: The root layout managing top-level navigation and theme state.
• components/SessionSidebar.tsx: The session tree and file explorer panel.
• components/ChatWindow.tsx: The chat interface handling message composition and SSE streaming.

The application reads local pi session files from ~/.pi/agent/sessions/. If the sidebar displays your existing sessions and the file explorer loads without errors, the setup is successful.

Development Workflow

Use these commands during development to maintain code quality:

# Run the test suite

npm test

# Type-check without emitting files

node_modules/.bin/tsc --noEmit

# Lint the codebase

npm run lint

# Build for production (avoid during active development)

npm run build

Architecture Context

Understanding the codebase structure helps with debugging and customization:

• API Layer: Server-side routes reside in app/api/. The file app/api/agent/[id]/events/route.ts handles Server-Sent Events (SSE) streaming to the frontend.
• Session Management: lib/rpc-manager.ts maintains a global registry (globalThis.__piSessions) of AgentSessionWrapper instances, ensuring singletons survive Next.js hot reloads with a 10-minute idle timeout.
• File Security: lib/file-access.ts implements an allow-list for file system access based on session working directories and project roots.
• Session Parsing: lib/session-reader.ts parses .jsonl session files, while lib/normalize.ts converts tool-call payloads into UI-friendly structures.
• Worktree Operations: lib/worktree.ts resolves git worktrees and groups sessions by project.

Summary

• Node.js 22.19.0 or newer is required to run the agegr/pi-web project.
• Use git clone and npm install to set up the repository, then npm run dev to start the server on port 30141.
• The global CLI (npm install -g @agegr/pi-web@latest) provides a convenient pi-web command for non-project-directory usage.
• Configure PI_WEB_PASSWORD, PI_WEB_HOSTNAME, and proxy variables to customize security and networking.
• Verify successful setup by checking that components/SessionSidebar.tsx loads your ~/.pi/agent/sessions/ data.

Frequently Asked Questions

What Node.js version is required for agegr/pi-web?

The project requires Node.js ≥22.19.0, as specified in the engines field of package.json. Verify your installation with node --version before running npm install.

How do I run the development server on my local network?

Use the npm run dev:lan command, which binds to 0.0.0.0 instead of 127.0.0.1. Alternatively, set PI_WEB_HOSTNAME=0.0.0.0 when running the standard dev server or global CLI.

How do I disable the automatic browser launch?

Set the environment variable PI_WEB_NO_OPEN=1 before starting the server. For example: PI_WEB_NO_OPEN=1 npm run dev. This prevents the system from automatically opening http://127.0.0.1:30141 in your default browser.

How do I protect the UI with a password?

Set the PI_WEB_PASSWORD environment variable when starting the server. This enables HTTP Basic Authentication with the username pi and your specified password on all UI pages and API endpoints. Example: PI_WEB_PASSWORD='secure-password' pi-web.

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