Install & Run Your First Session

PizzaPi runs the pi coding agent on your computer. The CLI is available as pizzapi and pizza.

Requirements

• Node.js 18+ or Bun 1.x (the package is distributed through npm).
• An AI provider account, subscription, or API key. See Providers & Models.
• Docker is only needed if you use pizzapi local to start a local relay, or self-host the relay separately.

Install

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

Or run without installing:

npx @pizzapi/pizza --help

Where data is stored

PizzaPi stores global settings and provider credentials under ~/.pizzapi/. The relay API key and relay URL are in ~/.pizzapi/config.json; provider auth is in ~/.pizzapi/auth.json; sessions and logs are also kept under this directory. Project-specific configuration lives in .pizzapi/ in the project. Back up files before resetting or uninstalling.

To remove provider credentials, delete ~/.pizzapi/auth.json. To remove all PizzaPi local data, stop its processes and remove ~/.pizzapi/.

Run your first session

Choose one of these paths. A relay is needed to view sessions in a browser; the terminal-only path works without one.

Path 1: Local relay (Docker)

With Docker running, start the local relay and runner:

pizzapi local

On first use, the command starts the web hub on port 7492, opens setup if no local credentials exist, then runs the agent in the foreground. Sign up at http://localhost:7492 if needed. Setup stores apiKey and relayUrl in ~/.pizzapi/config.json. The relay remains running after Ctrl+C; stop it with pizzapi web stop.

Use pizzapi local --port 8080 for another port or --no-browser to suppress browser launch. It reuses a healthy local relay. If your saved credentials point to a remote relay, it refuses to switch automatically; run pizzapi setup first and choose the local relay URL. See CLI reference.

Path 2: Existing relay

If you already have a PizzaPi relay, connect the CLI to it:

pizzapi setup

Enter the relay address and your relay account credentials, or run pizzapi setup --scan and approve the device from an authenticated browser. Setup persists the API key and normalized relay URL to ~/.pizzapi/config.json. Then open a project directory and start:

cd /path/to/project
pizzapi

Open the relay’s web UI in a browser to see the session stream.

Path 3: Terminal only

To use the CLI without connecting to a relay, run:

PIZZAPI_RELAY_URL=off pizzapi

This disables relay connection for that invocation; pizzapi --no-relay is the equivalent flag form. The agent and local session history still work, but browser streaming and remote spawning do not. For persistent relay-free use, set "relayUrl": "off" in ~/.pizzapi/config.json. Use pizzapi runner only when you want headless sessions spawned from the web UI.

Authenticate and select a model

Relay sign-in and AI provider sign-in are separate. At the PizzaPi prompt, run /login and complete an available provider OAuth flow, or set the provider’s API key in the environment before starting (for example ANTHROPIC_API_KEY). Then run /model and select a model shown as available. See Providers & Models for credential priority, supported providers, and custom models.

Verify a real response

From the session prompt, send a harmless request such as:

Reply with exactly: PizzaPi is connected.

A successful response in the terminal confirms provider access. For relay paths, also confirm the session and response appear in the browser. If no model is available, complete /login or provide an API key, then reopen /model.

Stop

Press Ctrl+C to stop the foreground agent/runner. With pizzapi local, the relay stays up; stop it separately with:

pizzapi web stop

With the standalone pizzapi runner daemon, use pizzapi runner stop to stop it. See Runner Daemon for managed/background operation.

Troubleshooting

If the runner repeatedly crashes on Windows, try running it inside WSL2, which uses the Linux runtime. Capture the runner logs and check the current release notes before switching versions; older reports about specific crash addresses and version ranges may no longer apply.