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

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

Quick Start Verification

Verify your environment and launch the server using these commands:

# 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:

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

Configure proxy settings before starting:

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:

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 – Primary documentation listing all prerequisites and CLI flags.
• bin/pi-web.js – Parses command-line arguments and loads environment variables.
• lib/http-dispatcher.ts – Implements HTTP/HTTPS proxy handling.
• lib/rpc-manager.ts – Manages AgentSession lifecycle with the local pi agent.
• 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 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.
• 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 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, matching standard Node.js behavior for corporate network environments.

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