Installation

Requirements

Requirement	Minimum
Node.js or Bun	Node 18+ or Bun 1.x
OS	Linux, macOS, Windows
For self-hosting	Docker + Docker Compose

---

Install the CLI

npm (recommended)

npm install -g @pizzapi/pizza
pizzapi --version

Bun

bun install -g @pizzapi/pizza
pizzapi --version

npx (no install)

# Run without installing — always uses the latest version
npx @pizzapi/pizza

Pre-built binary

Download a binary for your platform from the GitHub Releases page and put it on your PATH.

Platform	Architectures
Linux	x64, arm64
macOS	x64, arm64 (Apple Silicon)
Windows	x64

# Linux / macOS example
curl -L https://github.com/Pizzaface/PizzaPi/releases/latest/download/pizzapi-linux-x64 \
  -o pizzapi
chmod +x pizzapi
sudo mv pizzapi /usr/local/bin/
pizzapi --version

---

First-Run Setup

Connect the CLI to your relay server:

pizzapi setup

You’ll be prompted for:

Prompt	Default	Description
Relay server URL	http://localhost:7492	HTTP(S) address of the relay server
Your name	—	Optional; only used when creating a new account
Email	—	Account email
Password	—	Account password

On success the CLI saves your API key to ~/.pizzapi/config.json and prints the derived WebSocket URL used for streaming.

Note

Already have an account? Leave Your name blank and just provide email + password.

---

Verify the Installation

# Show the installed version
pizzapi --version

# List available AI models
pizzapi models

# Show API usage
pizzapi usage

---

Updating

npm update -g @pizzapi/pizza
# — or —
bun update -g @pizzapi/pizza

---

Files & Directories Created by PizzaPi

PizzaPi stores all its data under ~/.pizzapi/. Here’s what each file is for:

Path	Created by	Purpose
~/.pizzapi/config.json	pizzapi setup / manual	CLI config: API key, relay URL, skills, hooks
~/.pizzapi/auth.json	/login inside a session	AI provider credentials (OAuth tokens, API keys)
~/.pizzapi/models.json	first session start	Cached model registry
~/.pizzapi/runner.json	pizzapi runner (first start)	Runner identity, name, and PID tracking (auto-generated)
~/.pizzapi/usage-cache.json	pizzapi runner	Shared provider quota cache (written by daemon, read by workers)
~/.pizzapi/logs/	macOS LaunchAgent setup	Log files for runner stdout/stderr
~/.pizzapi/web/config.json	pizzapi web	Web hub settings (port, VAPID keys, origins)
~/.pizzapi/web/compose.yml	pizzapi web	Auto-generated Docker Compose file (regenerated each run)
~/.pizzapi/web/data/	pizzapi web	Persistent SQLite database for user accounts
~/.pizzapi/web/repo/	pizzapi web	Cloned PizzaPi source repo
~/.pizzapi/skills/	manual	Global personal skills
~/.pizzapi/usage.db	first session	SQLite database tracking token consumption, costs, and session analytics. Safe to delete (loses analytics history).
~/.pizzapi/session-list-cache.json	pizzapi runner	Cache of session metadata with mtime-based invalidation. Safe to delete (rebuilds automatically on next session list).

Project-local config (.pizzapi/config.json) is stored in each project’s directory and is not part of the global ~/.pizzapi/ tree.

---

Upgrading from pi

If you previously used the raw pi coding agent, PizzaPi automatically migrates your existing data on first startup. No manual steps are required.

The migration runs in two phases:

1. Phase 1 — ~/.pi/agent/ → ~/.pizzapi/: Copies sessions, auth, and other data from a legacy pi install into the PizzaPi config directory.
2. Phase 2 — ~/.pizzapi/agent/ → ~/.pizzapi/: Flattens an older PizzaPi layout where data was nested under ~/.pizzapi/agent/ (caused by an earlier upstream getAgentDir() path). Files are merged into the flat ~/.pizzapi/ structure.

Both phases are idempotent — they skip files that already exist at the destination and write a .migrated marker so they don’t re-scan on subsequent startups. It’s safe to re-run (e.g., if you reinstall).

Tip

If something looks wrong after migration, you can safely delete ~/.pizzapi/agent/.migrated and restart PizzaPi to re-run Phase 2. Phase 1 re-runs automatically if ~/.pizzapi/sessions/ doesn’t exist yet.

---

Resetting Configuration

Re-run setup (switch relay or update credentials)

To switch to a different relay server or update your credentials at any time:

pizzapi setup

This overwrites the apiKey in ~/.pizzapi/config.json and prints the WebSocket URL to add to your config. After setup, manually add the relay URL if it’s not the default:

~/.pizzapi/config.json

{
  "apiKey": "pk_live_...",
  "relayUrl": "wss://your-relay.example.com"
}

Disconnect from the relay (relay-free mode)

To stop connecting to a relay without uninstalling:

# Add to ~/.pizzapi/config.json:
# "relayUrl": "off"

# — or — use an environment variable:
PIZZAPI_RELAY_URL=off pizzapi

See the Standalone Mode guide for details.

Reset AI provider credentials

To log out of all AI providers and start fresh with /login:

rm ~/.pizzapi/auth.json
rm ~/.pizzapi/models.json

Next time you start pizzapi, you’ll see “No models available” and can run /login to re-authenticate.

Reset runner identity

The runner identity is auto-generated on first start. To assign a new identity (useful if you’ve cloned a machine or want a fresh runner registration):

# Stop the runner first
pizzapi runner stop

# Remove the identity file
rm ~/.pizzapi/runner.json

# Restart — a new ID is generated automatically
pizzapi runner

Reset the web hub

To wipe the relay server’s database and start fresh (all user accounts and session metadata will be lost):

# Stop the web hub first
pizzapi web stop

# Remove only the database (preserves config, VAPID keys, etc.)
rm -rf ~/.pizzapi/web/data/

# Restart — a fresh database is created on next start
pizzapi web

To also reset the web hub configuration (port, VAPID keys, origins):

pizzapi web stop
rm -rf ~/.pizzapi/web/
pizzapi web   # all defaults restored; new VAPID keys generated

Caution

Deleting ~/.pizzapi/web/data/ removes all user accounts. Everyone will need to re-register. Push notification subscriptions are also lost (VAPID keys are in web/config.json).

---

Uninstalling

1. Stop any running processes

# Stop the runner daemon (if running)
pizzapi runner stop

# Stop the web hub (if running)
pizzapi web stop

2. Remove the CLI

npm

npm uninstall -g @pizzapi/pizza

Bun

bun remove -g @pizzapi/pizza

Pre-built binary

# Remove the binary from wherever you placed it
which pizzapi   # find it
sudo rm $(which pizzapi)

3. Remove all PizzaPi data

# Removes config, credentials, sessions, web hub data — everything
rm -rf ~/.pizzapi

Or remove selectively:

rm ~/.pizzapi/config.json      # relay credentials only
rm ~/.pizzapi/auth.json        # AI provider credentials only
rm -rf ~/.pizzapi/web/         # web hub only

4. Remove macOS LaunchAgent (if installed)

If you set up the runner as a macOS LaunchAgent:

launchctl unload ~/Library/LaunchAgents/com.pizzapi.runner.plist
rm ~/Library/LaunchAgents/com.pizzapi.runner.plist

5. Remove systemd service (Linux, if installed)

sudo systemctl stop pizzapi-runner
sudo systemctl disable pizzapi-runner
sudo rm /etc/systemd/system/pizzapi-runner.service
sudo systemctl daemon-reload