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

You can also override any setting with environment variables.

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 — 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", "tunnel", "time".
  // Plugin-provided services use the id declared in their manifest.
  "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
  },

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

---

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.
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 Tool Search.
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.
slowStartupWarning	boolean	true	Show warnings when startup takes longer than expected (slow MCP servers, etc.).
disabledRunnerServices	string[]	[]	Runner service IDs to skip. Built-in services: "terminal", "file-explorer", "git", "tunnel", "time". Plugin services use the id declared in their manifest.
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.
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.

---

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.

---

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.
• 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).

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_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

Every config option can also be set as an environment variable. Environment variables take effect for the current process only and do not rewrite the JSON file, but they do take precedence at runtime.

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)

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.

Relay URL is not saved by pizzapi setup

pizzapi setup saves your API key to ~/.pizzapi/config.json but does not persist the relay URL. If you connect to a non-default relay (anything other than localhost:7492), manually add "relayUrl" to your config after setup:

~/.pizzapi/config.json

{
  "apiKey": "pk_live_...",
  "relayUrl": "wss://your-relay.example.com"
}

---

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"
  ],
  "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). When the active model returns a rate-limit, quota, or provider-capacity error (e.g. Anthropic overloaded_error) after exhausting its retries, PizzaPi automatically switches to the first matching fallback in the list and retries the last user prompt. It cascades through the chain until a model succeeds or the chain is exhausted. Configure it from the web UI under Runner → Settings → Models or by editing ~/.pizzapi/settings.json directly.

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.