Configuration reference

# Configure PI WEB where your agents work.

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

## Config files

PI WEB uses a global config file for machine-local settings and a project-local file for repository settings.

- Global config: `$PI_WEB_CONFIG`, or `$XDG_CONFIG_HOME/pi-web/config.json`, or `~/.config/pi-web/config.json`.
- Project 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.

Pi package settings are separate from PI WEB config. They live in Pi's package-manager settings on the target machine and are managed by Pi (`pi install`, `pi remove`, `pi update`) or Settings → Pi packages. In a federated setup, Settings → Pi packages targets the currently selected machine; the PI WEB `plugins` config key only enables or disables discovered PI WEB browser plugins for the gateway you opened.

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 in this order:

    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_SPAWN_SESSIONS`, and `PI_WEB_SUBSESSIONS`.

- `host` / `port`: restart the web/API service or process.
- `maxUploadBytes`: restart both the web/API process and the session daemon.
- `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 PI WEB plugin enablement.
- Pi package install/remove/update: not a PI WEB config key; after a mutation, type `/reload` in each idle PI WEB session on the target machine to refresh Pi runtime resources such as extensions, skills, prompt templates, themes, and context/system prompt files as supported by Pi. Reload the browser page separately for PI WEB browser plugin changes. A routine session daemon restart is not required.
- `shortcuts`: saved settings apply in the browser after config refresh/save.

## Global config example

`pi-web install` creates the initial file. You can also save PI WEB config settings from Settings → General, Settings → PI WEB plugins, Settings → Keyboard, and Settings → Session daemon. Pi package operations live separately under Settings → Pi packages.

Example config.json

    {
      "host": "127.0.0.1",
      "port": 8504,
      "pathAccess": {
        "allowedPaths": ["~/SDKs", "/opt/reference"]
      },
      "uploads": {
        "defaultFolder": ".pi-web/uploads"
      },
      "maxUploadBytes": 67108864,
      "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.

.pi-web/config.json

    {
      "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 local and federated workspace responses; older remote servers may omit it and 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.

## Config matrix

Use this table as the quick reference for where a setting can live, which environment variable overrides it, and whether project-local config overrides or merges with global config. 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 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
PI WEB 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
Pi session storage directory | — | `PI_CODING_AGENT_SESSION_DIR` | Pi/session daemon env | Not supported locally | Restart session daemon; follows Pi session priority
Pi agent config directory | — | `PI_CODING_AGENT_DIR` | Pi/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

## 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.

Accepted root forms:

- Unix absolute paths, for example `/opt/reference`.
- Home-relative paths, for example `~/SDKs`.
- Windows absolute paths on Windows hosts, for example `C:\Users\dev\SDKs`.

When an absolute request is served, PI WEB expands `~`, canonicalizes 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. Add only roots you trust PI WEB to list and read through the browser UI.

## Manual upload defaults

The Files panel can upload files by dropping them onto the panel or by using the toolbar Upload button. `uploads.defaultFolder` sets the workspace-effective default destination. The built-in default is `.pi-web/uploads`; a project-local value overrides the global value for workspaces in that project.

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. Browser-owned XHR progress is shown per batch/file, and conflicts or errors stay visible in the upload progress UI.

## Session daemon tools

### `spawnSessions`

Boolean. Controls whether agents receive the `spawn_session` tool. Defaults to `true`. Set it to `false` if you do not want an agent to start independent PI WEB sessions.

Environment override: `PI_WEB_SPAWN_SESSIONS=0|1|true|false`.

### `subsessions`

Boolean. Beta. Controls whether agents receive the tracked-subsession tools: `spawn_subsession`, `list_subsessions`, `check_subsession`, and `read_subsession`. 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. Restart the session daemon after changing this setting.

Environment override: `PI_WEB_SUBSESSIONS=0|1|true|false`.

## 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 and ranking; otherwise it falls back to built-in ranking.

Install guide Markdown reference