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, Settings uses the selected machine for config that affects work running there: session daemon tools, PI WEB plugin enablement, external path access, and upload defaults. Gateway/browser-only settings stay local to the gateway: keyboard shortcuts, remote machine registry/tokens, and gateway host/port/allowed-hosts. Remote servers that do not advertise selected-machine settings support report those settings as unavailable instead of silently falling back to the gateway.

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 on the machine whose config you are editing; it does not install, remove, or update Pi packages.

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 gateway web/API service or process.
- `maxUploadBytes`: restart both the web/API process and the session daemon on that machine.
- `spawnSessions` / `subsessions`: restart the session daemon on that machine.
- `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. Machine-affecting Settings fields target the selected machine; gateway host/port/allowed-hosts and keyboard shortcuts stay local. 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. `Global` means machine-global. In Settings, selected-machine-safe global keys (`pathAccess`, `uploads`, `maxUploadBytes`, `spawnSessions`, `subsessions`, and `plugins`) are edited for the selected machine; gateway host/port/allowed-hosts, keyboard shortcuts, and machine registry/tokens stay local.

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 on that machine
Agent can spawn sessions | `spawnSessions` | `PI_WEB_SPAWN_SESSIONS` | Global/session daemon | Not supported locally | Restart session daemon on that machine
Tracked subsessions (beta) | `subsessions` | `PI_WEB_SUBSESSIONS` | Global/session daemon | Not supported locally; also requires `spawnSessions` | Restart session daemon on that machine
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.

In Settings → General, external filesystem roots are saved on the selected machine. Gateway host, port, and allowed-hosts fields stay on the gateway config.

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.

For machine federation, Settings saves the global upload default on the selected machine. Current remote PI WEB servers also return workspace-effective upload defaults on workspace responses; older remote servers may omit them and the browser falls back to the global/default upload folder.

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

In Settings → Session daemon, these keys are saved on the selected machine. Restart the session daemon on that machine after changing them.

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