# Prerequisites for Running the Pi-Web Application: Complete Setup Guide

> Discover the prerequisites for running the pi-web application. Learn about Node.js, local pi coding agent, and optional environment variables for a smooth setup. Get started now.

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

---

**To run the pi-web application, you need Node.js ≥22.19.0, a local pi coding agent with accessible session files, and optionally environment variables for authentication, networking, or proxy configuration.**

Pi-Web is a browser-based UI for the **pi coding agent** hosted in the `agegr/pi-web` repository. Before starting the server, you must satisfy specific system-level dependencies and directory access requirements. This guide breaks down every prerequisite using the actual source implementation.

## System Requirements

### Node.js Runtime

Pi-Web requires **Node.js ≥22.19.0** to execute. The application leverages modern ECMAScript features and depends on Next.js 14 tooling that relies on runtime APIs unavailable in older versions. Verify your installation before proceeding.

### Pi Coding Agent Installation

The application cannot function without the **pi coding agent** installed locally. Pi-Web reads session files from `~/.pi/agent/sessions/` and communicates with the agent via an in-process `AgentSession` object managed in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts). Without the agent's data present, the UI cannot load conversations.

## Configuration Prerequisites

### Data Directory Access

By default, Pi-Web looks for agent data under `~/.pi/agent`. If you store sessions in a non-standard location, set the **`PI_CODING_AGENT_DIR`** environment variable so the server knows where to read and write session data.

### Optional Environment Variables

The CLI entry point at [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js) reads several optional variables at startup:

- **`PI_WEB_PASSWORD`** – Enables HTTP Basic Auth (username is always `pi`).
- **`PI_WEB_HOSTNAME`** – Controls which network interface the server binds to.
- **`PI_WEB_ALLOWED_HOSTS`** – Restricts reachable hostnames for security.
- **`PI_WEB_NO_OPEN`** – Prevents the server from auto-opening a browser tab.

### HTTP/HTTPS Proxy Settings

If the server must reach external model APIs through a proxy, Pi-Web respects standard Node.js proxy variables. The [`lib/http-dispatcher.ts`](https://github.com/agegr/pi-web/blob/main/lib/http-dispatcher.ts) file implements handling for **`HTTP_PROXY`**, **`HTTPS_PROXY`**, and **`NO_PROXY`** to route outbound requests correctly.

### Git Worktree Support

To browse multiple Git worktrees from the sidebar, ensure **Git is installed** on the host system. Worktrees must be created in the same OS or container as the agent, as documented in [`docs/worktrees.md`](https://github.com/agegr/pi-web/blob/main/docs/worktrees.md).

## Quick Start Verification

Verify your environment and launch the server using these commands:

```bash

# Check Node.js version (must be ≥22.19.0)

node --version

# Run without installing (npx pulls the latest package)

npx @agegr/pi-web@latest

# Or install globally and start

npm install -g @agegr/pi-web@latest
pi-web            # starts on 127.0.0.1:30141 and opens browser

```

Start on a custom port with basic authentication enabled:

```bash
PI_WEB_PASSWORD=super-secret pi-web --port 8080

```

Configure proxy settings before starting:

```bash
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1
pi-web

```

Run behind a reverse proxy with a non-loopback hostname:

```bash
PI_WEB_HOSTNAME=0.0.0.0 PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web

```

## Key Source Files

Understanding these files helps troubleshoot setup issues:

- **[`README.md`](https://github.com/agegr/pi-web/blob/main/README.md)** – Primary documentation listing all prerequisites and CLI flags.
- **[`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js)** – Parses command-line arguments and loads environment variables.
- **[`lib/http-dispatcher.ts`](https://github.com/agegr/pi-web/blob/main/lib/http-dispatcher.ts)** – Implements HTTP/HTTPS proxy handling.
- **[`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts)** – Manages `AgentSession` lifecycle with the local pi agent.
- **[`docs/worktrees.md`](https://github.com/agegr/pi-web/blob/main/docs/worktrees.md)** – Explains Git worktree integration requirements.

## Summary

- **Node.js ≥22.19.0** is mandatory for modern runtime features.
- The **pi coding agent** must be installed with session files accessible at `~/.pi/agent/` (or via `PI_CODING_AGENT_DIR`).
- **Environment variables** in [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js) control authentication, networking, and startup behavior.
- **Proxy variables** (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) are respected for external API calls via [`lib/http-dispatcher.ts`](https://github.com/agegr/pi-web/blob/main/lib/http-dispatcher.ts).
- **Git installation** is optional but required for worktree browsing features.

## Frequently Asked Questions

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

Pi-Web requires **Node.js ≥22.19.0**. This version provides the ECMAScript features and APIs needed by Next.js 14 and the modern tooling chain. Older versions will fail to start or lack required runtime capabilities.

### Can I run pi-web without the pi coding agent installed?

No. Pi-Web is strictly a UI layer that reads the agent's session files from `~/.pi/agent/sessions/` and communicates via `AgentSession` objects. Without the agent's data directory present, the server cannot load conversations or function properly.

### How do I configure authentication for pi-web?

Set the **`PI_WEB_PASSWORD`** environment variable before starting the server. This enables HTTP Basic Auth with the fixed username `pi`. The variable is read by [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js) at startup. You can also restrict access via `PI_WEB_ALLOWED_HOSTS` to control which hostnames reach the server.

### Does pi-web support running behind a corporate proxy?

Yes. Pi-Web respects **`HTTP_PROXY`**, **`HTTPS_PROXY`**, and **`NO_PROXY`** environment variables for outbound requests. The proxy handling is implemented in [`lib/http-dispatcher.ts`](https://github.com/agegr/pi-web/blob/main/lib/http-dispatcher.ts), matching standard Node.js behavior for corporate network environments.