pi-web/docs/config.md

PI WEB configuration reference

PI WEB configuration covers the machine-local and project-local settings you usually need: the web/API bind address, trusted development-host settings, UI preferences, plugin enablement, file-explorer path access, manual upload defaults, upload limits, agent runtime selection, and session-daemon tools.

This file is the markdown reference for agents and package consumers. The website page is https://pi-web.dev/config.

Config files

PI WEB uses two config files:

• Global PI WEB config: $PI_WEB_CONFIG, or $XDG_CONFIG_HOME/pi-web/config.json, or ~/.config/pi-web/config.json.
• Project-local PI WEB config: <project>/.pi-web/config.json for commit-able project settings.

Each PI WEB machine has its own config. When using Fleet/machine federation, edit a remote machine's config by opening that machine directly or changing files on that machine.

If you installed services with a custom config path, rerun pi-web install --config /path/to/config.json after changing that path or after upgrading from a version that only applied the custom path to the web service. This regenerates service files so the web/API and session daemon use the same PI_WEB_CONFIG.

Precedence and reloads

Machine-global runtime values are resolved as:

defaults → global config file → environment overrides

Supported project-local settings are then applied for that project's workspaces. For upload defaults, <project>/.pi-web/config.json overrides the global value.

Environment overrides include PI_WEB_HOST, PI_WEB_PORT / PORT, PI_WEB_ALLOWED_HOSTS, PI_WEB_MAX_UPLOAD_BYTES, PI_WEB_AGENT_COMMAND, PI_WEB_AGENT_DIR, PI_WEB_AGENT_SESSION_DIR, PI_CODING_AGENT_DIR, PI_CODING_AGENT_SESSION_DIR, PI_WEB_SPAWN_SESSIONS, and PI_WEB_SUBSESSIONS.

Process restarts depend on the key:

• host / port: restart the web/API service or process.
• maxUploadBytes: restart both the web/API process and the session daemon.
• agent.command / agent.dir / spawnSessions / subsessions: restart the session daemon.
• pathAccess: applies on the next request; existing file views may need a browser refresh.
• uploads.defaultFolder: applies to newly opened Files upload dialogs and new direct drag/drop batches after config/workspace refresh.
• plugins: reload the browser tab after changing plugin enablement.
• shortcuts: saved settings apply in the browser after config refresh/save.

Global config example

{
  "host": "127.0.0.1",
  "port": 8504,
  "pathAccess": {
    "allowedPaths": ["~/SDKs", "/opt/reference"]
  },
  "uploads": {
    "defaultFolder": ".pi-web/uploads"
  },
  "maxUploadBytes": 67108864,
  "agent": {
    "command": "pi",
    "dir": "~/agent-profiles/research"
  },
  "spawnSessions": true,
  "subsessions": false,
  "plugins": {
    "workspace-tasks": { "enabled": true },
    "updates": { "enabled": true },
    "info": { "enabled": false }
  },
  "shortcuts": {
    "core:view.chat": "mod+1",
    "core:session.stop": null
  }
}

Project-local config

Project-local config lives at <project>/.pi-web/config.json. Use it for settings that should follow a repository.

{
  "version": 1,
  "pathAccess": {
    "allowedPaths": ["~/SDKs", "/opt/reference"]
  },
  "uploads": {
    "defaultFolder": "manual/uploads"
  }
}

Project-local pathAccess.allowedPaths entries are merged after the global list and deduplicated. Paths must still be host-absolute or ~-prefixed; relative roots are not supported.

Project-local uploads.defaultFolder overrides the global upload destination for workspaces in that project. Current PI WEB servers include this workspace-effective value on the existing workspace responses used locally and through machine federation. Older remote servers may omit the optional field; the browser falls back to the global/default upload folder.

Plugins may own separate project files, such as .pi-web/tasks.json for the built-in Workspace Tasks plugin.

Configuration matrix

Rows with JSON key — are runtime-only environment variables, not config-file keys.

Config	JSON key	Env var	Scope	Project-local behavior	Applies / restart
Config-file keys
Web/API bind host	host	PI_WEB_HOST	Global	Not supported locally	Restart web/API
Web/API port	port	PI_WEB_PORT, PORT	Global	Not supported locally	Restart web/API
Dev-server allowed hosts	allowedHosts	PI_WEB_ALLOWED_HOSTS	Global	Not supported locally	Restart dev web/UI
External filesystem roots	pathAccess.allowedPaths	—	Global + project	Merges: global roots first, then project roots; duplicates removed	Next file request; refresh existing views if needed
Manual file upload default folder	uploads.defaultFolder	—	Global + project	Overrides: project value wins for workspaces in that project; otherwise global/default applies	New Upload dialogs and direct drag/drop batches after config/workspace refresh
Upload/body limit	maxUploadBytes	PI_WEB_MAX_UPLOAD_BYTES	Global	Not supported locally	Restart web/API and session daemon
Agent CLI command	agent.command	PI_WEB_AGENT_COMMAND	Global/session daemon	Not supported locally	Restart session daemon; affects doctor/status/update checks
Agent state directory	agent.dir	PI_WEB_AGENT_DIR, PI_CODING_AGENT_DIR	Global/session daemon	Not supported locally	Restart session daemon; affects auth, models, settings, and sessions
Agent can spawn sessions	spawnSessions	PI_WEB_SPAWN_SESSIONS	Global/session daemon	Not supported locally	Restart session daemon
Tracked subsessions (beta)	subsessions	PI_WEB_SUBSESSIONS	Global/session daemon	Not supported locally; also requires spawnSessions	Restart session daemon
Plugin enablement/settings	plugins.<id>.enabled, plugins.<id>.settings	—	Global	Not core local config; plugins may read their own project files	Reload browser tab
Keyboard shortcuts	shortcuts.<actionId>	—	Global	Not supported locally	Applies after settings save/config refresh
Project config version	version	—	Project	Project-local only; must be 1 when present	Next project-config read
Runtime-only environment variables
Global config file path	—	PI_WEB_CONFIG (XDG_CONFIG_HOME affects the default path)	Process/env	Selects the global config file; not a project config	Restart services/processes after changing env
Managed data directory	—	PI_WEB_DATA_DIR	Process/env	Not supported locally	Restart services before changing; moves managed state location
Session daemon socket	—	PI_WEB_SESSIOND_SOCKET	Web/API + session daemon env	Not supported locally	Restart daemon and web/API; both must match
Session daemon TCP port	—	PI_WEB_SESSIOND_PORT	Session daemon env	Not supported locally	Restart session daemon; set PI_WEB_SESSIOND_URL for web/API too
Session daemon TCP host	—	PI_WEB_SESSIOND_HOST	Session daemon env	Not supported locally	Restart session daemon
Web-to-daemon URL	—	PI_WEB_SESSIOND_URL	Web/API env	Not supported locally	Restart web/API
Projects storage file	—	PI_WEB_PROJECTS_FILE	Web/API + session daemon env	Not supported locally	Restart services; advanced state override
Remote machines storage file	—	PI_WEB_MACHINES_FILE	Web/API env	Not supported locally	Restart web/API; advanced state override
Agent session storage directory	—	PI_WEB_AGENT_SESSION_DIR, PI_CODING_AGENT_SESSION_DIR	Session daemon env	Not supported locally	Restart session daemon; env-only session storage override
Agent config directory	—	PI_WEB_AGENT_DIR, PI_CODING_AGENT_DIR	Web/API + session daemon env	Not supported locally	Restart services
Skip update checks	—	PI_WEB_SKIP_VERSION_CHECK, PI_WEB_OFFLINE, PI_SKIP_VERSION_CHECK, PI_OFFLINE	Web/API env	Not supported locally	Restart web/API after env changes

Key details

External path access

pathAccess.allowedPaths grants PI WEB's file explorer and absolute @ path completions access to specific filesystem roots outside the current workspace.

By default, workspace-relative file reads stay inside the workspace and absolute paths are denied. Add only roots you trust PI WEB to list and read through the browser UI.

Accepted root forms:

• Unix absolute paths: /opt/reference
• Home-relative paths: ~/SDKs
• Windows absolute paths on Windows hosts: C:\Users\dev\SDKs

When an absolute request is served, PI WEB expands ~, canonicalizes the configured roots with realpath, requires roots to be existing directories, and rejects symlink escapes outside the allowed roots.

This is not a sandbox for the underlying Pi Coding Agent or your OS user. It only controls PI WEB UI/API file exposure outside a workspace.

Manual upload defaults

The Files panel can upload one or more files in two ways:

• Drop files onto the Files panel to upload immediately to the workspace-effective default folder.
• Use the toolbar Upload button to open the review dialog, edit the destination, and opt into upload options.

uploads.defaultFolder sets the workspace-effective default destination. The built-in default is .pi-web/uploads; a global config value applies to every project unless <project>/.pi-web/config.json sets a project-local override.

{
  "uploads": {
    "defaultFolder": "manual/uploads"
  }
}

The value must be a non-empty workspace-relative folder. PI WEB normalizes repeated separators and backslashes to /, and rejects absolute paths or .. traversal. In the upload dialog only, clearing the destination field uploads that batch to the workspace root.

Manual uploads use the workspace file-write path: paths stay workspace-relative, parent folder creation is enabled by default, and overwrite is disabled by default. Direct drag/drop always keeps overwrite off; the review dialog lets you explicitly enable overwrite when needed. Browser-owned XHR progress is shown per batch/file, conflicts and errors stay visible in the upload progress UI, and the final file-write response is the source of truth.

For machine federation, current remote PI WEB servers return workspace.effectiveConfig.uploads.defaultFolder on the existing workspace-list response. Older remote servers can omit that optional field without breaking clients; the Files panel falls back to the global/default upload folder.

The per-request size limit is still controlled by maxUploadBytes / PI_WEB_MAX_UPLOAD_BYTES.

Agent runtime selection

agent.command controls which Pi-compatible CLI PI WEB checks in doctor/status/update flows. It defaults to pi. Set it only when diagnostics and package-managed update checks should target another compatible command; the embedded session runtime still uses PI WEB's SDK integration.

agent.dir controls which compatible agent state directory PI WEB reads for auth providers, model settings, settings, and session metadata. It defaults to ~/.pi/agent. Set it to another Pi-compatible state directory when you want an isolated profile or an alternate compatible agent's data.

{
  "agent": {
    "command": "pi",
    "dir": "~/agent-profiles/research"
  }
}

For example, an Oh My Pi profile can set agent.command to omp and agent.dir to ~/.omp/agent.

Environment variables take precedence over the config file. PI_WEB_AGENT_COMMAND selects the command, PI_WEB_AGENT_DIR sets the state directory for any command, and PI_WEB_AGENT_SESSION_DIR overrides session storage separately from agent.dir. Existing Pi Coding Agent env names (PI_CODING_AGENT_DIR and PI_CODING_AGENT_SESSION_DIR) remain supported for compatibility.

Session directory overrides are environment-only; use PI_WEB_AGENT_SESSION_DIR unless you need the legacy Pi-compatible PI_CODING_AGENT_SESSION_DIR name.

Restart the session daemon after changing agent settings. The web/API process can display the new config immediately, and status/plugin discovery may re-read it on later requests, but active session runtime ownership is intentionally long-lived.

Session daemon tools

spawnSessions controls whether agents receive the spawn_session tool. It defaults to true; set it to false if you do not want an agent to start independent PI WEB sessions.

subsessions is beta and controls whether agents receive the tracked-subsession tools: spawn_subsession, list_subsessions, check_subsession, and read_subsession. It defaults to false and also requires spawnSessions to be enabled.

Tracked subsessions let an agent delegate work to child sessions, get notified when children stop working, and inspect their transcripts.

Plugin config

Plugins are enabled by default. Set plugins.<id>.enabled to false to remove a plugin from /pi-web-plugins/manifest.json before the browser imports it.

{
  "plugins": {
    "workspace-tasks": { "enabled": true, "settings": {} },
    "updates": { "enabled": false }
  }
}

Reload the browser tab after changing plugin enablement. Already-loaded plugin JavaScript is not unloaded from the current page.

Shortcut config

Shortcut values are keyed by action id. Values are shortcut strings such as mod+k or mod+g p; null disables that action's shortcut.

{
  "shortcuts": {
    "core:view.chat": "mod+1",
    "core:session.stop": null
  }
}

Prefer Settings → Keyboard for editing shortcuts interactively.

Optional completion tools

File and path @ completions work without extra tools. If fzf is available on the PI WEB server's PATH, PI WEB uses it to improve completion filtering/ranking; otherwise it falls back to built-in ranking.