diff --git a/.changeset/document-config-reference.md b/.changeset/document-config-reference.md new file mode 100644 index 0000000..93e519f --- /dev/null +++ b/.changeset/document-config-reference.md @@ -0,0 +1,5 @@ +--- +"@jmfederico/pi-web": patch +--- + +Add a dedicated PI WEB configuration reference covering config-file precedence, project-local config, external path access allowlists, session daemon tools, plugins, shortcuts, upload limits, and environment variables. Custom `pi-web install --config` paths are now passed to the session daemon service as well as the web service, and the session daemon now honors config-file `maxUploadBytes` values. diff --git a/README.md b/README.md index a27f1a9..801f4b5 100644 --- a/README.md +++ b/README.md @@ -259,10 +259,16 @@ npm publish --access public PI WEB uses a single-line CalVer-inspired npm version: `MAJOR.YYYYMM.SEQUENCE`, for example `1.202605.1`. The major number signals breaking-change eras; the middle number is the release month; the final number increments for additional releases in that month. Older major eras may be deprecated rather than maintained in parallel. -PI WEB declares `@earendil-works/pi-coding-agent` as a peer dependency (`>=0.74.0 <1`) and a development dependency for local builds. This keeps published installs flexible: npm 7+ installs the peer automatically, and users can upgrade the Pi package within the compatible range without PI WEB pinning a separate copy. +PI WEB declares `@earendil-works/pi-coding-agent` as a peer dependency (`>=0.78.0 <1`) and a development dependency for local builds. This keeps published installs flexible: npm 7+ installs the peer automatically, and users can upgrade the Pi package within the compatible range without PI WEB pinning a separate copy. -The web server defaults to `127.0.0.1:8504`. Set `PI_WEB_HOST=0.0.0.0` only when you intentionally want to bind directly on all interfaces. +## Configuration + +Global PI WEB config lives at `$PI_WEB_CONFIG`, or `$XDG_CONFIG_HOME/pi-web/config.json`, or `~/.config/pi-web/config.json`. Project-local core config lives at `/.pi-web/config.json`. + +See the full [Configuration reference](docs/config.md) for config-file precedence, project-local config, external path access, session daemon settings, plugins, shortcuts, upload limits, and environment variables. + +The web server defaults to `127.0.0.1:8504`. Set `PI_WEB_HOST=0.0.0.0` only when you intentionally want to bind directly on all interfaces behind a trusted network, firewall, or authenticated proxy. The session daemon defaults to a private Unix socket at: @@ -270,18 +276,26 @@ The session daemon defaults to a private Unix socket at: ~/.pi-web/sessiond.sock ``` -Environment variables: +Common config keys: -- `PI_WEB_PORT` / `PORT` — web server port. Defaults to `8504`. -- `PI_WEB_HOST` — web server bind host. Defaults to `127.0.0.1`. -- `PI_WEB_DATA_DIR` — PI WEB data directory. Defaults to `~/.pi-web`. +- `host` / `port` — web/API bind address. Environment overrides: `PI_WEB_HOST`, `PI_WEB_PORT` / `PORT`. +- `pathAccess.allowedPaths` — external filesystem roots that PI WEB may list/read through the file explorer and absolute `@` path completions. Absolute paths are denied by default. +- `maxUploadBytes` — maximum accepted request body size. Defaults to 64 MB. Environment override: `PI_WEB_MAX_UPLOAD_BYTES`. +- `spawnSessions` — enable the `spawn_session` tool. Defaults to `true`. Environment override: `PI_WEB_SPAWN_SESSIONS`. +- `subsessions` — beta tracked-subsession tools (`spawn_subsession`, `list_subsessions`, `check_subsession`, `read_subsession`). Defaults to `false`, requires `spawnSessions`, and requires a session daemon restart after changes. Environment override: `PI_WEB_SUBSESSIONS`. +- `plugins` — plugin enablement/settings. Reload the browser after changing plugin enablement. +- `shortcuts` — keyboard shortcut overrides; use `null` to disable an action shortcut. + +Operational environment variables: + +- `PI_WEB_CONFIG` — path to the global config JSON file. +- `PI_WEB_DATA_DIR` — PI WEB-managed data directory. Defaults to `~/.pi-web`. - `PI_WEB_SESSIOND_SOCKET` — Unix socket path used by both the daemon and web process when `PI_WEB_SESSIOND_URL` is not set. Defaults to `$PI_WEB_DATA_DIR/sessiond.sock`. - `PI_WEB_SESSIOND_PORT` — optional TCP port for the daemon. If unset, the daemon listens on the Unix socket instead. - `PI_WEB_SESSIOND_HOST` — daemon TCP bind host when `PI_WEB_SESSIOND_PORT` is set. Defaults to `127.0.0.1`. - `PI_WEB_SESSIOND_URL` — daemon URL used by the web process when connecting over TCP, for example `http://127.0.0.1:3001`. If you set `PI_WEB_SESSIOND_PORT`, set this for the web process too. - `PI_WEB_PROJECTS_FILE` — optional override for the projects storage JSON file. Defaults to `$PI_WEB_DATA_DIR/projects.json`. - `PI_WEB_MACHINES_FILE` — optional override for the remote machine registry JSON file. Defaults to `$PI_WEB_DATA_DIR/machines.json`. -- `PI_WEB_MAX_UPLOAD_BYTES` — maximum accepted HTTP request body size in bytes (covers pasted/attached images). Defaults to 64 MB. Also configurable as `maxUploadBytes` in `config.json`. - `PI_CODING_AGENT_SESSION_DIR` — Pi session storage directory. PI WEB follows the same session-location priority as Pi for web sessions: this environment variable, then `sessionDir` in Pi settings for the selected workspace, then Pi's default session directory. - `PI_CODING_AGENT_DIR` — Pi agent config directory. PI WEB uses this for Pi auth, settings, resources, and default session storage, matching Pi's own configuration layout. diff --git a/docs/404.html b/docs/404.html index 2f313ac..b80d812 100644 --- a/docs/404.html +++ b/docs/404.html @@ -40,6 +40,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -90,6 +91,7 @@
Fleet Install + Config Plugins FAQ npm diff --git a/docs/config.html b/docs/config.html new file mode 100644 index 0000000..0062f9c --- /dev/null +++ b/docs/config.html @@ -0,0 +1,481 @@ + + + + + + Configure PI WEB — config files, paths, and session tools + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+
+
+

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, plugin enablement, file-explorer path access, 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. +

+

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

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

+
    +
  • 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

+

+ pi-web install creates the initial file. You can also save settings from + Settings → General, Settings → Plugins, Settings → Keyboard, + and Settings → Session daemon. +

+
+
+ Example config.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. When a project config defines pathAccess, PI WEB merges it after the + global path list. +

+
+
+ .pi-web/config.json + +
+ 
{
+  "version": 1,
+  "pathAccess": {
+    "allowedPaths": ["~/SDKs", "/opt/reference"]
+  }
+}
+
+

+ Project-local pathAccess.allowedPaths entries 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. +

+
+ +
+

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

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConfigJSON keyEnv varScopeProject-local behaviorApplies / restart
Config-file keys
Web/API bind hosthostPI_WEB_HOSTGlobalNot supported locallyRestart web/API
Web/API portportPI_WEB_PORT, PORTGlobalNot supported locallyRestart web/API
Dev-server allowed hostsallowedHostsPI_WEB_ALLOWED_HOSTSGlobalNot supported locallyRestart dev web/UI
External filesystem rootspathAccess.allowedPaths—Global + projectMerges: global roots first, then project roots; duplicates removedNext file request; refresh existing views if needed
Upload/body limitmaxUploadBytesPI_WEB_MAX_UPLOAD_BYTESGlobalNot supported locallyRestart web/API and session daemon
Agent can spawn sessionsspawnSessionsPI_WEB_SPAWN_SESSIONSGlobal/session daemonNot supported locallyRestart session daemon
Tracked subsessions (beta)subsessionsPI_WEB_SUBSESSIONSGlobal/session daemonNot supported locally; also requires spawnSessionsRestart session daemon
Plugin enablement/settingsplugins.<id>.enabled, plugins.<id>.settings—GlobalNot core local config; plugins may read their own project filesReload browser tab
Keyboard shortcutsshortcuts.<actionId>—GlobalNot supported locallyApplies after settings save/config refresh
Project config versionversion—ProjectProject-local only; must be 1 when presentNext project-config read
Runtime-only environment variables
Global config file path—PI_WEB_CONFIG (XDG_CONFIG_HOME affects the default path)Process/envSelects the global config file; not a project configRestart services/processes after changing env
Managed data directory—PI_WEB_DATA_DIRProcess/envNot supported locallyRestart services before changing; moves managed state location
Session daemon socket—PI_WEB_SESSIOND_SOCKETWeb/API + session daemon envNot supported locallyRestart daemon and web/API; both must match
Session daemon TCP port—PI_WEB_SESSIOND_PORTSession daemon envNot supported locallyRestart session daemon; set PI_WEB_SESSIOND_URL for web/API too
Session daemon TCP host—PI_WEB_SESSIOND_HOSTSession daemon envNot supported locallyRestart session daemon
Web-to-daemon URL—PI_WEB_SESSIOND_URLWeb/API envNot supported locallyRestart web/API
Projects storage file—PI_WEB_PROJECTS_FILEWeb/API + session daemon envNot supported locallyRestart services; advanced state override
Remote machines storage file—PI_WEB_MACHINES_FILEWeb/API envNot supported locallyRestart web/API; advanced state override
Pi session storage directory—PI_CODING_AGENT_SESSION_DIRPi/session daemon envNot supported locallyRestart session daemon; follows Pi session priority
Pi agent config directory—PI_CODING_AGENT_DIRPi/Web/API/session daemon envNot supported locallyRestart services
Skip update checks—PI_WEB_SKIP_VERSION_CHECK, PI_WEB_OFFLINE, PI_SKIP_VERSION_CHECK, PI_OFFLINEWeb/API envNot supported locallyRestart 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. +
+
+ +
+

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 +
+
+
+
+
+
+ + + + + diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..d437ca2 --- /dev/null +++ b/docs/config.md @@ -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 . + +## 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:** `/.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 `/.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..enabled`, `plugins..settings` | — | Global | Not core local config; plugins may read their own project files | Reload browser tab | +| Keyboard shortcuts | `shortcuts.` | — | 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..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. diff --git a/docs/faq.html b/docs/faq.html index 1742a7d..6e30e6d 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ
@@ -305,6 +306,7 @@ Remote-first Fleet Install + Config Plugins Issues diff --git a/docs/index.html b/docs/index.html index 2fb873b..bfa5fce 100644 --- a/docs/index.html +++ b/docs/index.html @@ -66,6 +66,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -349,6 +350,7 @@ Remote-first Fleet Install + Config Plugins FAQ npm diff --git a/docs/install.html b/docs/install.html index cfddc18..a304eb0 100644 --- a/docs/install.html +++ b/docs/install.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -265,27 +266,33 @@

- Default config + Common config 
{
   "host": "127.0.0.1",
   "port": 8504,
-  "allowedHosts": []
+  "pathAccess": {
+    "allowedPaths": ["~/SDKs", "/opt/reference"]
+  },
+  "spawnSessions": true,
+  "subsessions": false
 }

- The web server defaults to 127.0.0.1:8504 and stores PI WEB state in ~/.pi-web. + Use Settings → General for host, port, and external filesystem roots; Settings → Session daemon + for agent-spawn tools; Settings → Plugins for plugin enablement; and Settings → Keyboard + for shortcut overrides. +

+
+ Need the full schema, restart rules, project-local .pi-web/config.json, path access details, and + environment variable reference? Read the configuration reference. +
+

+ The web server defaults to 127.0.0.1:8504, and PI WEB-managed state defaults to + ~/.pi-web. External filesystem paths are denied by default unless listed in + pathAccess.allowedPaths.

-
@@ -334,6 +341,7 @@ Home Remote-first Fleet + Config Plugins FAQ GitHub diff --git a/docs/machines.html b/docs/machines.html index 4d7005e..665f222 100644 --- a/docs/machines.html +++ b/docs/machines.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -289,6 +290,7 @@ PI WEB gateway you opened Home Remote-first Install + Config Plugins FAQ GitHub diff --git a/docs/plugins.html b/docs/plugins.html index 53a2936..8068d5b 100644 --- a/docs/plugins.html +++ b/docs/plugins.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -430,6 +431,7 @@ After editing, check the manifest endpoint and browser-console failure cases.Remote-first Fleet Install + Config FAQ GitHub diff --git a/docs/remote-first.html b/docs/remote-first.html index 4943dce..fd7b5fd 100644 --- a/docs/remote-first.html +++ b/docs/remote-first.html @@ -50,6 +50,7 @@ Remote-first Fleet Install + Config Plugins FAQ @@ -206,6 +207,7 @@ Home Fleet Install + Config Plugins FAQ GitHub diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 6913ebc..27b7161 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -4,6 +4,7 @@ https://pi-web.dev/remote-first https://pi-web.dev/machines https://pi-web.dev/install + https://pi-web.dev/config https://pi-web.dev/plugins https://pi-web.dev/faq diff --git a/docs/styles.css b/docs/styles.css index 95b99d7..9ea31df 100644 --- a/docs/styles.css +++ b/docs/styles.css @@ -847,6 +847,60 @@ code .comment, font-size: 1.25rem; } +.table-scroll { + overflow-x: auto; + margin: 16px 0; + border: 1px solid var(--line); + background: var(--panel); +} + +.doc-content table { + width: 100%; + min-width: 860px; + border-collapse: collapse; +} + +.doc-content th, +.doc-content td { + padding: 12px 14px; + border-bottom: 1px solid var(--line); + text-align: left; + vertical-align: top; +} + +.doc-content th { + background: var(--panel-strong); + color: var(--text); + font-size: 0.78rem; + letter-spacing: 0.05em; + text-transform: uppercase; +} + +.doc-content .table-section th { + border-top: 2px solid var(--line-bright); + border-bottom-color: var(--line-bright); + background: var(--panel-strong); + color: var(--text); + letter-spacing: 0.08em; +} + +.doc-content td { + color: var(--muted); +} + +.doc-content td:first-child { + color: var(--text); + font-weight: 700; +} + +.doc-content tr:last-child td { + border-bottom: 0; +} + +.doc-content table code { + white-space: nowrap; +} + .code-card { overflow: hidden; margin: 16px 0; diff --git a/package.json b/package.json index ac172e4..d57a16b 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "LICENSE", "extensions", "docs/plugins.md", + "docs/config.md", "docs/assets", "plugin-api.d.ts", "plugin-api/unstable.d.ts" diff --git a/src/cli.ts b/src/cli.ts index d7f9dea..75d2c64 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -386,20 +386,21 @@ function restartOrder(refs: ServiceRef[]): ServiceRef[] { } function productionServiceDefinitions(options: InstallOptions, configPath: string, executables: ServiceExecutables): ServiceDefinition[] { + const environment = configEnvironment(options, configPath); return [ { ...serviceRefs.sessiond, description: "PI WEB session daemon", shellCommand: `exec ${executables.sessiond.command}`, restart: "on-failure", - environment: {}, + environment, }, { ...serviceRefs.web, description: "PI WEB server", shellCommand: `exec ${executables.web.command}`, restart: "on-failure", - environment: configEnvironment(options, configPath), + environment, after: ["sessiond"], wants: ["sessiond"], }, @@ -429,13 +430,14 @@ function validateDevCheckout(root: string): void { } function devServiceDefinitions(options: InstallOptions, configPath: string, root: string): ServiceDefinition[] { + const environment = configEnvironment(options, configPath); return [ { ...serviceRefs.sessiond, description: "PI WEB session daemon (dev)", shellCommand: "exec npm run start:sessiond", restart: "never", - environment: {}, + environment, workingDirectory: root, }, { @@ -443,7 +445,7 @@ function devServiceDefinitions(options: InstallOptions, configPath: string, root description: "PI WEB UI dev server", shellCommand: `exec /usr/bin/env bash -c ${serviceShellQuote('trap "kill 0" EXIT; npm run dev:web & npm run dev:client & wait')}`, restart: "never", - environment: configEnvironment(options, configPath), + environment, after: ["sessiond"], wants: ["sessiond"], workingDirectory: root, diff --git a/src/server/sessiond.ts b/src/server/sessiond.ts index 62a17b3..f4cc36e 100644 --- a/src/server/sessiond.ts +++ b/src/server/sessiond.ts @@ -21,13 +21,13 @@ import { getPiWebRuntimeComponent } from "./piWebStatus.js"; import { SESSIOND_RUNTIME_CAPABILITIES } from "../shared/capabilities.js"; import { effectivePiWebConfig, maxUploadBytes, spawnSessionsEnabled, subsessionsEnabled } from "../config.js"; -const app = Fastify({ logger: true, bodyLimit: maxUploadBytes() }); +const { config } = effectivePiWebConfig(); +const app = Fastify({ logger: true, bodyLimit: maxUploadBytes(process.env, config) }); await app.register(fastifyWebsocket); const eventHub = new SessionEventHub(); const workspaceActivity = new WorkspaceActivityService(eventHub); const auth = new AuthService(); -const { config } = effectivePiWebConfig(); const spawnTargets = spawnSessionsEnabled(process.env, config) ? new ProjectScopedSpawnTargetResolver({ projects: new ProjectService(new ProjectStore()), workspaces: new WorkspaceService() }) : undefined;