PizzaPi is configured primarily through environment variables. This reference lists every variable recognized by the CLI runner and the server.
These are read by the PizzaPi CLI runner process (pizzapi / daemon).
| Variable | Description | Default |
|---|
PIZZAPI_API_KEY | API key used to authenticate with the relay server. PIZZAPI_RUNNER_API_KEY and PIZZAPI_API_TOKEN are accepted as aliases. | — |
PIZZAPI_RUNNER_TOKEN | Runner session token (alternative to API key auth). | — |
PIZZAPI_RELAY_URL | WebSocket URL of the relay server the runner connects to. | ws://localhost:7492 |
PIZZAPI_RUNNER_NAME | Human-readable name for this runner (shown in the UI). | System hostname |
PIZZAPI_RUNNER_STATE_PATH | Path to the runner state JSON file. | ~/.pizzapi/runner.json |
PIZZAPI_WORKSPACE_ROOTS | Comma-separated list of workspace root directories. PIZZAPI_WORKSPACE_ROOT (single) and PIZZAPI_RUNNER_ROOTS (legacy) are also accepted. | — |
These are set automatically by the runner daemon on spawned worker sessions.
| Variable | Description | Default |
|---|
PIZZAPI_SESSION_ID | Session ID assigned to this worker. Set by the daemon on spawn. | — |
PIZZAPI_WORKER_PARENT_SESSION_ID | ID of the parent session that spawned this one. Used by the trigger system for automatic parent-child communication (AskUserQuestion, plan_mode, session completion). Do not set manually. | — |
PIZZAPI_WORKER_CWD | Working directory for the worker session. | — |
PIZZAPI_WORKER_INITIAL_PROMPT | Initial prompt to inject into the session. | — |
These control where the runner stores session attachments (images and files sent from the web UI to the agent).
| Variable | Description | Default |
|---|
PIZZAPI_SESSION_ATTACHMENTS_DIR | Override the directory where session attachments are persisted on the runner. Each session gets a subdirectory keyed by session ID. Files are stored alongside a .meta.json sidecar containing the original filename, MIME type, size, and timestamp. | ~/.pizzapi/session-attachments/ |
Attachment pipeline: When a user uploads a file via the web UI, the relay server stores it temporarily (see PIZZAPI_ATTACHMENT_DIR / PIZZAPI_ATTACHMENT_TTL_MS in the Server section). The runner’s remote extension then downloads the attachment and persists it into the session attachments directory, making it available to the agent as a local file path. Attachments live as long as the session — there is no independent TTL on the runner side.
These variables control the Agent Sandbox behavior.
| Variable | Description | Default |
|---|
PIZZAPI_SANDBOX | Override sandbox mode: enforce, audit, or off. | Config value |
PIZZAPI_NO_SANDBOX | Set to 1 to disable sandbox (shorthand for PIZZAPI_SANDBOX=off). | — |
These variables control Anthropic’s server-side web search tool. They can also be configured via providerSettings.anthropic.webSearch in config.json. See Configuration → Web Search for details.
| Variable | Description | Default |
|---|
PIZZAPI_WEB_SEARCH | Set to 1 to enable Anthropic web search. | — |
PIZZAPI_WEB_SEARCH_MAX_USES | Maximum number of web searches per request. | 5 |
PIZZAPI_WEB_SEARCH_ALLOWED_DOMAINS | Comma-separated list of domains to restrict search results to. | — |
PIZZAPI_WEB_SEARCH_BLOCKED_DOMAINS | Comma-separated list of domains to exclude from search results. | — |
These variables control which subsystems are loaded by runner-spawned worker sessions. They’re equivalent to the CLI’s --no-* flags. See Safe Mode & Startup Performance for details.
| Variable | Description | Default |
|---|
PIZZAPI_NO_MCP | Set to 1 to skip MCP server connections. | — |
PIZZAPI_NO_PLUGINS | Set to 1 to skip Claude Code plugin loading. | — |
PIZZAPI_NO_HOOKS | Set to 1 to skip hook execution. | — |
PIZZAPI_NO_RELAY | Set to 1 to skip relay server connection. | — |
| Variable | Description | Default |
|---|
PORT | HTTP / WebSocket listen port. | 7492 |
PIZZAPI_REDIS_URL | Redis connection URL. | redis://127.0.0.1:6379 |
PIZZAPI_BASE_URL | Public base URL of the PizzaPi server (used for share links, CORS origins, etc.). | http://localhost:5173 |
PIZZAPI_EXTRA_ORIGINS | Comma-separated list of additional trusted origins for CORS and WebSocket auth. Use this to allow access from custom hostnames such as a Tailscale URL without hardcoding them. e.g. https://myhost.ts.net,http://myhost.ts.net:5173. These are also used to populate Vite’s allowedHosts in development. | — |
PIZZAPI_UI_DIR | Absolute path to the directory containing the built UI static assets. When unset the server does not serve a UI. | — |
| Variable | Description | Default |
|---|
AUTH_DB_PATH | Path to the SQLite database used by better-auth. | auth.db |
BETTER_AUTH_SECRET | Secret key used by better-auth for session signing. Must be set in production. | — |
BETTER_AUTH_BASE_URL | Base URL that better-auth uses for its own endpoints. | http://localhost:<PORT> |
| Variable | Description | Default |
|---|
PIZZAPI_API_KEY_RATE_LIMIT_ENABLED | Enable rate limiting on API-key-authenticated requests (true / false). | false |
PIZZAPI_API_KEY_RATE_LIMIT_MAX_REQUESTS | Maximum number of requests allowed per time window. | 10 |
PIZZAPI_API_KEY_RATE_LIMIT_TIME_WINDOW_MS | Length of the rate-limit sliding window in milliseconds. | 86400000 (24 h) |
PIZZAPI_TRUST_PROXY | Enable reverse proxy header handling for rate limiting and client IP detection. Set to true when the server is behind a non-loopback reverse proxy (e.g. Docker bridge network, Caddy, nginx). Loopback proxies (127.0.0.1, ::1) are auto-detected without this setting. Set to false to disable proxy detection entirely. See Self-Hosting for details. | unset (auto-detect loopback only) |
PIZZAPI_PROXY_DEPTH | Number of intermediate proxy hops between the server and the original client, for X-Forwarded-For parsing. 0 (default) = single proxy — use the right-most XFF entry. 1 = two proxies (e.g. CDN + local reverse proxy) — use the second-from-right entry. N = N+1 total proxies — use the entry N positions from the right. Only meaningful when proxy trust is enabled. See Self-Hosting. | 0 |
| Variable | Description | Default |
|---|
PIZZAPI_ATTACHMENT_DIR | Directory where uploaded attachments are stored. | .pizzapi/uploads (relative to cwd) |
PIZZAPI_ATTACHMENT_MAX_FILE_SIZE_BYTES | Maximum allowed upload file size in bytes. | 20971520 (20 MB) |
PIZZAPI_ATTACHMENT_TTL_MS | Time-to-live for stored attachments in milliseconds. Expired files are cleaned up automatically. | 900000 (15 min) |
| Variable | Description | Default |
|---|
PIZZAPI_RELAY_EVENT_BUFFER_SIZE | Maximum number of events kept in the per-session Redis ring buffer. | 1000 |
PIZZAPI_RELAY_EVENT_TTL_MS | TTL for relay events stored in Redis, in milliseconds. | 86400000 (24 h) |
PIZZAPI_EPHEMERAL_TTL_MS | TTL for ephemeral in-memory session data in milliseconds. | 600000 (10 min) |
PIZZAPI_EPHEMERAL_SWEEP_MS | Interval between ephemeral data sweep/cleanup runs in milliseconds. | 60000 (1 min) |
| Variable | Description | Default |
|---|
VAPID_PUBLIC_KEY | VAPID public key for Web Push. Generate a key pair with bunx web-push generate-vapid-keys. | — |
VAPID_PRIVATE_KEY | VAPID private key for Web Push. | — |
VAPID_SUBJECT | VAPID subject, typically a mailto: URI identifying the server operator. | mailto:admin@pizzapi.local |
