Getting Started

PizzaPi has two parts:

Part	What it does
CLI (`pizzapi`)	Wraps `pi` on your dev machine and streams session events to the relay
Relay Server	Buffers and broadcasts events; hosts the web UI

You always need the CLI. The relay can be hosted by someone else (quickest) or run yourself with Docker.

Prerequisites

Before you start, make sure you have:

Node.js 18+ (or Bun) installed
An AI provider API key — PizzaPi uses the pi coding agent under the hood, which needs an API key from at least one provider (Anthropic, OpenAI, Google, etc.). Alternatively, a Claude Pro/Max subscription works via the Claude Code OAuth flow.
A relay server URL — either a hosted relay someone has shared with you, or you’ll self-host one below.
Docker + Docker Compose — only if you self-host with pizzapi web

Option A — Use a Hosted Relay (Quickest)

Install the CLI
Terminal window
npx @pizzapi/pizza
Terminal window
npm install -g @pizzapi/pizza pizzapi
Terminal window
bun install -g @pizzapi/pizza pizzapi

Run first-time setup

The first time you run pizzapi without a saved config it launches the setup wizard automatically:

┌─────────────────────────────────────────┐
│        PizzaPi — first-run setup        │
└─────────────────────────────────────────┘

Relay server URL [http://localhost:7492]: https://relay.example.com
Your name (leave blank if account exists): Jordan
Email: you@example.com
Password: ••••••••

Connecting to relay server… ✓
✓ API key saved to ~/.pizzapi/config.json
✓ Relay: wss://relay.example.com

You can re-run setup at any time:

pizzapi setup

Start a session
Terminal window
```
pizzapi
```
Open the relay’s web UI in your browser — your session is streaming live!

Option B — Self-Host the Relay

Want complete control? Run the relay + web UI yourself.

The Easy Way: `pizza web`

If you have Docker installed, one command does everything:

pizzapi web

This clones the repo, builds the containers, and starts the relay at http://localhost:7492. See the Self-Hosting guide for details.

Manual Setup

Clone the repository

git clone https://github.com/Pizzaface/PizzaPi.git
cd PizzaPi

Start the server stack
Terminal window
```
docker compose -f docker/compose.yml up -d
```
Service Port Description
redis 6379 Session event buffer
server 7492 Relay API + Web UI

The web UI is now live at http://localhost:7492.
Open the web UI and sign in
- Open http://localhost:7492 in your browser
- Sign in or create an account from the Sign up tab

Service	Port	Description
`redis`	6379	Session event buffer
`server`	7492	Relay API + Web UI

Install the CLI & connect

npm install -g @pizzapi/pizza
pizzapi setup
# Relay server URL: http://localhost:7492
# Email: you@example.com
# Password: your-password

Start your first session
Terminal window
```
cd /your/project
pizzapi
```
Then open http://localhost:7492 to watch it live.

What You’ll See

Once your session is running, open the web UI. Here’s what to expect:

Live Token Stream

The agent’s response streams in token-by-token — just like watching it type. Markdown is rendered inline with syntax highlighting.

Tool Calls & Results

Every file read, bash command, and edit appears as a collapsible tool call with full input/output. You can see exactly what the agent is doing.

File Diffs

File edits show as syntax-highlighted diffs so you can review changes at a glance before the agent moves on.

Todo List

If the agent creates a task plan, it appears as a live-updating todo list in the sidebar — items move from pending → in progress → done.

You can type messages in the chat input at the bottom to ask questions, give corrections, or steer the agent — all without touching the terminal.

Verification Checklist

Run these checks after setup to make sure everything is working:

Check	Command / Action	Expected
CLI works	`pizzapi --version`	Prints PizzaPi CLI version
Relay configured	`pizzapi setup`	Shows saved API key + relay URL
Web hub healthy (if self-hosted)	`pizzapi web status`	Docker services listed
Session visible in UI	Start `pizzapi` session	Session appears in browser
Models available	`pizzapi models`	At least one model listed (after `/login`)

Troubleshooting

Problem	Fix
`pizzapi web` fails immediately	Make sure Docker Desktop/Engine is running and `docker compose version` works.
Setup says `Could not register with the relay server`	Verify URL, email/password, and that relay is reachable in browser.
Setup asks for a name but account already exists	Leave Your name blank for existing accounts.
Session not visible in web UI	Re-run `pizzapi setup`, then start a fresh session.
No model available in session	Run `/login`, then `/model` inside the session.

Escape Hatches

Skip relay setup entirely — If you run pizzapi without any saved config, the setup wizard asks “Skip setup and continue without relay?” Type y to start with no relay for this run only. To skip permanently, see Standalone Mode.

Re-run setup — Run pizzapi setup at any time to re-configure or switch relay servers.

Full reset — To wipe all PizzaPi state and start fresh:

rm -rf ~/.pizzapi
pizzapi setup

See the Installation guide for partial reset options.

What’s Next?

Installation Details

Platform-specific notes, binary downloads, and alternative install methods.

Installation guide →

CLI Reference

All pizzapi commands and flags — setup, session management, config overrides.

CLI reference →

Configuration

Customize config files, environment variables, model defaults, and relay settings.

Configuration →

Runner Daemon

Run a headless daemon that lets you spawn and manage agent sessions entirely from the web UI.

Runner daemon →

Self-Hosting Guide

Production Docker setup with HTTPS, custom domains, backups, and scaling.

Self-hosting →