Archived
docs: align package management website docs
This commit is contained in:
Federico Jaramillo Martinez
+66
-17
@@ -3,10 +3,10 @@
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Configure PI WEB — config files, paths, and session tools</title>
|
||||
<title>Configure PI WEB — config files, uploads, paths, and session tools</title>
|
||||
<meta
|
||||
name="description"
|
||||
content="Configure PI WEB config files, external path access, session daemon tools, plugins, shortcuts, uploads, and runtime environment variables."
|
||||
content="Configure PI WEB config files, external path access, manual upload defaults, session daemon tools, plugins, shortcuts, and runtime environment variables."
|
||||
/>
|
||||
<link rel="canonical" href="https://pi-web.dev/config" />
|
||||
<meta property="og:type" content="website" />
|
||||
@@ -14,7 +14,7 @@
|
||||
<meta property="og:title" content="Configure PI WEB" />
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Reference for PI WEB config files, path access allowlists, session daemon options, plugins, shortcuts, uploads, and environment variables."
|
||||
content="Reference for PI WEB config files, path access allowlists, manual upload defaults, session daemon options, plugins, shortcuts, and environment variables."
|
||||
/>
|
||||
<meta property="og:url" content="https://pi-web.dev/config" />
|
||||
<meta property="og:image" content="https://pi-web.dev/assets/pi-web-banner.png" />
|
||||
@@ -23,7 +23,7 @@
|
||||
<meta name="twitter:title" content="Configure PI WEB" />
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Reference for PI WEB config files, path access allowlists, session daemon options, plugins, shortcuts, uploads, and environment variables."
|
||||
content="Reference for PI WEB config files, path access allowlists, manual upload defaults, session daemon options, plugins, shortcuts, and environment variables."
|
||||
/>
|
||||
<meta name="twitter:image" content="https://pi-web.dev/assets/pi-web-banner.png" />
|
||||
<link rel="icon" type="image/svg+xml" href="assets/favicon.svg" />
|
||||
@@ -81,7 +81,7 @@
|
||||
<p>
|
||||
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,
|
||||
upload limits, and session-daemon tools.
|
||||
manual upload defaults, upload limits, and session-daemon tools.
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
@@ -96,6 +96,7 @@
|
||||
<a href="#project-config">Project config</a>
|
||||
<a href="#keys">Config matrix</a>
|
||||
<a href="#path-access">External path access</a>
|
||||
<a href="#manual-uploads">Manual uploads</a>
|
||||
<a href="#session-tools">Session tools</a>
|
||||
<a href="#completion-tools">Completion tools</a>
|
||||
</aside>
|
||||
@@ -113,10 +114,11 @@
|
||||
config by opening that machine directly or changing files on that machine.
|
||||
</p>
|
||||
<p>
|
||||
Pi package settings are separate from PI WEB config. They live in Pi's package-manager settings and are
|
||||
managed by Pi (<code>pi install</code>, <code>pi remove</code>, <code>pi update</code>) or
|
||||
<strong>Settings → Pi packages</strong>. The PI WEB <code>plugins</code> config key only enables or
|
||||
disables discovered PI WEB browser plugins.
|
||||
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 (<code>pi install</code>, <code>pi remove</code>, <code>pi update</code>) or
|
||||
<strong>Settings → Pi packages</strong>. In a federated setup, <strong>Settings → Pi packages</strong>
|
||||
targets the currently selected machine; the PI WEB <code>plugins</code> config key only enables or
|
||||
disables discovered PI WEB browser plugins for the gateway you opened.
|
||||
</p>
|
||||
<p>
|
||||
If you installed services with a custom config path, rerun
|
||||
@@ -128,10 +130,14 @@
|
||||
|
||||
<section id="precedence">
|
||||
<h2>Precedence and reloads</h2>
|
||||
<p>Runtime values are resolved in this order:</p>
|
||||
<p>Machine-global runtime values are resolved in this order:</p>
|
||||
<div class="code-card">
|
||||
<pre><code>defaults → config file → environment overrides</code></pre>
|
||||
<pre><code>defaults → global config file → environment overrides</code></pre>
|
||||
</div>
|
||||
<p>
|
||||
Supported project-local settings are then applied for that project's workspaces. For upload defaults,
|
||||
<code><project>/.pi-web/config.json</code> overrides the global value.
|
||||
</p>
|
||||
<p>
|
||||
Environment overrides include <code>PI_WEB_HOST</code>, <code>PI_WEB_PORT</code> / <code>PORT</code>,
|
||||
<code>PI_WEB_ALLOWED_HOSTS</code>, <code>PI_WEB_MAX_UPLOAD_BYTES</code>, <code>PI_WEB_SPAWN_SESSIONS</code>,
|
||||
@@ -142,8 +148,9 @@
|
||||
<li><code>maxUploadBytes</code>: restart both the web/API process and the session daemon.</li>
|
||||
<li><code>spawnSessions</code> / <code>subsessions</code>: restart the session daemon.</li>
|
||||
<li><code>pathAccess</code>: applies on the next request; existing file views may need a browser refresh.</li>
|
||||
<li><code>uploads.defaultFolder</code>: applies to newly opened Files upload dialogs and new direct drag/drop batches after config/workspace refresh.</li>
|
||||
<li><code>plugins</code>: reload the browser tab after changing PI WEB plugin enablement.</li>
|
||||
<li>Pi package install/remove/update: not a PI WEB config key; after a mutation, type <code>/reload</code> in each idle PI WEB session 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.</li>
|
||||
<li>Pi package install/remove/update: not a PI WEB config key; after a mutation, type <code>/reload</code> 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.</li>
|
||||
<li><code>shortcuts</code>: saved settings apply in the browser after config refresh/save.</li>
|
||||
</ul>
|
||||
</section>
|
||||
@@ -167,6 +174,9 @@
|
||||
"pathAccess": {
|
||||
"allowedPaths": ["~/SDKs", "/opt/reference"]
|
||||
},
|
||||
"uploads": {
|
||||
"defaultFolder": ".pi-web/uploads"
|
||||
},
|
||||
"maxUploadBytes": 67108864,
|
||||
"spawnSessions": true,
|
||||
"subsessions": false,
|
||||
@@ -187,8 +197,7 @@
|
||||
<h2>Project-local config</h2>
|
||||
<p>
|
||||
Project-local config lives at <code><project>/.pi-web/config.json</code>. Use it for settings that should
|
||||
follow a repository. When a project config defines <code>pathAccess</code>, PI WEB merges it after the
|
||||
global path list.
|
||||
follow a repository.
|
||||
</p>
|
||||
<div class="code-card">
|
||||
<div class="copy-row">
|
||||
@@ -199,13 +208,25 @@
|
||||
"version": 1,
|
||||
"pathAccess": {
|
||||
"allowedPaths": ["~/SDKs", "/opt/reference"]
|
||||
},
|
||||
"uploads": {
|
||||
"defaultFolder": "manual/uploads"
|
||||
}
|
||||
}</code></pre>
|
||||
</div>
|
||||
<p>
|
||||
Project-local <code>pathAccess.allowedPaths</code> entries must still be host-absolute or
|
||||
<code>~</code>-prefixed; relative roots are not supported. Plugins may own separate project files, such as
|
||||
<code>.pi-web/tasks.json</code> for the built-in Workspace Tasks plugin.
|
||||
Project-local <code>pathAccess.allowedPaths</code> entries are merged after the global list and deduplicated.
|
||||
Paths must still be host-absolute or <code>~</code>-prefixed; relative roots are not supported.
|
||||
</p>
|
||||
<p>
|
||||
Project-local <code>uploads.defaultFolder</code> 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.
|
||||
</p>
|
||||
<p>
|
||||
Plugins may own separate project files, such as <code>.pi-web/tasks.json</code> for the built-in Workspace
|
||||
Tasks plugin.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
@@ -262,6 +283,14 @@
|
||||
<td><strong>Merges:</strong> global roots first, then project roots; duplicates removed</td>
|
||||
<td>Next file request; refresh existing views if needed</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Manual file upload default folder</td>
|
||||
<td><code>uploads.defaultFolder</code></td>
|
||||
<td>—</td>
|
||||
<td>Global + project</td>
|
||||
<td><strong>Overrides:</strong> project value wins for workspaces in that project; otherwise global/default applies</td>
|
||||
<td>New Upload dialogs and direct drag/drop batches after config/workspace refresh</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Upload/body limit</td>
|
||||
<td><code>maxUploadBytes</code></td>
|
||||
@@ -428,6 +457,26 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="manual-uploads">
|
||||
<h2>Manual upload defaults</h2>
|
||||
<p>
|
||||
The Files panel can upload files by dropping them onto the panel or by using the toolbar
|
||||
<strong>Upload</strong> button. <code>uploads.defaultFolder</code> sets the workspace-effective default
|
||||
destination. The built-in default is <code>.pi-web/uploads</code>; a project-local value overrides the
|
||||
global value for workspaces in that project.
|
||||
</p>
|
||||
<p>
|
||||
The value must be a non-empty workspace-relative folder. PI WEB normalizes repeated separators and
|
||||
backslashes to <code>/</code>, and rejects absolute paths or <code>..</code> traversal. In the upload
|
||||
dialog only, clearing the destination field uploads that batch to the workspace root.
|
||||
</p>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section id="session-tools">
|
||||
<h2>Session daemon tools</h2>
|
||||
<h3><code>spawnSessions</code></h3>
|
||||
|
||||
+1
-1
@@ -251,7 +251,7 @@
|
||||
<p>
|
||||
Your device is replaceable. The sessions are not. Move between laptop, phone, tablet, and desktop
|
||||
without moving the development environment. Under the hood, PI WEB coordinates the running sessions,
|
||||
files, terminals, and remote machines like a browser-based control plane.
|
||||
files, terminals, Pi package management, and remote machines like a browser-based control plane.
|
||||
</p>
|
||||
</article>
|
||||
<article class="card">
|
||||
|
||||
+9
-7
@@ -6,7 +6,7 @@
|
||||
<title>PI WEB fleet — remote Pi web UI machines</title>
|
||||
<meta
|
||||
name="description"
|
||||
content="Connect trusted PI WEB runtimes through machine federation so one web UI can supervise local and remote projects, sessions, files, git state, terminals, and plugins."
|
||||
content="Connect trusted PI WEB runtimes through machine federation so one web UI can supervise local and remote projects, sessions, files, git state, terminals, Pi packages, and plugins."
|
||||
/>
|
||||
<link rel="canonical" href="https://pi-web.dev/machines" />
|
||||
<meta property="og:type" content="website" />
|
||||
@@ -81,7 +81,7 @@
|
||||
<p>
|
||||
Most PI WEB setups only need one runtime. When you do have more than one, machine federation lets the PI WEB
|
||||
instance you opened act as a gateway to other trusted runtimes while each machine keeps its own repositories,
|
||||
credentials, sessions, and plugins.
|
||||
credentials, sessions, Pi package settings, and plugins.
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
@@ -111,7 +111,7 @@
|
||||
<p>
|
||||
After registration, the browser keeps talking to the current PI WEB origin. The gateway contacts the
|
||||
selected remote PI WEB server and routes that machine's projects, workspaces, sessions, files, git state,
|
||||
activity, and terminals to the browser UI.
|
||||
activity, terminals, and Pi package-management operations to the browser UI.
|
||||
</p>
|
||||
<div class="code-card">
|
||||
<div class="copy-row">
|
||||
@@ -125,7 +125,7 @@ PI WEB gateway you opened
|
||||
│
|
||||
├─ [ Remote PI WEB runtime A ]
|
||||
│ ↓ selected machine
|
||||
│ projects, workspaces, sessions, terminals, plugins
|
||||
│ projects, workspaces, sessions, terminals, Pi packages, plugins
|
||||
│
|
||||
└─ [ Remote PI WEB runtime B ]</code></pre>
|
||||
</div>
|
||||
@@ -151,7 +151,7 @@ PI WEB gateway you opened
|
||||
<article class="card">
|
||||
<div class="card-icon">⌁</div>
|
||||
<h3>Local ownership</h3>
|
||||
<p>Each target machine keeps its own Pi auth, sessions, worktrees, terminal state, and plugins.</p>
|
||||
<p>Each target machine keeps its own Pi auth, sessions, worktrees, terminal state, Pi package settings, and plugins.</p>
|
||||
</article>
|
||||
</div>
|
||||
</section>
|
||||
@@ -213,6 +213,7 @@ PI WEB gateway you opened
|
||||
<li>Pi sessions, transcripts, prompts, model controls, and commands.</li>
|
||||
<li>Activity indicators and realtime updates.</li>
|
||||
<li>Terminals and terminal command runs.</li>
|
||||
<li>Pi package listing, install, remove, and update from <strong>Settings → Pi packages</strong> when supported by the target PI WEB runtime.</li>
|
||||
<li>Remote plugins from the selected machine.</li>
|
||||
</ul>
|
||||
</section>
|
||||
@@ -220,8 +221,9 @@ PI WEB gateway you opened
|
||||
<section id="auth-credentials">
|
||||
<h2>Credentials stay on the target machine</h2>
|
||||
<p>
|
||||
Model-provider credentials, Pi configuration, OAuth state, repositories, and active session runtimes stay
|
||||
on the selected target machine. The gateway does not copy them into its own Pi configuration.
|
||||
Model-provider credentials, Pi configuration, Pi package-manager settings, OAuth state, repositories, and
|
||||
active session runtimes stay on the selected target machine. The gateway does not copy them into its own
|
||||
Pi configuration.
|
||||
</p>
|
||||
<ul>
|
||||
<li>API-key provider configuration can be proxied through the gateway.</li>
|
||||
|
||||
+16
-6
@@ -144,13 +144,21 @@
|
||||
local path. PI WEB uses Pi's default package location, equivalent to <code>pi install <source></code>,
|
||||
and does not ask for an install location.
|
||||
</p>
|
||||
<p>
|
||||
When machine federation is enabled, <strong>Settings → Pi packages</strong> targets the currently selected
|
||||
machine. The panel labels whether changes will run on the local/gateway machine or on a selected remote
|
||||
PI WEB machine. If an older or unavailable remote PI WEB server does not expose package-management routes,
|
||||
PI WEB reports the package management operation as unsupported or unavailable instead of silently falling
|
||||
back to the gateway.
|
||||
</p>
|
||||
<p>
|
||||
Use <strong>Settings → PI WEB plugins</strong> to enable or disable discovered PI WEB browser plugins
|
||||
before the browser imports them. After installing, removing, or updating a Pi package, type
|
||||
<code>/reload</code> in each idle PI WEB session 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 newly discovered or changed PI WEB browser plugins. A routine session daemon restart
|
||||
is not required.
|
||||
before the browser imports them. This plugin enablement surface is for the PI WEB gateway you opened; to
|
||||
change remote plugin enablement, open that remote machine directly or edit its PI WEB config on that
|
||||
machine. After installing, removing, or updating a Pi package, type <code>/reload</code> 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 newly discovered or changed PI WEB browser plugins. A routine session daemon restart is not required.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
@@ -323,7 +331,9 @@ After editing, check the manifest endpoint and browser-console failure cases.</c
|
||||
</p>
|
||||
<p>
|
||||
This surface is only for PI WEB plugin enablement. To install, remove, or update Pi packages that may
|
||||
provide plugins or other Pi resources, use <strong>Settings → Pi packages</strong>.
|
||||
provide plugins or other Pi resources, use <strong>Settings → Pi packages</strong>. In a federated setup,
|
||||
the Pi packages panel targets the selected machine; the PI WEB plugins panel still controls gateway plugin
|
||||
enablement.
|
||||
</p>
|
||||
<div class="code-card">
|
||||
<div class="copy-row">
|
||||
|
||||
Reference in New Issue
Block a user