Archived
docs: add PI WEB configuration reference
This commit is contained in:
Federico Jaramillo Martinez
+166
@@ -0,0 +1,166 @@
|
||||
# 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, upload limits, 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
|
||||
|
||||
Runtime values are resolved as:
|
||||
|
||||
```text
|
||||
defaults → config file → environment overrides
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
- `spawnSessions` / `subsessions`: restart the session daemon.
|
||||
- `pathAccess`: applies on the next request; existing file views may need a browser refresh.
|
||||
- `plugins`: reload the browser tab after changing plugin enablement.
|
||||
- `shortcuts`: saved settings apply in the browser after config refresh/save.
|
||||
|
||||
## Global config example
|
||||
|
||||
```json
|
||||
{
|
||||
"host": "127.0.0.1",
|
||||
"port": 8504,
|
||||
"pathAccess": {
|
||||
"allowedPaths": ["~/SDKs", "/opt/reference"]
|
||||
},
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"pathAccess": {
|
||||
"allowedPaths": ["~/SDKs", "/opt/reference"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
## 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.
|
||||
|
||||
### 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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user