Pi-Web Deployment Strategy: Local Development to Production Setup

Pi-Web deploys as a local Node.js process using a CLI wrapper that starts a Next.js development server, configurable via environment variables and suitable for reverse-proxy fronting in production environments.

The agegr/pi-web repository provides a lightweight, local web UI for managing AI coding sessions. Understanding the deployment strategy for pi-web enables you to run it as a standalone development tool, a background service, or a production-grade web application behind a reverse proxy.

Installation Methods

Pi-Web offers two primary installation paths that both leverage the bin/pi-web.js entry point defined in package.json.

NPX One-Liner

The fastest deployment method requires no permanent installation. Execute the package directly using npx:

npx @agegr/pi-web@latest

This command downloads and runs the latest version on-the-fly, making it ideal for testing or CI/CD pipelines.

Global NPM Installation

For persistent access to the pi-web command, install the package globally:

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

After installation, the pi-web binary becomes available system-wide, invoking the launcher script at bin/pi-web.js.

Configuration via Environment Variables

The deployment strategy for pi-web relies heavily on environment variables parsed in bin/pi-web.js. These variables control networking, security, and runtime behavior before passing configuration to the Next.js server.

Variable	Purpose	Default
PI_WEB_HOSTNAME	Bind address for the server	127.0.0.1
PI_WEB_PORT	TCP port for incoming connections	30141
PI_WEB_ALLOWED_HOSTS	Whitelist for reverse-proxy hostnames	—
PI_WEB_PASSWORD	HTTP Basic Auth password (username: pi)	—
PI_WEB_NO_OPEN	Disable automatic browser launch	—

Critical security note: The built-in Basic Auth transmits credentials unencrypted. As implemented in agegr/pi-web, this authentication mechanism is intended for local development only and must not be exposed directly to the internet without TLS termination.

Starting the Server

Local Development Mode

By default, pi-web binds to localhost and automatically opens your default browser:

pi-web

This starts the Next.js development server on 127.0.0.1:30141 and launches the UI.

Custom Port and Host Binding

To make the service reachable from other machines on your network, override the bind address and port:

PI_WEB_HOSTNAME=0.0.0.0 PI_WEB_PORT=8080 pi-web

Background Service Deployment

Run pi-web as a detached process with authentication and disabled browser automation:

PI_WEB_PASSWORD='secure-random-string' PI_WEB_NO_OPEN=1 pi-web &

The PI_WEB_NO_OPEN flag prevents the CLI from attempting to launch a browser window, which is essential for headless server environments.

Production Deployment Architecture

Reverse Proxy Configuration

For production-grade deployment, front pi-web with a reverse proxy that handles TLS termination and additional authentication layers. Here is a typical NGINX configuration:

server {
    listen 443 ssl;
    server_name pi-web.example.com;

    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;

    location / {
        proxy_pass http://127.0.0.1:30141;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Set PI_WEB_ALLOWED_HOSTS to match your proxy's hostname to prevent DNS rebinding attacks:

PI_WEB_ALLOWED_HOSTS=pi-web.example.com PI_WEB_PORT=30141 pi-web

Containerization Strategy

Although the repository does not include a Dockerfile, you can containerize pi-web using any Node.js 22 base image:

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 30141
ENTRYPOINT ["node", "bin/pi-web.js"]

Build and run with environment variables passed at runtime:

docker build -t pi-web .
docker run -p 30141:30141 -e PI_WEB_HOSTNAME=0.0.0.0 -e PI_WEB_PASSWORD='secret' pi-web

Data Persistence and Session Management

Pi-Web requires no external database. The deployment strategy relies on filesystem storage in the user's home directory:

• Session files: Stored in ~/.pi/agent/sessions by default
• Model configuration: Resides in models.json within the same directory
• Custom paths: Override the base directory using PI_CODING_AGENT_DIR

Ensure the deployment environment persists the ~/.pi directory between restarts to maintain conversation history and model settings.

Summary

• Pi-Web deploys as a standard Node.js process via bin/pi-web.js, launching a Next.js development server.
• Configure networking and security using environment variables (PI_WEB_HOSTNAME, PI_WEB_PORT, PI_WEB_PASSWORD) parsed at startup.
• Default binding to 127.0.0.1:30141 ensures local-only access; use 0.0.0.0 for network exposure.
• Production deployments require a reverse proxy (NGINX, Caddy, Traefik) to provide TLS encryption and should not rely solely on the built-in Basic Auth.
• Data persists to ~/.pi/agent/sessions with no database dependencies, simplifying containerized deployments.

Frequently Asked Questions

How do I change the default port in pi-web?

Set the PI_WEB_PORT environment variable or use the --port flag when launching. For example: PI_WEB_PORT=8080 pi-web. The default value is 30141 as defined in the CLI argument parsing logic within bin/pi-web.js.

Is pi-web suitable for public internet deployment without modifications?

No. The pi-web deployment strategy assumes local or trusted network usage. The HTTP Basic Auth implementation sends credentials unencrypted, and the Next.js development server is not hardened for direct internet exposure. Always place pi-web behind a reverse proxy with TLS termination for public access.

Can I run pi-web inside Docker or Kubernetes?

Yes, though no official Dockerfile exists in the agegr/pi-web repository. Create a container using Node.js 22, copy the application code, run npm ci, and execute node bin/pi-web.js as the entrypoint. Mount a persistent volume for ~/.pi to retain session data across container restarts.

What is the difference between npx and global installation for pi-web?

npx @agegr/pi-web@latest downloads and executes the package temporarily without installing it globally, suitable for one-time use. Global installation via npm install -g permanently adds the pi-web command to your system path, referencing the local CLI wrapper at bin/pi-web.js for repeated use.

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