# Pi-Web Deployment Strategy: Local Development to Production Setup

> Learn the pi-web deployment strategy. Deploy your local Node.js Next.js app to production using a CLI wrapper and reverse proxy setup. Get started today.

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

---

**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`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js)** entry point defined in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json).

### NPX One-Liner

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

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

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

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

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

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

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

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

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

```bash
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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js)** for repeated use.