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.",

  // 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,

  // 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,

  // 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"]
    }
  }
}

---

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
agentDir	string	~/.pizzapi	Agent config directory (skills, extensions, etc.)
skills	string[]	[]	Additional skill directories. Supports ~ expansion.
allowProjectHooks	boolean	false	Trust gate: allow project-local hooks to run. Global config only.
trustedPlugins	string[]	[]	Trusted Claude Code plugin paths. Global config only. Managed via pizza plugins trust.
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.
mcpTimeout	number	30000	Timeout (ms) for each MCP server’s tools/list call during startup. Set to 0 to disable. See Safe Mode.
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.). See Safe Mode.
subagent.maxParallelTasks	number	8	Max tasks in a single parallel subagent call. Global config only.
subagent.maxConcurrency	number	4	Max concurrent agent sessions running simultaneously. Global config only.
providerSettings	object	—	Provider-specific settings. See Web Search below.

---

Web Search

PizzaPi can inject Anthropic’s server-side web search tool into requests, giving the agent the ability to search the web during conversations. This uses Anthropic’s web_search_20250305 tool type.

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.

Environment Variables

You can also enable web search via environment variables (these take precedence if the config values are not already set):

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.

Note

Web search works with both API key and OAuth authentication.

---

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 override saved config values in JSON files — the JSON is loaded first, then env vars for the relay connection are applied on top.

Variable	Equivalent config key	Notes
PIZZAPI_API_KEY	apiKey
PIZZAPI_RELAY_URL	relayUrl	Set to off to disable relay for this invocation
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_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"
}

---

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)

---

Skills Search Paths

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

1. ~/.pizzapi/skills/ — your global personal skills
2. <cwd>/.pizzapi/skills/ — project-local skills
3. 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.