Configuration

PizzaPi loads configuration from two JSON files merged together — project-local settings win over global ones:

File	Scope
~/.pizzapi/config.json	Global — applies to all projects
.pizzapi/config.json	Project-local — overrides global for this project

A documented subset of settings can also be overridden with environment variables (see the list below). Environment variables take precedence for the current process but do not rewrite JSON files.

Dedicated guides

For in-depth setup of specific features, see:

• MCP Servers — connecting external tool servers
• Hooks — lifecycle scripts that observe or block agent actions
• Skills — extending the agent with domain knowledge
• Agent Definitions & Subagents — creating reusable specialized agents

---

Config File Reference

// ~/.pizzapi/config.json  (or  .pizzapi/config.json in your project)
{
  // API key issued by the relay server during `pizzapi setup`
  "apiKey": "pk_live_abc123...",

  // WebSocket URL of the relay server.
  // Set to "off" to disable the relay entirely (no setup wizard, no streaming).
  // Default: ws://localhost:7492 (the pizzapi web default port)
  "relayUrl": "wss://relay.example.com",

  // Replace the default system prompt entirely
  "systemPrompt": "You are a helpful coding assistant.",

  // Append to the default system prompt without replacing it
  "appendSystemPrompt": "Always write tests for new code.",

  // Send AGENTS.md and rules/*.md files automatically as context. Set false
  // to omit them unless the agent explicitly reads them with tools. Default: true.
  "sendAgentsMd": true,

  // Override the agent config directory (skills, extensions, etc.)
  // Default: ~/.pizzapi
  "agentDir": "~/.pizzapi",

  // Additional skill paths — merged on top of the default locations:
  //   ~/.pizzapi/skills/  and  <cwd>/.pizzapi/skills/
  "skills": [
    "~/my-custom-skills",
    "/absolute/path/to/skills"
  ],

  // Trust gate: allow project-local hooks (.pizzapi/config.json) to run.
  // Must be in the GLOBAL config (project configs cannot self-authorize).
  "allowProjectHooks": false,

  // Trust gate: allow project-local MCP servers to load.
  // Project MCP servers are excluded by default; set this to true to enable loading.
  // Must be in the GLOBAL config.
  "allowProjectMcp": false,

  // Project-local Claude Code plugins that have been explicitly trusted.
  // Each entry is the absolute path to the plugin root directory.
  // Managed via `pizza plugins trust <path>` / `pizza plugins untrust <path>`.
  // Must be in the GLOBAL config (project configs cannot self-authorize).
  "trustedPlugins": [
    "/home/user/projects/my-app/.pizzapi/plugins/my-linter"
  ],

  // Timeout (ms) for each MCP server's tools/list call (default: 30000).
  // Set to 0 to disable.
  "mcpTimeout": 30000,

  // Show warnings when startup is slow (default: true).
  // Set to false to suppress slow-startup notifications.
  "slowStartupWarning": true,

  // Runner service IDs to skip loading.
  // Built-in services: "terminal", "file-explorer", "git", "memory", "process", "time", "tunnel".
  // Package services use the id declared under pi.pizzapi.services.
  "disabledRunnerServices": ["git", "time"],

  // OS-level sandbox configuration.
  // mode: "none" | "basic" (default) | "full"
  // All other fields are srt-native overrides merged on top of the preset.
  "sandbox": {
    "mode": "full",
    "network": {
      "allowedDomains": ["*.github.com", "api.anthropic.com"]
    },
    "filesystem": {
      "denyRead": ["~/.kube"],
      "allowWrite": [".", "/tmp"],
      "denyWrite": [".env.production"]
    }
  },

  // `/goal` evaluator configuration. Each time the agent finishes a run, the
  // evaluator appends a judge question to the session's own context and asks
  // the session's model — so the conversation is served from the provider's
  // prompt cache. Cadence is measured in completed agent runs (one user prompt
  // through to control returning to the user), not LLM round-trips.
  // `evaluatorModel` is an advanced escape hatch: pinning a model opts out of
  // cache reuse and sends a standalone transcript instead.
  "goal": {
    "evaluatorMaxTokens": 512,
    "evaluateEveryNTurns": 1,
    "minTurnsBeforeEvaluate": 1
  },

  // Subagent execution limits. Only these two subagent keys are supported;
  // bash backgrounding and tool-search persistence are configured separately.
  "subagent": {
    "maxParallelTasks": 8,
    "maxConcurrency": 4
  },

  // Dynamic MCP tool discovery — defers MCP tools when their descriptions
  // exceed a character threshold, letting agents load them on demand.
  // tokenThreshold belongs here, not under goal.
  "toolSearch": {
    "enabled": false,
    "tokenThreshold": 10000,
    "maxResults": 5,
    "keepLoadedTools": true
  },

  // Global trust grants for daemon services declared by installed pi.pizzapi
  // overlay packages. Managed by `pizza install --allow-daemon-services` and
  // `pizza config grant|revoke`; project config cannot self-grant services.
  "overlayServiceGrants": [
    { "package": "npm:@acme/pi-github", "services": ["github"] }
  ]
}

---

All Options

Key	Type	Default	Description
apiKey	string	—	API key for authenticating with the relay server. Issued during pizzapi setup.
relayUrl	string	ws://localhost:7492	WebSocket URL of the relay server. Set to "off" to disable relay entirely.
systemPrompt	string	(pi default)	Fully replace the default system prompt
appendSystemPrompt	string	—	Append to the default system prompt
builtinSystemPrompt	boolean	true	Set to false to skip PizzaPi’s built-in system prompt additions (subagents, plan mode, sigils, tunnels, PizzaPi config guidance) for a vanilla pi prompt
sendAgentsMd	boolean	true	Set to false to omit AGENTS.md and rules/*.md files from automatic prompt context. The agent can still read them explicitly with tools.
agentDir	string	~/.pizzapi	Agent config directory (skills, extensions, etc.)
skills	string[]	[]	Additional skill directories. Supports ~ expansion.
hooks	object	—	Lifecycle hook scripts. See Hooks.
envOverrides	Record<string, string>	—	Environment variables to inject into runner worker sessions. Keys that relax a protection (PIZZAPI_SANDBOX, PIZZAPI_NO_SANDBOX, PIZZAPI_SANDBOX_ALLOW_UNSANDBOXED, PIZZAPI_SANDBOX_ACTIVE, PIZZAPI_SANDBOX_MODE, PIZZAPI_PLAN_MODE_ALLOWED_TOOLS, PIZZAPI_BASH_PASSTHROUGH_ENV, PIZZAPI_ALLOW_PROJECT_HOOKS, PIZZAPI_ALLOW_PROJECT_MCP) are honoured only from the global ~/.pizzapi/config.json; a project config cannot set or change them.
allowProjectHooks	boolean	false	Trust gate: allow project-local hooks to run. Global config only.
allowProjectMcp	boolean	false	Allows project-local MCP server definitions to load; otherwise they are excluded. Global config only.
trustedPlugins	string[]	[]	Trusted Claude Code plugin paths. Global config only. Managed via pizza plugins trust.
disabledMcpServers	string[]	[]	MCP server names to skip during initialization. Both global and project lists are merged (union).
oauthClientName	string	"PizzaPi"	Global default client_name for MCP OAuth registration. Can also be set per-server in mcpServers entries. Per-server values take precedence. See Client Name Override.
oauthClientId	string	—	Global default pre-registered OAuth client_id for MCP servers. Per-server values take precedence.
oauthClientSecret	string	—	Global default pre-registered OAuth client_secret for MCP servers. Per-server values take precedence.
oauthCallbackPort	number	0	Global default local callback port for MCP OAuth redirect URI. A single OAuth server honors this port; multiple OAuth servers without per-server ports use OS-assigned ephemeral ports to avoid collisions. 0 means OS-assigned ephemeral port. Per-server values take precedence.
mcpTimeout	number	30000	Timeout (ms) for each MCP server’s tools/list call during startup. Set to 0 to disable.
toolSearch	object	—	Dynamic MCP tool discovery config. See MCP tool search.
toolSearch.tokenThreshold	number	10000	Character threshold for total MCP tool definitions before tools are deferred. This is not a /goal setting.
toolSearch.maxResults	number	5	Maximum tools returned by each search_tools call.
toolSearch.keepLoadedTools	boolean	true	Keep tools loaded after on-demand discovery. Set false to deactivate discovered tools after each turn.
bash.backgroundAfterSeconds	number	15	Seconds a bash command streams output in the foreground before it auto-backgrounds. 0 = background immediately. See Bash auto-backgrounding.
sandbox	object	(see below)	OS-level sandbox config. See Agent Sandbox.
sandbox.mode	string	"basic"	Preset: "none", "basic", or "full".
sandbox.network.allowedDomains	string[]	[] (full) / unset (basic)	Domains the agent may reach. Required for outbound access in full mode.
sandbox.network.deniedDomains	string[]	[]	Domains explicitly blocked.
sandbox.filesystem.denyRead	string[]	merged with preset	Additional paths blocked from reading.
sandbox.filesystem.allowWrite	string[]	[".", "/tmp"]	Paths allowed for writing (replaces preset when set).
sandbox.filesystem.denyWrite	string[]	merged with preset	Additional paths blocked from writing.
sandbox.network.allowLocalBinding	boolean	srt default	Pass-through sandbox-runtime network override.
sandbox.network.allowUnixSockets	string[]	srt default	Pass-through sandbox-runtime Unix socket allowlist.
sandbox.network.allowAllUnixSockets	boolean	srt default	Pass-through sandbox-runtime Unix socket override.
sandbox.network.httpProxyPort	number	srt default	Pass-through sandbox-runtime HTTP proxy port override.
sandbox.network.socksProxyPort	number	srt default	Pass-through sandbox-runtime SOCKS proxy port override.
sandbox.filesystem.allowGitConfig	boolean	false	Allow writes to .gitconfig inside the sandbox.
sandbox.ignoreViolations	Record<string, string[]>	—	Pass-through sandbox-runtime ignore rules.
sandbox.enableWeakerNetworkIsolation	boolean	—	Pass-through sandbox-runtime weaker network isolation switch.
sandbox.enableWeakerNestedSandbox	boolean	—	Pass-through sandbox-runtime nested sandbox switch.
sandbox.mandatoryDenySearchDepth	number	3	Pass-through sandbox-runtime mandatory-deny path scan depth.
sandbox.allowPty	boolean	—	Allow pseudo-terminal allocation inside the sandbox.
srtConfig	—	—	Not a config-file key. PizzaPi builds this resolved sandbox-runtime object internally from sandbox.
slowStartupWarning	boolean	true	Show warnings when startup takes longer than expected (slow MCP servers, etc.).
disabledRunnerServices	string[]	[]	Runner service IDs to skip. Built-in: "terminal", "file-explorer", "git", "memory", "process", "time", "tunnel" (terminal, file-explorer, git, time, tunnel cannot be disabled at runtime). Package services use the id declared under pi.pizzapi.services — see Runner Services.
subagent.maxParallelTasks	number	8	Max parallel tasks per call and active agent slots across background calls. Global config only.
subagent.maxConcurrency	number	4	Max concurrent agent sessions within one parallel call. Global config only.
subagent.backgroundAfterSeconds	—	—	Not supported. Use bash.backgroundAfterSeconds for shell auto-backgrounding.
subagent.keepLoadedTools	—	—	Not supported. Use toolSearch.keepLoadedTools for deferred MCP tools.
goal.evaluatorModel	string	the session’s own model	Advanced: pin a model (provider:modelId or modelId) for the /goal LLM evaluator. Opts out of session-context cache reuse; falls back to the cheapest authenticated text model if the pinned model has no credentials.
goal.evaluatorMaxTokens	number	512	Maximum output tokens for each /goal evaluator call.
goal.evaluateEveryNTurns	number	1	Default cadence for the LLM evaluator, in completed agent runs. 1 = every run. Ignored by the keyword evaluator.
goal.minTurnsBeforeEvaluate	number	1	Minimum completed agent runs before the goal evaluator runs for the first time.
allowProjectProviders	boolean	—	Obsolete and ignored. Project-local .pizzapi/providers/ is no longer loaded. PizzaPi warns if this key is still present.
providers	object	—	Obsolete and ignored. The extension-provider layer was removed; PizzaPi warns if this key is still present. Use a runner service for external integrations, or a plain pi extension for per-session behaviour.
providerSettings	object	—	Provider-specific settings. See Web Search and Per-Provider Overrides below.
providerSettings.<provider>.webSearch	object	—	Provider web-search config. Supported by anthropic, openai-codex, and ollama-cloud as documented below.
overlayServiceGrants	{ package: string; services: string[] }[]	[]	Global trust grants for daemon services declared by installed pi.pizzapi overlay packages. Managed by PizzaPi package commands; project configs cannot self-authorize these grants.
overlayServiceGrants[].package	string	—	Normalized package identity, e.g. npm:@acme/pi-github or local:/abs/path.
overlayServiceGrants[].services	string[]	—	Exact service IDs granted for that package. New services added by a package update are not auto-granted.

---

Bash Auto-Backgrounding

The bash tool streams output normally for the first 15 seconds. If the command is still running after that, the tool call returns, the process keeps running, its output is redirected to a temp log file, and a message is delivered into the session when it exits:

Run server tests exited with code 1 after 92s

See full stdout/stderr in /tmp/pizzapi-bash-1761...log

Every bash call takes a title describing its purpose — that is the name used in the running and completion messages. The agent is instructed never to sleep-poll for a backgrounded command; it can call bash_output(pid) for incremental output or kill_shell(pid) to stop it. Setting run_in_background: true skips the foreground wait entirely.

{
  "bash": {
    "backgroundAfterSeconds": 15
  }
}

Override per-process with PIZZAPI_BASH_BACKGROUND_SECONDS. Users can also background a running command manually with ctrl+shift+b, /background, or the web UI’s background button.

Shell environment

Commands run by the bash tool inherit the session’s environment except PizzaPi’s own credentials. Removed variables are PIZZAPI_API_KEY, PIZZAPI_API_TOKEN, PIZZAPI_RUNNER_API_KEY, PIZZAPI_RUNNER_TOKEN, PIZZAPI_AUTH_TOKEN, relay-server secrets (BETTER_AUTH_SECRET, VAPID_PRIVATE_KEY, PIZZAPI_TUNNEL_TOKEN_SECRET*, PIZZAPI_NTFY_PUBLISH_TOKEN, PIZZAPI_CADDY_DNS_TOKEN, PIZZAPI_WEBHOOK_SECRET), and any other PIZZAPI_* variable whose name ends in _KEY, _TOKEN, _SECRET, or _PASSWORD. A <NAME>_FILE pointer to any of these (such as PIZZAPI_API_KEY_FILE) is removed as well, so a command cannot follow it to the file-backed secret. The session process keeps the credentials for its own relay connection and tools.

Your own variables, such as provider API keys, GITHUB_TOKEN, and cloud credentials, are passed through unchanged so the tools you run in a shell keep working. Non-secret PizzaPi variables such as PIZZAPI_RELAY_URL are also kept. To deliberately expose a stripped variable to shell commands, list it in PIZZAPI_BASH_PASSTHROUGH_ENV (comma-separated) in the runner’s or CLI’s environment.

This keeps credentials out of the shell environment only. A command can still read files that contain secrets, such as ~/.pizzapi/config.json, unless the sandbox denies the path.

---

Web Search

PizzaPi can add web search tools to supported providers, giving the agent the ability to search the web during conversations.

• Anthropic uses Anthropic’s server-side web_search_20250305 tool type.
• OpenAI Codex uses OpenAI’s hosted web_search tool. It is available directly to the model, not through MCP tool discovery.
• Ollama Cloud registers web_search and web_fetch tools that call Ollama’s REST APIs with your Ollama Cloud credentials.

Configuration

Add a providerSettings block to ~/.pizzapi/config.json:

~/.pizzapi/config.json

{
  "providerSettings": {
    "anthropic": {
      "webSearch": {
        "enabled": true,
        "maxUses": 5,
        "allowedDomains": ["docs.python.org", "developer.mozilla.org"],
        "blockedDomains": ["example.com"]
      }
    }
  }
}

Key	Type	Default	Description
enabled	boolean	false	Enable web search for Anthropic models.
maxUses	number	5	Maximum number of searches per request.
allowedDomains	string[]	—	Only return results from these domains.
blockedDomains	string[]	—	Never return results from these domains.

For Ollama Cloud, enable web search under providerSettings["ollama-cloud"].webSearch:

~/.pizzapi/config.json

{
  "providerSettings": {
    "ollama-cloud": {
      "webSearch": {
        "enabled": true,
        "maxResults": 5,
        "maxContentChars": 8000,
        "maxLinks": 100
      }
    }
  }
}

Key	Type	Default	Description
enabled	boolean	false	Register Ollama web_search and web_fetch tools.
maxResults	number	5	Default number of search results to request from Ollama (1–10).
maxContentChars	number	8000	Truncate fetched page content to this many characters (1–100000).
maxLinks	number	100	Truncate fetched page links to this many entries (1–1000).

For OpenAI Codex, enable hosted search under providerSettings["openai-codex"].webSearch:

{
  "providerSettings": {
    "openai-codex": { "webSearch": { "enabled": true } }
  }
}

The enabled flag defaults to false. You can also toggle it under Runner → Settings → Web Search → OpenAI Codex; changes apply on the next session start.

Codex receives explicit hosted-search availability guidance on each enabled request. Search queries and source URLs appear in the session’s search cards, but are not replayed to the model as assistant text. This avoids confusing a displayed search with a completed search on a later turn, including after a model switch. Readable answer text and any citations the agent included in it remain in the conversation.

Per-Provider Overrides

System prompt controls, AGENTS.md inclusion, and MCP server availability can be overridden per model provider via providerSettings.<provider>.overrides — editable in the web UI under Runner → Settings → Provider Overrides. The overrides apply when a session starts on that provider — either because it was spawned with an explicit model, or because it matches defaultProvider in ~/.pizzapi/settings.json.

~/.pizzapi/config.json

{
  "providerSettings": {
    "claude-subscription": {
      "overrides": {
        // Vanilla prompt for subscription sessions
        "builtinSystemPrompt": false,
        "sendAgentsMd": false,
        "appendSystemPrompt": "",
        // Disable heavyweight MCP servers on this provider
        "disabledMcpServers": ["playwright"]
      }
    }
  }
}

Key	Type	Description
systemPrompt	string	Fully replace the default system prompt for this provider.
appendSystemPrompt	string	Replace the global appendSystemPrompt for this provider.
builtinSystemPrompt	boolean	Override the global built-in prompt toggle.
sendAgentsMd	boolean	Override automatic AGENTS.md context inclusion.
disabledMcpServers	string[]	Additional MCP servers to disable (union with global/project lists).

Note

The provider is resolved once at session start. Switching models mid-session (or resuming a session saved on a different provider) does not re-apply overrides — the same “changes apply on next session start” semantics as all other config.

Environment Variables

You can also enable web search via environment variables (environment variables take precedence over config values when set; otherwise the config value is used):

Variable	Description
PIZZAPI_WEB_SEARCH	Set to 1 to enable web search.
PIZZAPI_WEB_SEARCH_MAX_USES	Max searches per request (default: 5).
PIZZAPI_WEB_SEARCH_ALLOWED_DOMAINS	Comma-separated list of allowed domains.
PIZZAPI_WEB_SEARCH_BLOCKED_DOMAINS	Comma-separated list of blocked domains.
PIZZAPI_OPENAI_CODEX_WEB_SEARCH	Set to 1 to enable OpenAI Codex hosted search. 0, false, no, and off disable it.
PIZZAPI_OLLAMA_WEB_SEARCH	Set to 1 to enable Ollama Cloud web tools.
PIZZAPI_OLLAMA_WEB_SEARCH_MAX_RESULTS	Default Ollama search results per request (1–10, default: 5).
PIZZAPI_OLLAMA_WEB_FETCH_MAX_CONTENT_CHARS	Max chars for fetched page content (1–100000, default: 8000).
PIZZAPI_OLLAMA_WEB_FETCH_MAX_LINKS	Max links from fetched pages (1–1000, default: 100).

Note

Anthropic web search works with both API key and OAuth authentication. Ollama web search uses your stored ollama-cloud credentials from /login, or OLLAMA_API_KEY if set.

Built-in Ollama Cloud auth uses an environment variable

Ollama Cloud is available as a built-in provider via OLLAMA_API_KEY. Set it in the same environment as pizzapi or your runner daemon. This is provider auth, not a providerSettings entry.

---

Environment Variables

Only the settings listed here have environment-variable overrides. Overrides apply to the current process and do not rewrite the JSON file.

Variable	Equivalent config key	Notes
PIZZAPI_API_KEY	apiKey
PIZZAPI_RELAY_URL	relayUrl	Set to off to disable relay for this invocation
PIZZAPI_ALLOW_PROJECT_HOOKS	—	Set to 1 to enable project-local hooks
PIZZAPI_ALLOW_PROJECT_MCP	—	Set to 1 to enable loading project-local MCP servers
PIZZAPI_NO_MCP	—	Set to 1 to skip MCP servers (Safe Mode)
PIZZAPI_NO_PLUGINS	—	Set to 1 to skip plugin loading (Safe Mode)
PIZZAPI_NO_HOOKS	—	Set to 1 to skip hook execution (Safe Mode)
PIZZAPI_NO_RELAY	—	Set to 1 to skip relay connection (Safe Mode)
PIZZAPI_DISABLED_RUNNER_SERVICES	disabledRunnerServices	Comma-separated list of service IDs to skip (e.g. git,time)
PIZZAPI_SANDBOX	sandbox.mode	Override sandbox mode: none, basic, or full (Sandbox)
PIZZAPI_NO_SANDBOX	—	Set to 1 to disable sandbox (shorthand for none) (Sandbox)
PIZZAPI_BASH_PASSTHROUGH_ENV	unset	Comma-separated variable names to pass to bash tool commands even though they are PizzaPi credentials that are stripped by default (Shell environment)
PIZZAPI_SANDBOX_ALLOW_UNSANDBOXED	unset	Set to 1 or true to let an explicitly requested sandbox (--sandbox, PIZZAPI_SANDBOX, or sandbox.mode in ~/.pizzapi/config.json) degrade to unsandboxed execution when it cannot be enabled, instead of refusing to start (Sandbox)
PIZZAPI_DEBUG	—	Set to 1 for debug-level PizzaPi CLI logging, including de-duplicated config warnings.
PIZZAPI_LOG_PROVIDER_REQUEST	—	Set to 1 to log summarized outbound Anthropic /v1/messages request data for diagnostics. Authorization headers are fingerprinted, not printed raw.
PIZZAPI_HIDDEN_MODELS	—	JSON array of provider/modelId keys hidden from model listing/switching in worker sessions. Usually seeded and updated by the relay from the user’s web preferences.
PIZZAPI_SUBAGENT_MODEL	—	Default subagent/workflow model as provider/modelId; empty/unset means auto-select. Usually managed by the web UI.
PIZZAPI_SANDBOX_MODE	—	Internal status set after sandbox initialization to the active resolved mode (basic or full). Use PIZZAPI_SANDBOX to request a mode.
PIZZAPI_TUNNEL_MAX_BUFFERED_BYTES	—	Runner-side tunnel buffer ceiling in bytes (default 64 MiB; 0 disables). A local request body, local WebSocket, or relay link that falls this far behind is terminated instead of queueing without bound. For the relay link, the check includes the frame about to be sent (with its encoding overhead): a tunnelled HTTP response or WebSocket whose next frame would push the queue past the ceiling is terminated, so a single oversized frame cannot slip through. Invalid values are ignored. The relay reads the same variable for its side (Self-Hosting).
PIZZAPI_RUNNER_STATE_PATH	—	Override runner daemon state/lock file. Default: ~/.pizzapi/runner.json.
PIZZAPI_RUNNER_USAGE_CACHE_PATH	—	Override the runner-wide provider-usage cache file inherited by workers. Normally set by the daemon.
PIZZAPI_SUSPEND_IDLE_MS	—	Override how long (ms) a completed child session sits idle before its worker exits and the session suspends on the relay (default 30 minutes). Invalid values are ignored; valid values are clamped to a 5000ms minimum. Only runner-spawned worker sessions can suspend; set it on the daemon’s own environment to forward it to every worker it spawns.
PIZZAPI_MCP_AUTH_DIR	—	Override MCP OAuth token/client storage directory. Default: ~/.pizzapi/mcp-auth. Useful for tests or isolated installs.
PIZZAPI_SOCKETIO_URL	—	Override the Socket.IO HTTP(S) base URL. Default is derived from relayUrl by converting ws/wss to http/https.
PIZZAPI_CHANGELOG_PATH	—	Override the PizzaPi CLI changelog path used by the patched upstream changelog reader; normally set automatically to packages/cli/CHANGELOG.md when present.
PIZZAPI_NTFY_URL	—	Internal ntfy base URL used by the pizza web Docker stack for native Android push; compose sets it to http://ntfy.
PIZZAPI_ELICITATION_URL_PORT	—	Test-fixture port for extensions/mcp/elicitation-url-test-server.mjs; unset uses a random port.

PIZZAPI_WORKER_* and PIZZAPI_SESSION_* variables are internal worker-session plumbing set by the daemon, not user configuration. Current internal keys include PIZZAPI_WORKER_CWD, PIZZAPI_WORKER_INITIAL_PROMPT, PIZZAPI_WORKER_INITIAL_IMAGE_URLS, PIZZAPI_WORKER_INITIAL_MODEL_PROVIDER, PIZZAPI_WORKER_INITIAL_MODEL_ID, PIZZAPI_WORKER_INITIAL_EFFORT, PIZZAPI_WORKER_PARENT_SESSION_ID, PIZZAPI_WORKER_AGENT_NAME, PIZZAPI_WORKER_AGENT_SYSTEM_PROMPT, PIZZAPI_WORKER_AGENT_TOOLS, PIZZAPI_WORKER_AGENT_DISALLOWED_TOOLS, PIZZAPI_WORKER_RESUME_PATH, PIZZAPI_WORKER_AUTO_CLOSE, PIZZAPI_SESSION_ID, PIZZAPI_SESSION_PROVIDER, PIZZAPI_SESSION_FILE, PIZZAPI_SESSION_PROC_FILE, and PIZZAPI_SESSION_ATTACHMENTS_DIR.

Example:

export PIZZAPI_API_KEY="pk_live_abc123..."
export PIZZAPI_RELAY_URL="wss://relay.example.com"
pizzapi

Disable the relay for one invocation:

PIZZAPI_RELAY_URL=off pizzapi

Disable the relay permanently (no env var needed each time):

~/.pizzapi/config.json

{
  "relayUrl": "off"
}

Tip

Environment variables are useful in CI/CD pipelines or when you want to avoid storing credentials in a file.

Note

pizzapi setup persists both the API key and the selected relay URL in ~/.pizzapi/config.json. Environment overrides apply only to that process and do not rewrite the file.

---

Pi Agent Settings

In addition to PizzaPi’s own config, the underlying pi agent has its own settings file for model defaults, compaction, retry behavior, and UI preferences. These are separate from ~/.pizzapi/config.json:

File	Scope
~/.pizzapi/settings.json	Global pi settings
.pizzapi/settings.json	Project-local pi settings (overrides global)

Edit directly or use the /settings command inside a session.

Key Settings

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "fallbackModels": [
    "openai-codex:gpt-5.5",
    "ollama-cloud:glm-5.2"
  ],
  "waitForRateLimits": false,
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "maxDelayMs": 60000
  },
  "enabledModels": ["claude-*", "gpt-4o"]
}

fallbackModels is an ordered list of model references (provider:modelId or just modelId). Fallback runs only when a turn ends with stopReason: "error" and the final error message matches a usage-limit phrase (usage limit, rate limit, quota, quota exceeded, resource exhausted, tokens per minute, requests per minute, output tokens per) or a provider-capacity phrase (overloaded, HTTP 529, throttl...). At the failed turn boundary, fallback switches to the next configured model with credentials and sends the last user input back as a steer message. It starts after the current model’s position in the chain when present, otherwise at the beginning, skips unavailable/already-tried models, and cascades until one succeeds or no configured fallback is available. Configure it from the web UI under Runner → Settings → Models or by editing ~/.pizzapi/settings.json directly.

waitForRateLimits defaults to false. When enabled, a usage-limit failure with no remaining fallback can wait for verified quota recovery on the current model before continuing. Unknown or stale quota never triggers a retry. The global setting applies on session start; /rate-limit-wait on|off|cancel|status controls the current session from the TUI or web composer. See waiting for rate limits for cancellation and recovery behavior.

Note

PizzaPi config (~/.pizzapi/config.json) controls the relay, MCP servers, hooks, sandbox, and PizzaPi extensions. Pi settings (~/.pizzapi/settings.json) control model defaults, compaction, retry, and session behavior. They are independent — don’t mix them up.

---

Merge Order

When PizzaPi starts, config is resolved in this order (later entries win):

1. Built-in defaults
2. ~/.pizzapi/config.json (global)
3. <cwd>/.pizzapi/config.json (project-local)
4. Environment variables (PIZZAPI_API_KEY, PIZZAPI_RELAY_URL)

Note

apiKey and relayUrl are exceptions: when both global and project configs set them, the global value wins. Project values are kept only when global is unset.

---

Skills Search Paths

PizzaPi automatically looks for skills in these locations (all merged):

1. Built-in CLI skills
2. ~/.pizzapi/skills/ — your global personal skills
3. <cwd>/.pizzapi/skills/ — project-local skills
4. ~/.pizzapi/agents/ — global agents treated as skills
5. <cwd>/.pizzapi/agents/ — project-local agents treated as skills
6. <cwd>/.agents/skills/ — Claude Code compatible project skills
7. <cwd>/.agents/agents/ — Claude Code compatible project agents
8. Any paths listed in the skills config array

See the Skills & Extensions guide for how to write and use skills.

---

Example: Per-Project Configuration

Create .pizzapi/config.json in your project root to customize behavior for that repo:

my-project/.pizzapi/config.json

{
  "appendSystemPrompt": "This is a Next.js 15 project using the App Router. Always use TypeScript.",
  "skills": [
    ".pi/skills"
  ]
}

Commit this file to share it with your team — just keep apiKey out of project-local config (use the global file or environment variables instead).

---

Web Hub Configuration

The pizza web command has its own separate config file at ~/.pizzapi/web/config.json for managing the self-hosted relay server. This is distinct from the CLI config above.

# View current web hub config
pizzapi web config

# Set values
pizzapi web config set port 9000
pizzapi web config set extraOrigins "https://example.com"
pizzapi web config set vapidSubject "mailto:ops@example.com"

Key	Default	Description
port	7492	Host port to expose the web UI on
vapidSubject	mailto:admin@pizzapi.local	VAPID subject for web push notifications
extraOrigins	(none)	Extra allowed CORS origins, comma-separated

CLI flags like --port and --origins also persist to this config file automatically.

See the CLI Reference and Self-Hosting guide for more details.