How to Run the pi-web Application After Setup: Complete CLI Guide

Run the pi-web application by executing the pi-web CLI command after installation, which spawns a Next.js server on http://127.0.0.1:30141 by default and automatically opens your browser.

The pi-web application from the agegr/pi-web repository provides a browser-based UI for the pi coding-agent. After completing the setup, you launch the application through a command-line interface that handles Node version validation, option parsing, and Next.js server initialization. Understanding the boot sequence and available configuration flags ensures you can customize the server for local development or network exposure.

Prerequisites and Node Version Validation

Before starting the application, ensure your environment meets the Node.js version requirements. The CLI entry point at bin/pi-web.js imports bin/node-version.js to validate that the running Node version meets the minimum supported range (Node 22+). If the version check fails, the process aborts immediately with an error message.

Install the package globally to access the pi-web command system-wide:

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

Alternatively, run without installation using npx:

npx @agegr/pi-web@latest

Starting the pi-web Server

When you execute pi-web, the script at bin/pi-web.js orchestrates the boot process through five distinct stages:

1. Node version validation – Confirms compatibility via bin/node-version.js.
2. Parse launch options – Transforms CLI flags and environment variables into configuration objects using parseLaunchOptions() from lib/pi-web-options.ts.
3. Locate Next.js binary – Resolves the next executable path from the package's node_modules directory.
4. Spawn Next.js process – Executes node <next-bin> start -p <port> -H <hostname> with piped stdio.
5. Browser auto-launch – Opens the default browser once Next.js prints "Ready" (unless disabled).

The server listens on http://<hostname>:<port> with defaults of 127.0.0.1:30141.

CLI Options and Environment Variables

The parseLaunchOptions() function in lib/pi-web-options.ts accepts both command-line arguments and environment variables:

• --port / -p or PORT – Server port (default: 30141)
• --hostname / -H or HOST – Bind address (default: 127.0.0.1)
• --no-open or PI_WEB_NO_OPEN – Disable automatic browser opening
• PI_WEB_PASSWORD – Enable HTTP Basic Auth (username: pi)

Command-line flags take precedence over environment variables. The function uses minimist to parse arguments:

// lib/pi-web-options.ts
export function parseLaunchOptions() {
  const args = minimist(process.argv.slice(2), {
    alias: { p: "port", H: "hostname", "no-open": "noOpen" },
    default: { 
      port: process.env.PORT ?? 30141, 
      hostname: process.env.HOST ?? "127.0.0.1", 
      openBrowser: !(process.env.PI_WEB_NO_OPEN) 
    },
  });
  return { 
    port: String(args.port), 
    hostname: String(args.hostname), 
    openBrowser: Boolean(args.openBrowser) 
  };
}

Common Usage Examples

Run the server with default settings:

pi-web

Customize the port and disable browser auto-open:

pi-web --port 8080 --no-open

Expose on all network interfaces with Basic Auth protection:

PI_WEB_PASSWORD='secure-random-string' pi-web --hostname 0.0.0.0

Use environment variables instead of flags:

PORT=9090 HOST=0.0.0.0 PI_WEB_NO_OPEN=1 pi-web

Security and Network Configuration

When exposing pi-web beyond localhost using --hostname 0.0.0.0, always enable Basic Auth to prevent unauthorized access. Set PI_WEB_PASSWORD to enforce authentication with username pi. The application handles the auth layer before serving the Next.js UI.

For proxy configurations, the application respects standard environment variables like HTTP_PROXY during the startup phase, though specific proxy handling depends on the underlying Node.js and Next.js network stack.

Summary

• Run the pi-web application using the pi-web CLI command after global installation or via npx @agegr/pi-web@latest.
• Default address is http://127.0.0.1:30141, customizable via --port and --hostname flags or PORT and HOST environment variables.
• Auto-browser opens by default; disable with --no-open or PI_WEB_NO_OPEN.
• Security requires PI_WEB_PASSWORD when binding to 0.0.0.0 to enable Basic Auth with username pi.
• Boot process involves Node validation in bin/node-version.js, option parsing in lib/pi-web-options.ts, and Next.js spawning in bin/pi-web.js.

Frequently Asked Questions

What is the default port and host for pi-web?

By default, pi-web binds to 127.0.0.1 on port 30141. You can override these values using the --port and --hostname CLI flags, or by setting the PORT and HOST environment variables before executing the command.

How do I prevent pi-web from automatically opening a browser?

Pass the --no-open flag when starting the server, or set the PI_WEB_NO_OPEN environment variable to any truthy value. The parseLaunchOptions() function in lib/pi-web-options.ts checks for these conditions to disable the browser launch behavior that normally triggers when Next.js reports "Ready".

Can I run pi-web without installing it globally?

Yes. Use npx @agegr/pi-web@latest to download and execute the latest version without permanent installation. This command performs the same Node version validation and boot sequence as the globally installed CLI.

How do I secure pi-web with password protection?

Set the PI_WEB_PASSWORD environment variable when launching the application. This enables HTTP Basic Authentication with the fixed username pi and your chosen password. Always use this setting when exposing the server to the network via --hostname 0.0.0.0 to prevent unauthorized access to the coding-agent UI.

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