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

> Easily set up the agegr/pi-web project locally with our complete development guide. Follow these simple steps to get the Pi Web UI running on your machine in minutes.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/agegr/pi-web/blob/main/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:

```bash
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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/package.json) (lines 30-38):

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/agegr/pi-web/blob/main/components/AppShell.tsx)**: The root layout managing top-level navigation and theme state.
- **[`components/SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/components/SessionSidebar.tsx)**: The session tree and file explorer panel.
- **[`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/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:

```bash

# 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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) parses `.jsonl` session files, while [`lib/normalize.ts`](https://github.com/agegr/pi-web/blob/main/lib/normalize.ts) converts tool-call payloads into UI-friendly structures.
- **Worktree Operations**: [`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`.