Skip to content

Add configurable agent runtime settings #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jeffscottward wants to merge 3 commits into from
Closed

Add configurable agent runtime settings #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8bdf11a
refactor: add session route service seam
jeffscottward Jun 25, 2026
f11f95e
feat: add OMP runtime support
jeffscottward Jun 26, 2026
48f3d44
fix: generalize agent runtime config
jeffscottward Jun 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/agent-runtime-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@jmfederico/pi-web": patch
---

Add configurable Pi-compatible agent command and state-directory settings for diagnostics, update checks, auth, models, sessions, and settings.
97 changes: 85 additions & 12 deletions docs/config.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ <h1>Configure PI WEB where your agents work.</h1>
<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,
manual upload defaults, upload limits, and session-daemon tools.
manual upload defaults, upload limits, agent runtime selection, and session-daemon tools.
</p>
</div>
</section>
Expand All @@ -97,6 +97,7 @@ <h1>Configure PI WEB where your agents work.</h1>
<a href="#keys">Config matrix</a>
<a href="#path-access">External path access</a>
<a href="#manual-uploads">Manual uploads</a>
<a href="#agent-runtime">Agent runtime</a>
<a href="#session-tools">Session tools</a>
<a href="#completion-tools">Completion tools</a>
</aside>
Expand Down Expand Up @@ -145,12 +146,17 @@ <h2>Precedence and reloads</h2>
</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>,
and <code>PI_WEB_SUBSESSIONS</code>.
<code>PI_WEB_ALLOWED_HOSTS</code>, <code>PI_WEB_MAX_UPLOAD_BYTES</code>, <code>PI_WEB_AGENT_COMMAND</code>,
<code>PI_WEB_AGENT_DIR</code>, <code>PI_WEB_AGENT_SESSION_DIR</code>,
<code>PI_CODING_AGENT_DIR</code> / <code>PI_CODING_AGENT_SESSION_DIR</code> for the default
<code>pi</code> command, the selected non-<code>pi</code> command's
<code>&lt;COMMAND&gt;_CODING_AGENT_DIR</code> / <code>&lt;COMMAND&gt;_CODING_AGENT_SESSION_DIR</code>,
<code>PI_WEB_SPAWN_SESSIONS</code>, and <code>PI_WEB_SUBSESSIONS</code>.
</p>
<ul>
<li><code>host</code> / <code>port</code>: restart the gateway web/API service or process.</li>
<li><code>maxUploadBytes</code>: restart both the web/API process and the session daemon on that machine.</li>
<li><code>agent.command</code> / <code>agent.dir</code>: restart the web/API process and the session daemon on that machine.</li>
<li><code>spawnSessions</code> / <code>subsessions</code>: restart the session daemon on that machine.</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>
Expand Down Expand Up @@ -184,6 +190,10 @@ <h2>Global config example</h2>
"defaultFolder": ".pi-web/uploads"
},
"maxUploadBytes": 67108864,
"agent": {
"command": "pi",
"dir": "~/.pi/agent"
},
"spawnSessions": true,
"subsessions": false,
"plugins": {
Expand Down Expand Up @@ -243,8 +253,8 @@ <h2>Config matrix</h2>
it, and whether project-local config overrides or merges with global config. Rows with JSON key
<code>—</code> are runtime-only environment variables, not config-file keys. <code>Global</code> means
machine-global. In Settings, selected-machine-safe global keys (<code>pathAccess</code>, <code>uploads</code>,
<code>maxUploadBytes</code>, <code>spawnSessions</code>, <code>subsessions</code>, and <code>plugins</code>)
are edited for the selected machine; gateway host/port/allowed-hosts, keyboard shortcuts, and machine
<code>maxUploadBytes</code>, <code>agent</code>, <code>spawnSessions</code>, <code>subsessions</code>,
and <code>plugins</code>) are edited for the selected machine; gateway host/port/allowed-hosts, keyboard shortcuts, and machine
registry/tokens stay local.
</p>
<div class="table-scroll" role="region" aria-label="PI WEB configuration matrix" tabindex="0">
Expand Down Expand Up @@ -309,6 +319,22 @@ <h2>Config matrix</h2>
<td>Not supported locally</td>
<td>Restart web/API and session daemon on that machine</td>
</tr>
<tr>
<td>Agent CLI command</td>
<td><code>agent.command</code></td>
<td><code>PI_WEB_AGENT_COMMAND</code></td>
<td>Global/session daemon</td>
<td>Not supported locally</td>
<td>Restart web/API and session daemon on that machine; affects doctor/status/update checks</td>
</tr>
<tr>
<td>Agent state directory</td>
<td><code>agent.dir</code></td>
<td><code>PI_WEB_AGENT_DIR</code>, <code>PI_CODING_AGENT_DIR</code> for <code>pi</code>, selected non-<code>pi</code> command's <code>&lt;COMMAND&gt;_CODING_AGENT_DIR</code></td>
<td>Global/session daemon</td>
<td>Not supported locally</td>
<td>Restart web/API and session daemon on that machine; affects auth, models, settings, and sessions</td>
</tr>
<tr>
<td>Agent can spawn sessions</td>
<td><code>spawnSessions</code></td>
Expand Down Expand Up @@ -415,18 +441,18 @@ <h2>Config matrix</h2>
<td>Restart web/API; advanced state override</td>
</tr>
<tr>
<td>Pi session storage directory</td>
<td>Agent session storage directory</td>
<td>—</td>
<td><code>PI_CODING_AGENT_SESSION_DIR</code></td>
<td>Pi/session daemon env</td>
<td><code>PI_WEB_AGENT_SESSION_DIR</code>, <code>PI_CODING_AGENT_SESSION_DIR</code> for <code>pi</code>, selected non-<code>pi</code> command's <code>&lt;COMMAND&gt;_CODING_AGENT_SESSION_DIR</code></td>
<td>Session daemon env</td>
<td>Not supported locally</td>
<td>Restart session daemon; follows Pi session priority</td>
<td>Restart session daemon; env-only session storage override</td>
</tr>
<tr>
<td>Pi agent config directory</td>
<td>Agent config directory</td>
<td>—</td>
<td><code>PI_CODING_AGENT_DIR</code></td>
<td>Pi/Web/API/session daemon env</td>
<td><code>PI_WEB_AGENT_DIR</code>, <code>PI_CODING_AGENT_DIR</code> for <code>pi</code>, selected non-<code>pi</code> command's <code>&lt;COMMAND&gt;_CODING_AGENT_DIR</code></td>
<td>Web/API + session daemon env</td>
<td>Not supported locally</td>
<td>Restart services</td>
</tr>
Expand Down Expand Up @@ -496,6 +522,53 @@ <h2>Manual upload defaults</h2>
</p>
</section>

<section id="agent-runtime">
<h2>Agent runtime</h2>
<p>
<code>agent.command</code> controls which Pi-compatible CLI PI WEB checks in doctor/status/update flows.
It defaults to <code>pi</code>. PI WEB's embedded session runtime still uses the bundled SDK path; changing
this command does not load a different session implementation.
</p>
<p>
<code>agent.dir</code> controls which compatible agent state directory PI WEB reads for auth providers,
model settings, settings, and session metadata. It defaults to <code>~/.pi/agent</code> only when the
selected command resolves to <code>pi</code>. For any other command, set <code>agent.dir</code>,
<code>PI_WEB_AGENT_DIR</code>, or the selected command's <code>&lt;COMMAND&gt;_CODING_AGENT_DIR</code> explicitly.
</p>
<div class="code-card">
<pre><code>{
"agent": {
"command": "my-pi-fork",
"dir": "/opt/my-pi-fork/agent"
}
}</code></pre>
</div>
<p>
For example, an OMP setup can use <code>"command": "omp"</code> with
<code>"dir": "~/.omp/agent"</code> and, if needed, <code>OMP_CODING_AGENT_DIR</code> /
<code>OMP_CODING_AGENT_SESSION_DIR</code> environment overrides.
</p>
<p>
Environment variables take precedence over the config file. <code>PI_WEB_AGENT_COMMAND</code> selects the
command, <code>PI_WEB_AGENT_DIR</code> sets the state directory for any command, and command-specific
variables are honored for compatible runtimes.
</p>
<p>
Command-specific environment names are derived from the selected command's basename by stripping common
executable extensions, replacing non-alphanumeric characters with underscores, and uppercasing the result.
For example, <code>my-pi-fork</code> uses <code>MY_PI_FORK_CODING_AGENT_DIR</code> and
<code>MY_PI_FORK_CODING_AGENT_SESSION_DIR</code>.
</p>
<p>
Session directory overrides are environment-only. Set <code>PI_WEB_AGENT_SESSION_DIR</code> or the selected
command's session variable when you need to override session storage separately from <code>agent.dir</code>.
</p>
<div class="callout warning">
Restart the web/API process and the session daemon after changing agent settings. The web/API process
captures diagnostics/package state at startup, and active session runtime ownership is intentionally long-lived.
</div>
</section>

<section id="session-tools">
<h2>Session daemon tools</h2>
<h3><code>spawnSessions</code></h3>
Expand Down
42 changes: 37 additions & 5 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 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, manual upload defaults, upload limits, and session-daemon tools.
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, manual upload defaults, upload limits, agent runtime selection, and session-daemon tools.

This file is the markdown reference for agents and package consumers. The website page is <https://pi-web.dev/config>.

Expand All @@ -27,12 +27,13 @@ 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`.
Environment overrides include `PI_WEB_HOST`, `PI_WEB_PORT` / `PORT`, `PI_WEB_ALLOWED_HOSTS`, `PI_WEB_MAX_UPLOAD_BYTES`, `PI_WEB_AGENT_COMMAND`, `PI_WEB_AGENT_DIR`, `PI_WEB_AGENT_SESSION_DIR`, `PI_CODING_AGENT_DIR` / `PI_CODING_AGENT_SESSION_DIR` for the default `pi` command, the selected non-`pi` command's `<COMMAND>_CODING_AGENT_DIR` / `<COMMAND>_CODING_AGENT_SESSION_DIR`, `PI_WEB_SPAWN_SESSIONS`, and `PI_WEB_SUBSESSIONS`.

Process restarts depend on the key:

- `host` / `port`: restart the gateway web/API service or process.
- `maxUploadBytes`: restart both the web/API process and the session daemon on that machine.
- `agent.command` / `agent.dir`: restart 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.
Expand All @@ -53,6 +54,10 @@ Process restarts depend on the key:
"defaultFolder": ".pi-web/uploads"
},
"maxUploadBytes": 67108864,
"agent": {
"command": "pi",
"dir": "~/.pi/agent"
},
"spawnSessions": true,
"subsessions": false,
"plugins": {
Expand Down Expand Up @@ -91,7 +96,7 @@ Plugins may own separate project files, such as `.pi-web/tasks.json` for the bui

## Configuration matrix

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.
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`, `agent`, `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 |
| --- | --- | --- | --- | --- | --- |
Expand All @@ -102,6 +107,8 @@ Rows with JSON key `—` are runtime-only environment variables, not config-file
| 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 CLI command | `agent.command` | `PI_WEB_AGENT_COMMAND` | Global/session daemon | Not supported locally | Restart web/API and session daemon on that machine; affects doctor/status/update checks |
| Agent state directory | `agent.dir` | `PI_WEB_AGENT_DIR`, `PI_CODING_AGENT_DIR` for `pi`, selected non-`pi` command's `<COMMAND>_CODING_AGENT_DIR` | Global/session daemon | Not supported locally | Restart web/API and session daemon on that machine; affects auth, models, settings, and sessions |
| 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 |
| Plugin enablement/settings | `plugins.<id>.enabled`, `plugins.<id>.settings` | — | Global | Not core local config; plugins may read their own project files | Reload browser tab |
Expand All @@ -116,8 +123,8 @@ Rows with JSON key `—` are runtime-only environment variables, not config-file
| 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 |
| Agent session storage directory | — | `PI_WEB_AGENT_SESSION_DIR`, `PI_CODING_AGENT_SESSION_DIR` for `pi`, selected non-`pi` command's `<COMMAND>_CODING_AGENT_SESSION_DIR` | Session daemon env | Not supported locally | Restart session daemon; env-only session storage override |
| Agent config directory | — | `PI_WEB_AGENT_DIR`, `PI_CODING_AGENT_DIR` for `pi`, selected non-`pi` command's `<COMMAND>_CODING_AGENT_DIR` | 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
Expand Down Expand Up @@ -165,6 +172,31 @@ For machine federation, Settings saves the global upload default on the selected

The per-request size limit is still controlled by `maxUploadBytes` / `PI_WEB_MAX_UPLOAD_BYTES` on the machine serving the upload.

### Agent runtime selection

`agent.command` controls which Pi-compatible CLI PI WEB checks in doctor/status/update flows. It defaults to `pi`. PI WEB's embedded session runtime still uses the bundled SDK path; changing this command does not load a different session implementation.

`agent.dir` controls which compatible agent state directory PI WEB reads for auth providers, model settings, settings, and session metadata. It defaults to `~/.pi/agent` only when the selected command resolves to `pi`. For any other command, set `agent.dir`, `PI_WEB_AGENT_DIR`, or the selected command's `<COMMAND>_CODING_AGENT_DIR` explicitly.

```json
{
"agent": {
"command": "my-pi-fork",
"dir": "/opt/my-pi-fork/agent"
}
}
```

For example, an OMP setup can use `"command": "omp"` with `"dir": "~/.omp/agent"` and, if needed, `OMP_CODING_AGENT_DIR` / `OMP_CODING_AGENT_SESSION_DIR` environment overrides.

Environment variables take precedence over the config file. `PI_WEB_AGENT_COMMAND` selects the command, `PI_WEB_AGENT_DIR` sets the state directory for any command, and command-specific variables such as `OMP_CODING_AGENT_DIR` are honored when the selected command is `omp`.

Command-specific environment names are derived from the selected command's basename by stripping common executable extensions, replacing non-alphanumeric characters with underscores, and uppercasing the result. For example, `my-pi-fork` uses `MY_PI_FORK_CODING_AGENT_DIR` and `MY_PI_FORK_CODING_AGENT_SESSION_DIR`.

Session directory overrides are environment-only. Set `PI_WEB_AGENT_SESSION_DIR` or the selected command's session variable (for example `OMP_CODING_AGENT_SESSION_DIR`) when you need to override session storage separately from `agent.dir`.

Restart the web/API process and the session daemon after changing agent settings. The web/API process captures diagnostics/package state at startup, and active session runtime ownership is intentionally long-lived.

### 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.
Expand Down
Loading