PizzaPi is configured primarily through environment variables. This reference lists the common operator-facing variables recognized by the CLI runner and the server. Internal worker-session variables set automatically by the daemon are excluded unless they are useful for advanced configuration.
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). | — |
| Variable | Description | Default |
|---|
PIZZAPI_BASH_BACKGROUND_SECONDS | Seconds a bash command streams output in the foreground before it auto-backgrounds. 0 backgrounds immediately. Overrides bash.backgroundAfterSeconds in config.json. | 15 |
These variables control provider web search tools. They can also be configured via providerSettings.<provider>.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 Anthropic search results. | — |
PIZZAPI_OLLAMA_WEB_SEARCH | Set to 1 to register Ollama Cloud web_search and web_fetch tools. Uses stored ollama-cloud credentials or OLLAMA_API_KEY. | — |
PIZZAPI_OLLAMA_WEB_SEARCH_MAX_RESULTS | Default number of Ollama search results per request (1–10). | 5 |
These variables are read by the underlying pi model providers. Set them in the same environment as pizzapi or the runner daemon.
| Variable | Description | Default |
|---|
OLLAMA_API_KEY | API key for the built-in Ollama Cloud provider (https://ollama.com/v1). Required to use Ollama Cloud models without entering the key manually through /login. | — |
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://localhost: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. Expands to http://localhost:7492 when PORT is unset. | http://localhost:<PORT> |
PIZZAPI_DISABLE_SIGNUP_AFTER_FIRST_USER | Set to false to allow sign-ups after the first user is registered. | true |
| 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_TRUSTED_PROXY_CIDRS | Comma-separated list of CIDR ranges (IPv4 or IPv6) whose peers are trusted to set X-Forwarded-For. Required for cloud load balancers (public peer IPs) and any deployment that shares its private network with untrusted hosts (multi-tenant VPC, shared LAN, multi-app Docker bridge). Bare IPs default to /32 (IPv4) or /128 (IPv6). Loopback is always trusted in addition to the allowlist. Example: 203.0.113.0/24, 10.0.0.0/8. See Self-Hosting. | unset |
PIZZAPI_TRUST_PROXY | Convenience opt-in for trusting X-Forwarded-For from any loopback or RFC1918/ULA private peer. Suitable for single-tenant Docker Compose where every container on the bridge is trusted. Do not use on shared LANs/VPCs — use PIZZAPI_TRUSTED_PROXY_CIDRS instead. false disables proxy trust entirely (kill switch, overrides everything). PIZZAPI_TRUSTED_PROXY_CIDRS takes precedence over true. See Self-Hosting. | 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 |
PIZZAPI_TRUST_MOBILE_ORIGINS | Set to false to disable the default trust of Capacitor mobile origins (capacitor://localhost, https://localhost). | true |
| Variable | Description | Default |
|---|
PIZZAPI_TUNNEL_DOMAIN | Dedicated origin for tunnels, as [scheme://]host[:port] (e.g. t.localhost:7492, https://t.example.com). Each tunnel is served at an opaque subdomain <label>.<domain> with the path proxied verbatim — no prefix, no content rewriting, SPA client-side routing works. Requires wildcard DNS for the domain (*.localhost resolves in browsers automatically). Scheme defaults to http for *.localhost, https otherwise. Unset → path-prefix tunnels (/api/tunnel/…). See Tunnels. | unset |
PIZZAPI_CADDY | pizza web only. Adds a Caddy service to the generated compose file that terminates wildcard TLS for *.<PIZZAPI_TUNNEL_DOMAIN> and proxies to the relay, writing ~/.pizzapi/web/Caddyfile. Listen port comes from PIZZAPI_TUNNEL_DOMAIN (default 443). Persisted to the web config. Ignored for *.localhost domains, which need no TLS. | false |
PIZZAPI_CADDY_DNS_PROVIDER | pizza web only. caddy-dns module name (e.g. cloudflare) used to solve the DNS-01 challenge for a publicly trusted wildcard certificate. Persisted to the web config, so subsequent pizza web --build runs keep DNS-01; set it empty to clear. Unset → Caddy’s internal CA, which requires no DNS credentials but must be trusted once per device — note an untrusted cert makes the tunnel fail silently inside the web UI’s iframe, since browsers never offer a click-through interstitial in a subframe. | unset |
PIZZAPI_CADDY_DNS_TOKEN | pizza web only. API token for PIZZAPI_CADDY_DNS_PROVIDER, passed to the container and referenced from the Caddyfile as {env.PIZZAPI_CADDY_DNS_TOKEN} (never written into the file). Required whenever a DNS provider is set. Persisted to ~/.pizzapi/web/config.json, which is written mode 0600. | unset |
PIZZAPI_CADDY_IMAGE | pizza web only. Overrides the Caddy image. DNS-01 needs a build containing the provider module: cloudflare resolves to a known prebuilt image, any other provider requires an xcaddy build set here. Persisted to the web config. | caddy:2-alpine, or the prebuilt cloudflare image |
| 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. | 31457280 (30 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_RELAY_SNAPSHOT_SCAN_CHUNK_SIZE | Redis SCAN chunk size for relay snapshot iteration tuning. | 1000 |
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 |
Self-hosted ntfy delivers background push to the Android
Capacitor app without Google/FCM. All three variables are optional — if
PIZZAPI_NTFY_URL is unset, the ntfy branch is a silent no-op and only Web
Push runs. See Mobile push for the full
setup (compose service, reverse proxy, publish-user provisioning, security).
| Variable | Description | Default |
|---|
PIZZAPI_NTFY_URL | Internal URL the server uses to publish to ntfy (e.g. http://ntfy on the Docker network). | — |
PIZZAPI_NTFY_PUBLIC_URL | Public URL devices use to subscribe (e.g. https://push.example.com). | — |
PIZZAPI_NTFY_PUBLISH_TOKEN | ntfy access token for the server’s publish user (provisioned via ntfy user + ntfy token). | — |
