Skip to content
PizzaPi

Your First Remote Session

This tutorial walks you through setting up the PizzaPi relay server so you can stream agent sessions to a browser — and interact with them remotely from any device.

Prerequisites

Section titled “Prerequisites”

Before you start, make sure you have:

  • PizzaPi CLI installed — see Installation
  • Docker and Docker Compose — needed to run the relay server
  • git — pizzapi web clones the PizzaPi repo on first run
  • An AI provider API key — Anthropic, OpenAI, Google, Ollama Cloud, or a Claude Pro/Max subscription

Set Up the Relay

Section titled “Set Up the Relay”

  1. Start the relay server

    Section titled “Start the relay server”

    One command builds and starts everything:

    Terminal window
    pizzapi web

    Wait for the success message:

    ✅ PizzaPi web is running at http://localhost:7492

    This spins up a Docker Compose stack with Redis (relay state / pub-sub), the PizzaPi server (relay API + web UI), a UI sidecar for web assets, and an optional ntfy service for native Android push (configured separately in Mobile Push).

    The first run clones the repo and builds the Docker images, which usually takes a few minutes. Subsequent starts are much faster.

  2. Create your account

    Section titled “Create your account”

    Open http://localhost:7492 in your browser. You’ll see the PizzaPi web UI.

    Switch to the Sign up tab to create an account. This is a local account on your relay — no external service involved.

  3. Connect the CLI

    Section titled “Connect the CLI”

    In your terminal, run:

    Terminal window
    pizzapi setup

    The setup wizard will prompt for:

    • Relay server URL — enter http://localhost:7492
    • Your name — leave blank if you already signed up in the browser
    • Email and password — use the account you just created
    ┌───────────────────────────────────────────┐
    │     🍕 PizzaPi — first-run setup     │
    └───────────────────────────────────────────┘
    

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

    Connecting to relay server… ✓
    ✓ API key saved to ~/.pizzapi/config.json
    ✓ Relay: ws://localhost:7492
    ✓ Theme set to pizzapi-dark

  4. Start a session

    Section titled “Start a session”

    Navigate to any project directory and start PizzaPi:

    Terminal window
    cd /path/to/your/project
    pizzapi

  5. Watch it in the browser

    Section titled “Watch it in the browser”

    Go back to http://localhost:7492. Your session appears in the session list with a live status indicator.

    Click on it to see:

    • Live token stream — the agent’s response appearing in real-time
    • Tool calls — every file read, bash command, and edit as collapsible cards
    • File diffs — syntax-highlighted diffs for code changes
    • Chat input — type messages to steer the agent from the browser

What’s Next?

Section titled “What’s Next?”

Now that you have a working relay, here are the natural next steps:

  • Runner Daemon — Run sessions headlessly without a terminal. Spawn and manage agent sessions entirely from the web UI.
  • Self-Hosting — Deploy the relay on a remote server with Docker Compose, custom domains, and production settings.
  • Tailscale HTTPS — Expose your relay over a secure Tailscale tunnel with automatic TLS — access your sessions from anywhere.
  • Configuration — Customize model defaults, MCP servers, hooks, and more.