From 84a485d62e01502554733140be471d8dae0931f4 Mon Sep 17 00:00:00 2001
From: Jeff Scott Ward <jeffscottward@users.noreply.github.com>
Date: Fri, 26 Jun 2026 02:35:54 -0400
Subject: [PATCH]  feat: add OMP runtime support

---
 .changeset/omp-agent-runtime.md               |   5 +
 docs/config.html                              |  81 +++++++++++--
 docs/config.md                                |  37 +++++-
 src/cli.test.ts                               |  41 ++++++-
 src/cli.ts                                    |  26 ++--
 src/client/src/api/parsers.test.ts            |  12 +-
 src/client/src/api/parsers.ts                 |  21 +++-
 src/client/src/components/AuthDialog.ts       |   4 +-
 .../settings/SettingsSessiondPanel.ts         |  63 ++++++++++
 .../settings/settingsConfigDraft.test.ts      |   3 +-
 .../settings/settingsConfigDraft.ts           |   1 +
 src/config.test.ts                            |  47 +++++++-
 src/config.ts                                 | 114 +++++++++++++++++-
 src/server/app.test.ts                        |   2 +-
 src/server/app.ts                             |   8 +-
 src/server/configRoutes.test.ts               |   6 +-
 src/server/configRoutes.ts                    |  40 +++++-
 src/server/piWebStatus.test.ts                |  52 +++++++-
 src/server/piWebStatus.ts                     |  59 +++++----
 src/server/sessiond.ts                        |   8 +-
 src/server/sessions/authService.test.ts       |  27 ++++-
 src/server/sessions/authService.ts            |   9 +-
 .../sessions/piSessionManagerGateway.test.ts  |  25 ++++
 .../sessions/piSessionManagerGateway.ts       |  15 ++-
 src/server/sessions/piSessionService.ts       |   4 +-
 src/shared/apiTypes.ts                        |  12 ++
 26 files changed, 639 insertions(+), 83 deletions(-)
 create mode 100644 .changeset/omp-agent-runtime.md

diff --git a/.changeset/omp-agent-runtime.md b/.changeset/omp-agent-runtime.md
new file mode 100644
index 0000000..c270f40
--- /dev/null
+++ b/.changeset/omp-agent-runtime.md
@@ -0,0 +1,5 @@
+---
+"@jmfederico/pi-web": minor
+---
+
+Add configurable Pi-compatible agent runtime settings so PI WEB can target Oh My Pi (`omp`) state, auth, sessions, diagnostics, and update checks.
diff --git a/docs/config.html b/docs/config.html
index 0062f9c..82d6f3a 100644
--- a/docs/config.html
+++ b/docs/config.html
@@ -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, plugin enablement, file-explorer path access, upload
-            limits, and session-daemon tools.
+            limits, agent runtime selection, 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="#agent-runtime">Agent runtime</a>
             <a href="#session-tools">Session tools</a>
             <a href="#completion-tools">Completion tools</a>
           </aside>
@@ -128,13 +129,16 @@
               </div>
               <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>, <code>OMP_CODING_AGENT_DIR</code>,
+                <code>OMP_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 web/API service or process.</li>
                 <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>agent.command</code> / <code>agent.dir</code> / <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>plugins</code>: reload the browser tab after changing plugin enablement.</li>
                 <li><code>shortcuts</code>: saved settings apply in the browser after config refresh/save.</li>
@@ -160,6 +164,10 @@
     "allowedPaths": ["~/SDKs", "/opt/reference"]
   },
   "maxUploadBytes": 67108864,
+  "agent": {
+    "command": "omp",
+    "dir": "~/.omp/agent"
+  },
   "spawnSessions": true,
   "subsessions": false,
   "plugins": {
@@ -262,6 +270,22 @@
                       <td>Not supported locally</td>
                       <td>Restart web/API and session daemon</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 session daemon; 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>, <code>OMP_CODING_AGENT_DIR</code></td>
+                      <td>Global/session daemon</td>
+                      <td>Not supported locally</td>
+                      <td>Restart session daemon; affects auth, models, settings, and sessions</td>
+                    </tr>
                     <tr>
                       <td>Agent can spawn sessions</td>
                       <td><code>spawnSessions</code></td>
@@ -368,18 +392,18 @@
                       <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>, <code>OMP_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>, <code>OMP_CODING_AGENT_DIR</code></td>
+                      <td>Web/API + session daemon env</td>
                       <td>Not supported locally</td>
                       <td>Restart services</td>
                     </tr>
@@ -420,6 +444,41 @@
               </div>
             </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>; set it to <code>omp</code> when this machine should use Oh My Pi.
+              </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 the selected agent's conventional
+                directory (<code>~/.pi/agent</code> for <code>pi</code>, <code>~/.omp/agent</code> for <code>omp</code>).
+              </p>
+              <div class="code-card">
+                <pre><code>{
+  "agent": {
+    "command": "omp",
+    "dir": "~/.omp/agent"
+  }
+}</code></pre>
+              </div>
+              <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 such as <code>OMP_CODING_AGENT_DIR</code> are honored when the selected command is <code>omp</code>.
+              </p>
+              <p>
+                Session directory overrides are environment-only. Set <code>PI_WEB_AGENT_SESSION_DIR</code> or the selected
+                command's session variable (for example <code>OMP_CODING_AGENT_SESSION_DIR</code>) when you need to override
+                session storage separately from <code>agent.dir</code>.
+              </p>
+              <div class="callout warning">
+                Restart the session daemon after changing agent settings. The web/API process can display the new config
+                immediately, but active session runtime ownership is intentionally long-lived.
+              </div>
+            </section>
+
             <section id="session-tools">
               <h2>Session daemon tools</h2>
               <h3><code>spawnSessions</code></h3>
diff --git a/docs/config.md b/docs/config.md
index 2707a9c..fe9ba72 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -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>.
 
@@ -25,13 +25,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`, `OMP_CODING_AGENT_DIR`, `OMP_CODING_AGENT_SESSION_DIR`, `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.
+- `agent.command` / `agent.dir` / `spawnSessions` / `subsessions`: restart the session daemon.
 - `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 plugin enablement.
@@ -50,6 +50,10 @@ Process restarts depend on the key:
     "defaultFolder": ".pi-web/uploads"
   },
   "maxUploadBytes": 67108864,
+  "agent": {
+    "command": "omp",
+    "dir": "~/.omp/agent"
+  },
   "spawnSessions": true,
   "subsessions": false,
   "plugins": {
@@ -99,6 +103,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 |
+| Agent CLI command | `agent.command` | `PI_WEB_AGENT_COMMAND` | Global/session daemon | Not supported locally | Restart session daemon; affects doctor/status/update checks |
+| Agent state directory | `agent.dir` | `PI_WEB_AGENT_DIR`, `PI_CODING_AGENT_DIR`, `OMP_CODING_AGENT_DIR` | Global/session daemon | Not supported locally | Restart session daemon; affects auth, models, settings, and sessions |
 | 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 |
@@ -113,8 +119,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`, `OMP_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`, `OMP_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
@@ -160,6 +166,27 @@ For machine federation, current remote PI WEB servers return `workspace.effectiv
 
 The per-request size limit is still controlled by `maxUploadBytes` / `PI_WEB_MAX_UPLOAD_BYTES`.
 
+### Agent runtime selection
+
+`agent.command` controls which Pi-compatible CLI PI WEB checks in doctor/status/update flows. It defaults to `pi`; set it to `omp` when this machine should use Oh My Pi.
+
+`agent.dir` controls which compatible agent state directory PI WEB reads for auth providers, model settings, settings, and session metadata. It defaults to the selected agent's conventional directory (`~/.pi/agent` for `pi`, `~/.omp/agent` for `omp`).
+
+```json
+{
+  "agent": {
+    "command": "omp",
+    "dir": "~/.omp/agent"
+  }
+}
+```
+
+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`.
+
+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 session daemon after changing agent settings. The web/API process can display the new config immediately, but 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.
diff --git a/src/cli.test.ts b/src/cli.test.ts
index 72da8f8..065e55a 100644
--- a/src/cli.test.ts
+++ b/src/cli.test.ts
@@ -2,9 +2,11 @@ import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { commandWithVersionCheck, isCliEntrypoint } from "./cli.js";
+import { agentCommandForChecks, commandWithVersionCheck, isCliEntrypoint } from "./cli.js";
 
 const originalShell = process.env["SHELL"];
+const originalPiWebConfig = process.env["PI_WEB_CONFIG"];
+const originalPiWebAgentCommand = process.env["PI_WEB_AGENT_COMMAND"];
 
 afterEach(() => {
   if (originalShell === undefined) {
@@ -12,25 +14,56 @@ afterEach(() => {
   } else {
     process.env["SHELL"] = originalShell;
   }
+  if (originalPiWebConfig === undefined) {
+    delete process.env["PI_WEB_CONFIG"];
+  } else {
+    process.env["PI_WEB_CONFIG"] = originalPiWebConfig;
+  }
+  if (originalPiWebAgentCommand === undefined) {
+    delete process.env["PI_WEB_AGENT_COMMAND"];
+  } else {
+    process.env["PI_WEB_AGENT_COMMAND"] = originalPiWebAgentCommand;
+  }
 });
 
 describe("commandWithVersionCheck", () => {
   it("emits a POSIX subshell group for bash", () => {
     process.env["SHELL"] = "/bin/bash";
-    expect(commandWithVersionCheck("npm")).toBe("command -v npm && (npm --version 2>&1 || true)");
+    expect(commandWithVersionCheck("npm")).toBe("command -v 'npm' && ('npm' --version 2>&1 || true)");
   });
 
   it("emits a POSIX subshell group for zsh", () => {
     process.env["SHELL"] = "/bin/zsh";
-    expect(commandWithVersionCheck("pi")).toBe("command -v pi && (pi --version 2>&1 || true)");
+    expect(commandWithVersionCheck("pi")).toBe("command -v 'pi' && ('pi' --version 2>&1 || true)");
   });
 
   it("uses fish begin/end grouping instead of a POSIX subshell", () => {
     process.env["SHELL"] = "/usr/local/bin/fish";
     const command = commandWithVersionCheck("npm");
-    expect(command).toBe("command -v npm && begin; npm --version 2>&1 || true; end");
+    expect(command).toBe("command -v 'npm' && begin; 'npm' --version 2>&1 || true; end");
     expect(command).not.toContain("(");
   });
+
+  it("shell-quotes command words", () => {
+    process.env["SHELL"] = "/bin/bash";
+    expect(commandWithVersionCheck("/tmp/agent's/omp")).toBe("command -v '/tmp/agent'\\''s/omp' && ('/tmp/agent'\\''s/omp' --version 2>&1 || true)");
+  });
+});
+
+describe("agentCommandForChecks", () => {
+  it("reads the configured agent command for doctor checks", () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-web-cli-test-"));
+    try {
+      const configPath = join(dir, "config.json");
+      writeFileSync(configPath, `${JSON.stringify({ agent: { command: "omp" } })}\n`);
+      process.env["PI_WEB_CONFIG"] = configPath;
+      delete process.env["PI_WEB_AGENT_COMMAND"];
+
+      expect(agentCommandForChecks()).toBe("omp");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("isCliEntrypoint", () => {
diff --git a/src/cli.ts b/src/cli.ts
index 00f1409..90fa419 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -5,7 +5,7 @@ import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir, userInfo } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { defaultPiWebConfigPath, defaultPiWebDataDir, examplePiWebConfig } from "./config.js";
+import { defaultPiWebConfigPath, defaultPiWebDataDir, effectiveAgentConfig, effectivePiWebConfig, examplePiWebConfig } from "./config.js";
 import { packageVersion, printPiWebVersionReport } from "./piWebVersionReport.js";
 import { checkNodePtyDarwinSpawnHelper, formatNodePtyDarwinSpawnHelperCheck } from "./server/diagnostics/nodePtySpawnHelper.js";
 
@@ -178,7 +178,7 @@ function runQuiet(command: string, args: string[]): number {
 }
 
 function hasCommand(command: string): boolean {
-  return capture("/usr/bin/env", ["sh", "-c", `command -v ${command}`]).status === 0;
+  return capture("/usr/bin/env", ["sh", "-c", `command -v ${shellQuote(command)}`]).status === 0;
 }
 
 function isLingerEnabled(): boolean | undefined {
@@ -898,16 +898,21 @@ function systemdUserServiceShellCommand(command: string, cwd?: string): string[]
   ];
 }
 
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
 function commandCheck(command: string): string {
-  return `command -v ${command}`;
+  return `command -v ${shellQuote(command)}`;
 }
 
 export function commandWithVersionCheck(command: string): string {
   const found = commandCheck(command);
+  const commandWord = shellQuote(command);
   if (detectServiceShell().name === "fish") {
-    return `${found} && begin; ${command} --version 2>&1 || true; end`;
+    return `${found} && begin; ${commandWord} --version 2>&1 || true; end`;
   }
-  return `${found} && (${command} --version 2>&1 || true)`;
+  return `${found} && (${commandWord} --version 2>&1 || true)`;
 }
 
 function nodeVersionCheck(): string {
@@ -917,14 +922,19 @@ function nodeVersionCheck(): string {
   ].join(" && ");
 }
 
+export function agentCommandForChecks(env: NodeJS.ProcessEnv = process.env): string {
+  return effectiveAgentConfig(env, effectivePiWebConfig({ env }).config).command;
+}
+
 function doctorChecks(): Check[] {
   const shell = serviceShellLabel();
   const backend = currentServiceBackend();
+  const agentCommand = agentCommandForChecks();
   if (backend === undefined) {
     return [
       [`${shell} can find node >= 22`, serviceShellCommand(nodeVersionCheck())],
       [`${shell} can find npm`, serviceShellCommand(commandWithVersionCheck("npm"))],
-      [`${shell} can find pi`, serviceShellCommand(commandWithVersionCheck("pi"))],
+      [`${shell} can find ${agentCommand}`, serviceShellCommand(commandWithVersionCheck(agentCommand))],
     ];
   }
 
@@ -932,12 +942,12 @@ function doctorChecks(): Check[] {
     ...backendAvailabilityChecks(backend),
     ...baseShellChecks(backend),
     [`${shell} can find npm`, serviceShellCommand(commandWithVersionCheck("npm"))],
-    [`${shell} can find pi`, serviceShellCommand(commandWithVersionCheck("pi"))],
+    [`${shell} can find ${agentCommand}`, serviceShellCommand(commandWithVersionCheck(agentCommand))],
   ];
   const executables = resolveServiceExecutables(backend);
   checks.push(...executables.web.checks, ...executables.sessiond.checks);
   if (backend.kind === "systemd") {
-    checks.push([`systemd user ${shell} can find pi`, systemdUserServiceShellCommand(commandWithVersionCheck("pi"))]);
+    checks.push([`systemd user ${shell} can find ${agentCommand}`, systemdUserServiceShellCommand(commandWithVersionCheck(agentCommand))]);
   }
   return checks;
 }
diff --git a/src/client/src/api/parsers.test.ts b/src/client/src/api/parsers.test.ts
index 3d157e1..038d476 100644
--- a/src/client/src/api/parsers.test.ts
+++ b/src/client/src/api/parsers.test.ts
@@ -7,15 +7,15 @@ describe("API parsers", () => {
     expect(parsePiWebConfigResponse({
       path: "/tmp/config.json",
       exists: true,
-      config: { host: "0.0.0.0", port: 8504, allowedHosts: ["example.local"], shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { compact: true } } }, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: "manual/uploads" }, maxUploadBytes: 1234 },
-      effectiveConfig: { host: "127.0.0.1", port: 8504, allowedHosts: true, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: ".pi-web/uploads" } },
-      envOverrides: { host: true, port: false, allowedHosts: false, spawnSessions: false, subsessions: false },
+      config: { host: "0.0.0.0", port: 8504, allowedHosts: ["example.local"], shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { compact: true } } }, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: "manual/uploads" }, maxUploadBytes: 1234, agent: { command: "omp", dir: "~/.omp/agent" } },
+      effectiveConfig: { host: "127.0.0.1", port: 8504, allowedHosts: true, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: ".pi-web/uploads" }, agent: { command: "omp", dir: "/Users/dev/.omp/agent" } },
+      envOverrides: { host: true, port: false, allowedHosts: false, spawnSessions: false, subsessions: false, agentCommand: false, agentDir: true, agentSessionDir: false },
     })).toEqual({
       path: "/tmp/config.json",
       exists: true,
-      config: { host: "0.0.0.0", port: 8504, allowedHosts: ["example.local"], shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { compact: true } } }, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: "manual/uploads" }, maxUploadBytes: 1234 },
-      effectiveConfig: { host: "127.0.0.1", port: 8504, allowedHosts: true, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: ".pi-web/uploads" } },
-      envOverrides: { host: true, port: false, allowedHosts: false, spawnSessions: false, subsessions: false },
+      config: { host: "0.0.0.0", port: 8504, allowedHosts: ["example.local"], shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { compact: true } } }, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: "manual/uploads" }, maxUploadBytes: 1234, agent: { command: "omp", dir: "~/.omp/agent" } },
+      effectiveConfig: { host: "127.0.0.1", port: 8504, allowedHosts: true, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: ".pi-web/uploads" }, agent: { command: "omp", dir: "/Users/dev/.omp/agent" } },
+      envOverrides: { host: true, port: false, allowedHosts: false, spawnSessions: false, subsessions: false, agentCommand: false, agentDir: true, agentSessionDir: false },
     });
   });
 
diff --git a/src/client/src/api/parsers.ts b/src/client/src/api/parsers.ts
index 580db98..c64fc8d 100644
--- a/src/client/src/api/parsers.ts
+++ b/src/client/src/api/parsers.ts
@@ -531,11 +531,21 @@ function parsePiWebConfigValues(value: unknown): PiWebConfigValues {
     ...optionalField("pathAccess", optionalPathAccess(record["pathAccess"])),
     ...optionalField("uploads", optionalUploads(record["uploads"])),
     ...optionalField("maxUploadBytes", optionalNumber(record, "maxUploadBytes")),
+    ...optionalField("agent", optionalAgent(record["agent"])),
     ...optionalField("spawnSessions", optionalBoolean(record, "spawnSessions")),
     ...optionalField("subsessions", optionalBoolean(record, "subsessions")),
   };
 }
 
+function optionalAgent(value: unknown): PiWebConfigValues["agent"] | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value) || Array.isArray(value)) throw new Error("Invalid PI WEB agent field");
+  return {
+    ...optionalField("command", optionalString(value, "command")),
+    ...optionalField("dir", optionalString(value, "dir")),
+  };
+}
+
 function optionalAllowedHosts(value: unknown): PiWebConfigValues["allowedHosts"] | undefined {
   if (value === undefined) return undefined;
   if (value === true) return true;
@@ -598,7 +608,16 @@ function optionalPlugins(value: unknown): PiWebPluginConfigMap | undefined {
 
 function parsePiWebConfigEnvOverrides(value: unknown): PiWebConfigEnvOverrides {
   const record = requireRecord(value);
-  return { host: requireBoolean(record, "host"), port: requireBoolean(record, "port"), allowedHosts: requireBoolean(record, "allowedHosts"), spawnSessions: requireBoolean(record, "spawnSessions"), subsessions: requireBoolean(record, "subsessions") };
+  return {
+    host: requireBoolean(record, "host"),
+    port: requireBoolean(record, "port"),
+    allowedHosts: requireBoolean(record, "allowedHosts"),
+    spawnSessions: requireBoolean(record, "spawnSessions"),
+    subsessions: requireBoolean(record, "subsessions"),
+    agentCommand: optionalBoolean(record, "agentCommand") ?? false,
+    agentDir: optionalBoolean(record, "agentDir") ?? false,
+    agentSessionDir: optionalBoolean(record, "agentSessionDir") ?? false,
+  };
 }
 
 export function parsePiWebPluginsResponse(value: unknown): PiWebPluginsResponse {
diff --git a/src/client/src/components/AuthDialog.ts b/src/client/src/components/AuthDialog.ts
index 28a5698..6cb0bbf 100644
--- a/src/client/src/components/AuthDialog.ts
+++ b/src/client/src/components/AuthDialog.ts
@@ -54,13 +54,13 @@ export class AuthDialog extends LitElement {
       case "method": return html`
         <div class="options">
           <button @click=${() => { this.onChooseMethod?.("oauth"); }}><span>Use a subscription</span><small>ChatGPT Plus/Pro, Claude Pro/Max, or GitHub Copilot</small></button>
-          <button @click=${() => { this.onChooseMethod?.("api_key"); }}><span>Use an API key</span><small>Store an API key in pi auth.json</small></button>
+          <button @click=${() => { this.onChooseMethod?.("api_key"); }}><span>Use an API key</span><small>Store an API key in the configured agent auth.json</small></button>
         </div>
       `;
       case "providers": return html`<div class="options">${state.providers.length === 0 ? html`<div class="empty">No providers available.</div>` : state.providers.map((provider) => this.renderProviderButton(provider))}</div>`;
       case "apiKey": return html`
         <div class="form">
-          <p>Enter the API key for <strong>${state.provider.name}</strong>. It will be stored by pi in <code>auth.json</code>.</p>
+          <p>Enter the API key for <strong>${state.provider.name}</strong>. It will be stored in the configured agent <code>auth.json</code>.</p>
           <input type="password" autocomplete="off" placeholder="API key" .value=${state.value} @input=${(event: Event) => { if (event.target instanceof HTMLInputElement) this.onApiKeyInput?.(event.target.value); }}>
           ${state.error !== undefined && state.error !== "" ? html`<div class="error-text">${state.error}</div>` : null}
           <div class="actions"><button @click=${() => { this.cancel(); }}>Cancel</button><button class="primary" ?disabled=${state.saving === true} @click=${() => { this.onSaveApiKey?.(); }}>${state.saving === true ? "Saving…" : "Save API key"}</button></div>
diff --git a/src/client/src/components/settings/SettingsSessiondPanel.ts b/src/client/src/components/settings/SettingsSessiondPanel.ts
index 9c1c9e1..98824c0 100644
--- a/src/client/src/components/settings/SettingsSessiondPanel.ts
+++ b/src/client/src/components/settings/SettingsSessiondPanel.ts
@@ -21,6 +21,9 @@ export class SettingsSessiondPanel extends LitElement {
     const subsessionsOverridden = config?.envOverrides.subsessions === true;
     // Beta, off by default; also requires spawn to be enabled.
     const effectiveSubsessions = config?.effectiveConfig.subsessions === true && effectiveSpawn;
+    const agentCommandOverridden = config?.envOverrides.agentCommand === true;
+    const agentDirOverridden = config?.envOverrides.agentDir === true;
+    const effectiveAgent = config?.effectiveConfig.agent;
     return html`
       <div class="section-heading">
         <div>
@@ -36,6 +39,40 @@ export class SettingsSessiondPanel extends LitElement {
           <span>Config file</span>
           <code>${config?.path ?? "Unknown"}</code>
         </div>
+        <div class="field">
+          <span class="field-heading">
+            <span>Agent command for diagnostics</span>
+            ${agentCommandOverridden ? html`<span class="override-badge">environment override</span>` : null}
+          </span>
+          <input
+            class="text-input"
+            type="text"
+            autocomplete="off"
+            spellcheck="false"
+            .value=${config?.config.agent?.command ?? ""}
+            placeholder="pi"
+            ?disabled=${this.loading || this.saving || agentCommandOverridden}
+            @change=${(event: Event) => { void this.saveAgentField("command", event); }}
+          >
+          <small>Use <code>omp</code> to make doctor/update checks target Oh My Pi. The embedded session runtime remains PI WEB's SDK path, so this does not dynamically load a different agent implementation.</small>
+        </div>
+        <div class="field">
+          <span class="field-heading">
+            <span>Agent state directory</span>
+            ${agentDirOverridden ? html`<span class="override-badge">environment override</span>` : null}
+          </span>
+          <input
+            class="text-input"
+            type="text"
+            autocomplete="off"
+            spellcheck="false"
+            .value=${config?.config.agent?.dir ?? ""}
+            placeholder="~/.pi/agent or ~/.omp/agent"
+            ?disabled=${this.loading || this.saving || agentDirOverridden}
+            @change=${(event: Event) => { void this.saveAgentField("dir", event); }}
+          >
+          <small>Choose which compatible auth, models, settings, and sessions PI WEB reads. For OMP, set this to <code>~/.omp/agent</code>, then restart the session daemon.</small>
+        </div>
         <div class="field">
           <span class="field-heading">
             <span>Allow agents to start sessions</span>
@@ -72,6 +109,8 @@ export class SettingsSessiondPanel extends LitElement {
         <section class="effective-card" aria-label="Effective configuration summary">
           <h3>Effective after environment overrides</h3>
           <dl>
+            <div><dt>Agent command</dt><dd>${effectiveAgent?.command ?? html`<span class="muted">pi default</span>`}</dd></div>
+            <div><dt>Agent state</dt><dd>${effectiveAgent?.dir ?? html`<span class="muted">Pi default</span>`}</dd></div>
             <div><dt>Spawn sessions</dt><dd>${effectiveSpawn ? "Enabled" : html`<span class="muted">Disabled</span>`}</dd></div>
             <div><dt>Subsessions</dt><dd>${effectiveSubsessions ? "Enabled" : html`<span class="muted">Disabled</span>`}</dd></div>
           </dl>
@@ -86,6 +125,28 @@ export class SettingsSessiondPanel extends LitElement {
     return null;
   }
 
+  private async saveAgentField(field: "command" | "dir", event: Event): Promise<void> {
+    if (!(event.target instanceof HTMLInputElement)) return;
+    const value = event.target.value.trim();
+    const baseConfig = this.configResponse?.config ?? {};
+    const nextConfig: PiWebConfigValues = { ...baseConfig };
+    const nextAgent: NonNullable<PiWebConfigValues["agent"]> = { ...(baseConfig.agent ?? {}) };
+    if (field === "command") {
+      if (value === "") delete nextAgent.command;
+      else nextAgent.command = value;
+    } else if (value === "") {
+      delete nextAgent.dir;
+    } else {
+      nextAgent.dir = value;
+    }
+    if (nextAgent.command === undefined && nextAgent.dir === undefined) {
+      delete nextConfig.agent;
+    } else {
+      nextConfig.agent = nextAgent;
+    }
+    await this.onSave?.(nextConfig);
+  }
+
   private async toggleSpawnSessions(event: Event): Promise<void> {
     const enabled = event.target instanceof HTMLInputElement && event.target.checked;
     const baseConfig = this.configResponse?.config ?? {};
@@ -124,6 +185,8 @@ export class SettingsSessiondPanel extends LitElement {
     .field-heading { display: flex; align-items: center; gap: 8px; }
     .toggle { display: flex; align-items: center; gap: 9px; cursor: pointer; }
     .toggle input { width: 16px; height: 16px; }
+    .text-input { width: 100%; box-sizing: border-box; border: 1px solid var(--pi-border); border-radius: 8px; background: var(--pi-bg); color: var(--pi-text); padding: 8px 9px; font: 13px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .text-input:disabled { opacity: .65; cursor: not-allowed; }
     .toggle input:disabled { cursor: not-allowed; }
     .override-badge { border: 1px solid var(--pi-warning-border); border-radius: 999px; color: var(--pi-warning); background: var(--pi-warning-surface); padding: 2px 7px; font-size: 11px; font-weight: 600; text-transform: none; }
     .beta-badge { border: 1px solid var(--pi-border); border-radius: 999px; color: var(--pi-muted); background: var(--pi-bg); padding: 2px 7px; font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .04em; }
diff --git a/src/client/src/components/settings/settingsConfigDraft.test.ts b/src/client/src/components/settings/settingsConfigDraft.test.ts
index 69ebb53..d177add 100644
--- a/src/client/src/components/settings/settingsConfigDraft.test.ts
+++ b/src/client/src/components/settings/settingsConfigDraft.test.ts
@@ -20,7 +20,7 @@ describe("settings config drafts", () => {
       allowedHostsMode: "list",
       allowedHostsText: "example.local, 192.168.1.20\n",
       allowedPathsText: "/tmp\n~/SDKs\n",
-    }, { shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false } }, pathAccess: { allowedPaths: ["/old"] }, uploads: { defaultFolder: "manual/uploads" }, maxUploadBytes: 1234 })).toEqual({
+    }, { shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false } }, pathAccess: { allowedPaths: ["/old"] }, uploads: { defaultFolder: "manual/uploads" }, maxUploadBytes: 1234, agent: { command: "omp", dir: "~/.omp/agent" } })).toEqual({
       host: "127.0.0.1",
       port: 9000,
       allowedHosts: ["example.local", "192.168.1.20"],
@@ -29,6 +29,7 @@ describe("settings config drafts", () => {
       pathAccess: { allowedPaths: ["/tmp", "~/SDKs"] },
       uploads: { defaultFolder: "manual/uploads" },
       maxUploadBytes: 1234,
+      agent: { command: "omp", dir: "~/.omp/agent" },
     });
   });
 
diff --git a/src/client/src/components/settings/settingsConfigDraft.ts b/src/client/src/components/settings/settingsConfigDraft.ts
index 414ef16..4ce638e 100644
--- a/src/client/src/components/settings/settingsConfigDraft.ts
+++ b/src/client/src/components/settings/settingsConfigDraft.ts
@@ -30,6 +30,7 @@ export function configFromDraft(draft: ConfigDraft, baseConfig: PiWebConfigValue
     ...(baseConfig.maxUploadBytes === undefined ? {} : { maxUploadBytes: baseConfig.maxUploadBytes }),
     ...(baseConfig.spawnSessions === undefined ? {} : { spawnSessions: baseConfig.spawnSessions }),
     ...(baseConfig.subsessions === undefined ? {} : { subsessions: baseConfig.subsessions }),
+    ...(baseConfig.agent === undefined ? {} : { agent: baseConfig.agent }),
   };
   const host = draft.host.trim();
   const port = draft.port.trim();
diff --git a/src/config.test.ts b/src/config.test.ts
index c23c0c2..8cf115d 100644
--- a/src/config.test.ts
+++ b/src/config.test.ts
@@ -2,7 +2,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_UPLOADS_FOLDER, effectivePiWebConfig, loadPiWebConfig, maxUploadBytes, savePiWebConfig, spawnSessionsEnabled, subsessionsEnabled } from "./config.js";
+import { DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_UPLOADS_FOLDER, effectiveAgentConfig, effectivePiWebConfig, loadPiWebConfig, maxUploadBytes, savePiWebConfig, spawnSessionsEnabled, subsessionsEnabled } from "./config.js";
 
 let tempDir: string;
 let configPath: string;
@@ -49,6 +49,51 @@ describe("PI WEB config persistence", () => {
     expect(loadPiWebConfig(testOptions()).config.maxUploadBytes).toBe(1234);
   });
 
+  it("persists and reads custom agent runtime settings", () => {
+    savePiWebConfig({ agent: { command: "omp", dir: "~/.omp/agent" } }, testOptions());
+
+    expect(loadPiWebConfig(testOptions()).config.agent).toEqual({ command: "omp", dir: "~/.omp/agent" });
+  });
+
+  it("resolves OMP agent defaults from the configured command", () => {
+    expect(effectiveAgentConfig({ HOME: join(tempDir, ".home") }, { agent: { command: "omp" } })).toMatchObject({
+      command: "omp",
+      dir: join(tempDir, ".home", ".omp", "agent"),
+      sessionDirEnvKeys: ["PI_WEB_AGENT_SESSION_DIR", "OMP_CODING_AGENT_SESSION_DIR", "PI_CODING_AGENT_SESSION_DIR"],
+    });
+  });
+
+  it("lets PI WEB agent environment overrides take precedence", () => {
+    expect(effectiveAgentConfig({
+      PI_WEB_AGENT_COMMAND: "omp",
+      PI_WEB_AGENT_DIR: join(tempDir, "env-agent"),
+    }, { agent: { command: "pi", dir: join(tempDir, "config-agent") } })).toMatchObject({
+      command: "omp",
+      dir: join(tempDir, "env-agent"),
+    });
+  });
+
+  it("lets command-specific agent environment directories override config", () => {
+    expect(effectiveAgentConfig({
+      HOME: join(tempDir, ".home"),
+      OMP_CODING_AGENT_DIR: join(tempDir, "omp-env-agent"),
+    }, { agent: { command: "omp", dir: join(tempDir, "config-agent") } })).toMatchObject({
+      command: "omp",
+      dir: join(tempDir, "omp-env-agent"),
+    });
+  });
+
+  it("normalizes omp.exe to OMP environment keys", () => {
+    expect(effectiveAgentConfig({
+      HOME: join(tempDir, ".home"),
+      OMP_CODING_AGENT_DIR: join(tempDir, "omp-exe-env-agent"),
+    }, { agent: { command: "omp.exe", dir: join(tempDir, "config-agent") } })).toMatchObject({
+      command: "omp.exe",
+      dir: join(tempDir, "omp-exe-env-agent"),
+      sessionDirEnvKeys: ["PI_WEB_AGENT_SESSION_DIR", "OMP_CODING_AGENT_SESSION_DIR", "PI_CODING_AGENT_SESSION_DIR"],
+    });
+  });
+
   it("exposes the default upload folder in the effective config", () => {
     expect(effectivePiWebConfig(testOptions()).config.uploads).toEqual({ defaultFolder: DEFAULT_UPLOADS_FOLDER });
   });
diff --git a/src/config.ts b/src/config.ts
index b770fb1..8754c01 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -35,6 +35,42 @@ export const DEFAULT_MAX_UPLOAD_BYTES = 64 * 1024 * 1024;
 
 export const DEFAULT_UPLOADS_FOLDER = ".pi-web/uploads";
 
+export const DEFAULT_AGENT_COMMAND = "pi";
+export const PI_WEB_AGENT_COMMAND_ENV = "PI_WEB_AGENT_COMMAND";
+export const PI_WEB_AGENT_DIR_ENV = "PI_WEB_AGENT_DIR";
+export const PI_WEB_AGENT_SESSION_DIR_ENV = "PI_WEB_AGENT_SESSION_DIR";
+export const PI_CODING_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+export const PI_CODING_AGENT_SESSION_DIR_ENV = "PI_CODING_AGENT_SESSION_DIR";
+
+export interface EffectivePiWebAgentConfig {
+  command: string;
+  dir: string;
+  sessionDirEnvKeys: string[];
+}
+
+export function effectiveAgentConfig(env: NodeJS.ProcessEnv = process.env, config: Pick<PiWebConfig, "agent"> = {}, cwd = process.cwd()): EffectivePiWebAgentConfig {
+  const command = parseAgentCommand(env[PI_WEB_AGENT_COMMAND_ENV] ?? config.agent?.command ?? DEFAULT_AGENT_COMMAND, "agent.command", "environment");
+  const commandDirEnv = commandAgentDirEnv(command);
+  const configuredDir = env[PI_WEB_AGENT_DIR_ENV] ?? env[commandDirEnv] ?? config.agent?.dir ?? defaultAgentDirForCommand(command, env);
+  return {
+    command,
+    dir: resolveAgentDirPath(configuredDir, env, cwd, "agent.dir", "environment"),
+    sessionDirEnvKeys: agentSessionDirEnvKeys(command),
+  };
+}
+
+export function agentSessionDirEnvKeys(command = DEFAULT_AGENT_COMMAND): string[] {
+  return uniqueStrings([PI_WEB_AGENT_SESSION_DIR_ENV, commandSessionDirEnv(command), PI_CODING_AGENT_SESSION_DIR_ENV]);
+}
+
+export function hasAgentDirEnvOverride(env: NodeJS.ProcessEnv, command = DEFAULT_AGENT_COMMAND): boolean {
+  return isEnvSet(env[PI_WEB_AGENT_DIR_ENV]) || isEnvSet(env[commandAgentDirEnv(command)]);
+}
+
+export function hasAgentSessionDirEnvOverride(env: NodeJS.ProcessEnv, command = DEFAULT_AGENT_COMMAND): boolean {
+  return agentSessionDirEnvKeys(command).some((key) => isEnvSet(env[key]));
+}
+
 export function effectiveUploadsConfig(config: Pick<PiWebConfig, "uploads"> = {}): NonNullable<PiWebConfig["uploads"]> {
   return { defaultFolder: config.uploads?.defaultFolder ?? DEFAULT_UPLOADS_FOLDER };
 }
@@ -79,7 +115,7 @@ export function effectivePiWebConfig(options: LoadOptions = {}): LoadedPiWebConf
   const port = env["PI_WEB_PORT"] ?? env["PORT"];
   const allowedHosts = env["PI_WEB_ALLOWED_HOSTS"];
   const maxUpload = env["PI_WEB_MAX_UPLOAD_BYTES"];
-
+  const agent = effectiveAgentConfig(env, loaded.config, options.cwd ?? process.cwd());
   return {
     ...loaded,
     config: {
@@ -94,6 +130,7 @@ export function effectivePiWebConfig(options: LoadOptions = {}): LoadedPiWebConf
       spawnSessions: spawnSessionsEnabled(env, loaded.config),
       // Beta capability, resolved off by default.
       subsessions: subsessionsEnabled(env, loaded.config),
+      agent: { command: agent.command, dir: agent.dir },
     },
   };
 }
@@ -113,6 +150,7 @@ export function savePiWebConfig(config: PiWebConfig, options: LoadOptions = {}):
   delete existing["maxUploadBytes"];
   delete existing["spawnSessions"];
   delete existing["subsessions"];
+  delete existing["agent"];
   const merged = { ...existing, ...piWebConfigRecord(normalized) };
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
@@ -138,6 +176,7 @@ function piWebConfigRecord(config: PiWebConfig): Record<string, unknown> {
     ...(config.maxUploadBytes !== undefined ? { maxUploadBytes: config.maxUploadBytes } : {}),
     ...(config.spawnSessions !== undefined ? { spawnSessions: config.spawnSessions } : {}),
     ...(config.subsessions !== undefined ? { subsessions: config.subsessions } : {}),
+    ...(config.agent !== undefined ? { agent: config.agent } : {}),
   };
 }
 
@@ -153,6 +192,7 @@ function parsePiWebConfig(value: Record<string, unknown>, path: string): PiWebCo
     ...(value["maxUploadBytes"] !== undefined ? { maxUploadBytes: parseMaxUploadBytes(value["maxUploadBytes"], "maxUploadBytes", path) } : {}),
     ...(value["spawnSessions"] !== undefined ? { spawnSessions: parseSpawnSessions(value["spawnSessions"], path) } : {}),
     ...(value["subsessions"] !== undefined ? { subsessions: parseSubsessions(value["subsessions"], path) } : {}),
+    ...(value["agent"] !== undefined ? { agent: parseAgentConfig(value["agent"], path) } : {}),
   };
 }
 
@@ -203,6 +243,35 @@ function parseString(value: unknown, key: string, path: string): string {
   return value;
 }
 
+function parseAgentConfig(value: unknown, path: string): NonNullable<PiWebConfig["agent"]> {
+  if (!isRecord(value)) throw new Error(`PI WEB config agent must be an object: ${path}`);
+  const command = value["command"];
+  const dir = value["dir"];
+  return {
+    ...(command !== undefined ? { command: parseAgentCommand(command, "agent.command", path) } : {}),
+    ...(dir !== undefined ? { dir: parseAgentDir(dir, "agent.dir", path) } : {}),
+  };
+}
+
+function parseAgentCommand(value: unknown, key: string, path: string): string {
+  const command = parseString(value, key, path).trim();
+  if (command === "") throw new Error(`PI WEB config ${key} must be a non-empty string: ${path}`);
+  if (/[\s;&|`$<>]/u.test(command)) throw new Error(`PI WEB config ${key} must be a single command name or path without shell metacharacters: ${path}`);
+  return command;
+}
+
+function parseAgentDir(value: unknown, key: string, path: string): string {
+  const dir = parseString(value, key, path);
+  if (!isAbsoluteOrHomePath(dir)) throw new Error(`PI WEB config ${key} must be an absolute path or start with ~: ${path}`);
+  return dir;
+}
+
+function resolveAgentDirPath(value: string, env: NodeJS.ProcessEnv, cwd: string, key: string, path: string): string {
+  const parsed = parseAgentDir(value, key, path);
+  const expanded = expandHomePath(parsed, env);
+  return isAbsoluteLike(expanded) ? expanded : resolve(cwd, expanded);
+}
+
 function parsePort(value: unknown, key: string, path = "environment"): number {
   const port = typeof value === "number" ? value : typeof value === "string" && value !== "" ? Number(value) : NaN;
   if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`PI WEB config ${key} must be an integer from 1 to 65535: ${path}`);
@@ -252,6 +321,49 @@ function parseWorkspaceRelativeFolder(value: unknown, key: string, path: string)
   return parts.join("/");
 }
 
+
+function isAbsoluteOrHomePath(value: string): boolean {
+  return value === "~" || value.startsWith("~/") || value.startsWith("~\\") || isAbsoluteLike(value);
+}
+
+function expandHomePath(value: string, env: NodeJS.ProcessEnv): string {
+  const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir();
+  if (value === "~") return home;
+  if (value.startsWith("~/") || value.startsWith("~\\")) return join(home, value.slice(2));
+  return value;
+}
+
+function defaultAgentDirForCommand(command: string, env: NodeJS.ProcessEnv): string {
+  return expandHomePath(isOmpCommand(command) ? "~/.omp/agent" : "~/.pi/agent", env);
+}
+
+function commandAgentDirEnv(command: string): string {
+  const prefix = agentEnvPrefix(command);
+  return prefix === "PI" ? PI_CODING_AGENT_DIR_ENV : `${prefix}_CODING_AGENT_DIR`;
+}
+
+function commandSessionDirEnv(command: string): string {
+  return `${agentEnvPrefix(command)}_CODING_AGENT_SESSION_DIR`;
+}
+
+function agentEnvPrefix(command: string): string {
+  const name = command.split(/[\\/]/u).at(-1) ?? command;
+  const normalized = name.replace(/(?:\.[cm]?js|\.exe)$/iu, "").replace(/[^A-Za-z0-9]+/gu, "_").replace(/^_+|_+$/gu, "").toUpperCase();
+  return normalized === "" ? "PI" : normalized;
+}
+
+function isOmpCommand(command: string): boolean {
+  const name = command.split(/[\\/]/u).at(-1)?.toLowerCase();
+  return name === "omp" || name === "omp.exe";
+}
+
+function isEnvSet(value: string | undefined): boolean {
+  return value !== undefined && value !== "";
+}
+
+function uniqueStrings(values: readonly string[]): string[] {
+  return [...new Set(values)];
+}
 function isAbsoluteLike(value: string): boolean {
   const withForwardSlashes = value.replace(/\\/g, "/");
   return isAbsolute(value) || withForwardSlashes.startsWith("/") || /^[A-Za-z]:\//.test(withForwardSlashes);
diff --git a/src/server/app.test.ts b/src/server/app.test.ts
index 955c5f5..808b6fb 100644
--- a/src/server/app.test.ts
+++ b/src/server/app.test.ts
@@ -901,7 +901,7 @@ function piWebConfigResponse(config: PiWebConfigValues): PiWebConfigResponse {
     exists: false,
     config,
     effectiveConfig: config,
-    envOverrides: { host: false, port: false, allowedHosts: false, spawnSessions: false, subsessions: false },
+    envOverrides: { host: false, port: false, allowedHosts: false, spawnSessions: false, subsessions: false, agentCommand: false, agentDir: false, agentSessionDir: false },
   };
 }
 
diff --git a/src/server/app.ts b/src/server/app.ts
index c0bcf5d..9860f71 100644
--- a/src/server/app.ts
+++ b/src/server/app.ts
@@ -22,6 +22,7 @@ import { createFilePiWebConfigService, registerConfigRoutes, type PiWebConfigSer
 import { PiWebPluginService } from "./piWebPluginService.js";
 import { createPiWebStatusCache } from "./piWebStatusCache.js";
 import { getPiWebRuntime, getPiWebStatus, getPiWebVersionStatus } from "./piWebStatus.js";
+import { effectiveAgentConfig, effectivePiWebConfig } from "../config.js";
 import { MachineService } from "./machines/machineService.js";
 import { registerMachineRoutes } from "./machines/machineRoutes.js";
 import { registerMachineProxyRoutes } from "./machines/machineProxyRoutes.js";
@@ -121,10 +122,11 @@ export async function buildApp(deps: AppDependencies = {}): Promise<FastifyInsta
 
   const projects = deps.projects ?? new ProjectService(new ProjectStore());
   const workspaces = deps.workspaces ?? new WorkspaceService();
-  const piWebPlugins = deps.piWebPlugins ?? new PiWebPluginService();
+  const agent = effectiveAgentConfig(process.env, effectivePiWebConfig().config);
+  const piWebPlugins = deps.piWebPlugins ?? new PiWebPluginService({ agentDir: agent.dir });
   const configService = deps.config ?? createFilePiWebConfigService();
   const sessionDaemon = deps.sessionDaemon ?? new SessionDaemonClient();
-  const piWebStatusCache = createPiWebStatusCache(() => getPiWebStatus(sessionDaemon), {
+  const piWebStatusCache = createPiWebStatusCache(() => getPiWebStatus(sessionDaemon, { agentCommand: agent.command, agentDir: agent.dir }), {
     onError: (error) => { app.log.warn({ err: error }, "failed to refresh PI WEB status cache"); },
   });
   const machines = deps.machines ?? new MachineService(undefined, {
@@ -142,7 +144,7 @@ export async function buildApp(deps: AppDependencies = {}): Promise<FastifyInsta
   });
 
   app.get("/api/pi-web/status", async () => piWebStatusCache.get());
-  app.get("/api/pi-web/version", async () => getPiWebVersionStatus(sessionDaemon));
+  app.get("/api/pi-web/version", async () => getPiWebVersionStatus(sessionDaemon, { agentCommand: agent.command, agentDir: agent.dir }));
   app.get("/api/pi-web/runtime", async () => getPiWebRuntime(sessionDaemon));
   app.get("/api/plugins", async () => piWebPlugins.plugins());
   registerConfigRoutes(app, configService);
diff --git a/src/server/configRoutes.test.ts b/src/server/configRoutes.test.ts
index da3937f..264805f 100644
--- a/src/server/configRoutes.test.ts
+++ b/src/server/configRoutes.test.ts
@@ -37,11 +37,11 @@ describe("config routes", () => {
     const response = await app.inject({
       method: "PUT",
       url: "/api/config",
-      payload: { config: { host: "0.0.0.0", port: 9000, allowedHosts: true, spawnSessions: true, subsessions: true, shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { note: "hidden" } } }, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: "uploads\\manual" }, maxUploadBytes: 1234 } },
+      payload: { config: { host: "0.0.0.0", port: 9000, allowedHosts: true, spawnSessions: true, subsessions: true, agent: { command: "omp", dir: "~/.omp/agent" }, shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { note: "hidden" } } }, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: "uploads\\manual" }, maxUploadBytes: 1234 } },
     });
 
     expect(response.statusCode).toBe(200);
-    expect(savedConfig).toEqual({ host: "0.0.0.0", port: 9000, allowedHosts: true, spawnSessions: true, subsessions: true, shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { note: "hidden" } } }, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: "uploads/manual" }, maxUploadBytes: 1234 });
+    expect(savedConfig).toEqual({ host: "0.0.0.0", port: 9000, allowedHosts: true, spawnSessions: true, subsessions: true, agent: { command: "omp", dir: "~/.omp/agent" }, shortcuts: { "core:view.chat": "mod+1", "core:session.stop": null }, plugins: { info: { enabled: false, settings: { note: "hidden" } } }, pathAccess: { allowedPaths: ["/tmp"] }, uploads: { defaultFolder: "uploads/manual" }, maxUploadBytes: 1234 });
     expect(response.json<PiWebConfigResponse>().config).toEqual(savedConfig);
   });
 
@@ -100,6 +100,6 @@ function responseFor(config: PiWebConfigValues, exists: boolean): PiWebConfigRes
     exists,
     config,
     effectiveConfig: config,
-    envOverrides: { host: false, port: false, allowedHosts: false, spawnSessions: false, subsessions: false },
+    envOverrides: { host: false, port: false, allowedHosts: false, spawnSessions: false, subsessions: false, agentCommand: false, agentDir: false, agentSessionDir: false },
   };
 }
diff --git a/src/server/configRoutes.ts b/src/server/configRoutes.ts
index 1585efa..89ef3f4 100644
--- a/src/server/configRoutes.ts
+++ b/src/server/configRoutes.ts
@@ -1,5 +1,5 @@
 import type { FastifyInstance } from "fastify";
-import { effectivePiWebConfig, loadPiWebConfig, parseUploadsConfig, savePiWebConfig, type LoadOptions, type PiWebConfig } from "../config.js";
+import { effectiveAgentConfig, effectivePiWebConfig, hasAgentDirEnvOverride, hasAgentSessionDirEnvOverride, loadPiWebConfig, parseUploadsConfig, savePiWebConfig, type LoadOptions, type PiWebConfig } from "../config.js";
 import type { PiWebConfigEnvOverrides, PiWebConfigResponse, PiWebConfigValues } from "../shared/apiTypes.js";
 import { isPiWebPluginId } from "../shared/pluginIds.js";
 
@@ -27,7 +27,7 @@ export function currentPiWebConfigResponse(options: LoadOptions = {}): PiWebConf
     exists: loaded.exists,
     config: loaded.config,
     effectiveConfig: effective.config,
-    envOverrides: piWebConfigEnvOverrides(env),
+    envOverrides: piWebConfigEnvOverrides(env, loaded.config),
   };
 }
 
@@ -63,6 +63,7 @@ function parseConfigRequest(value: unknown): PiWebConfig {
   const maxUploadBytes = value["maxUploadBytes"];
   const spawnSessions = value["spawnSessions"];
   const subsessions = value["subsessions"];
+  const agent = value["agent"];
   if (host !== undefined) {
     if (typeof host !== "string") throw new Error("PI WEB config host must be a string");
     config.host = host;
@@ -85,6 +86,7 @@ function parseConfigRequest(value: unknown): PiWebConfig {
     if (typeof subsessions !== "boolean") throw new Error("PI WEB config subsessions must be a boolean");
     config.subsessions = subsessions;
   }
+  if (agent !== undefined) config.agent = parseAgentRequest(agent);
   return config;
 }
 
@@ -128,6 +130,30 @@ function parseMaxUploadBytesRequest(value: unknown): number {
   return value;
 }
 
+function parseAgentRequest(value: unknown): NonNullable<PiWebConfig["agent"]> {
+  if (!isRecord(value)) throw new Error("PI WEB config agent must be an object");
+  const command = value["command"];
+  const dir = value["dir"];
+  return {
+    ...(command === undefined ? {} : { command: parseAgentCommandRequest(command) }),
+    ...(dir === undefined ? {} : { dir: parseAgentDirRequest(dir) }),
+  };
+}
+
+function parseAgentCommandRequest(value: unknown): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error("PI WEB config agent.command must be a non-empty string");
+  const command = value.trim();
+  if (/[\s;&|`$<>]/u.test(command)) throw new Error("PI WEB config agent.command must be a single command name or path without shell metacharacters");
+  return command;
+}
+
+function parseAgentDirRequest(value: unknown): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error("PI WEB config agent.dir must be a non-empty string");
+  const dir = value.trim();
+  if (!isAbsoluteOrHomePath(dir)) throw new Error("PI WEB config agent.dir must be an absolute path or start with ~");
+  return dir;
+}
+
 function parsePluginsRequest(value: unknown): NonNullable<PiWebConfig["plugins"]> {
   if (!isRecord(value) || Array.isArray(value)) throw new Error("PI WEB config plugins must be an object");
   return Object.fromEntries(Object.entries(value).map(([pluginId, config]) => {
@@ -141,13 +167,17 @@ function parsePluginsRequest(value: unknown): NonNullable<PiWebConfig["plugins"]
   }));
 }
 
-function piWebConfigEnvOverrides(env: NodeJS.ProcessEnv): PiWebConfigEnvOverrides {
+function piWebConfigEnvOverrides(env: NodeJS.ProcessEnv, config: PiWebConfig = {}): PiWebConfigEnvOverrides {
+  const agent = effectiveAgentConfig(env, config);
   return {
     host: isEnvSet(env["PI_WEB_HOST"]),
     port: isEnvSet(env["PI_WEB_PORT"]) || isEnvSet(env["PORT"]),
     allowedHosts: isEnvSet(env["PI_WEB_ALLOWED_HOSTS"]),
     spawnSessions: isEnvSet(env["PI_WEB_SPAWN_SESSIONS"]),
     subsessions: isEnvSet(env["PI_WEB_SUBSESSIONS"]),
+    agentCommand: isEnvSet(env["PI_WEB_AGENT_COMMAND"]),
+    agentDir: hasAgentDirEnvOverride(env, agent.command),
+    agentSessionDir: hasAgentSessionDirEnvOverride(env, agent.command),
   };
 }
 
@@ -163,6 +193,10 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function isAbsoluteOrHomePath(value: string): boolean {
+  return value === "~" || value.startsWith("~/") || value.startsWith("~\\") || value.startsWith("/") || value.startsWith("\\") || /^[A-Za-z]:[\\/]/u.test(value);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
diff --git a/src/server/piWebStatus.test.ts b/src/server/piWebStatus.test.ts
index 344395f..94bf1eb 100644
--- a/src/server/piWebStatus.test.ts
+++ b/src/server/piWebStatus.test.ts
@@ -2,9 +2,9 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { comparePackageVersions, getPiWebStatus, getPiWebVersionStatus } from "./piWebStatus.js";
+import { comparePackageVersions, getPiWebStatus, getPiWebVersionStatus, updateCommandFor } from "./piWebStatus.js";
 import { SessionDaemonClient } from "../sessiond/sessionDaemonClient.js";
-import type { PiWebComponentStatus } from "../shared/apiTypes.js";
+import type { PiWebComponentStatus, PiWebRuntimeComponent } from "../shared/apiTypes.js";
 
 const originalSkipVersionCheck = process.env["PI_WEB_SKIP_VERSION_CHECK"];
 const originalHome = process.env["HOME"];
@@ -40,6 +40,26 @@ describe("PI WEB status", () => {
     expect(status).not.toHaveProperty("release");
   });
 
+  it("detects session daemon package installs from the configured agent dir for runtime responses", async () => {
+    const agentDir = await tempHome();
+    try {
+      await installConfiguredPiWebPackage(agentDir);
+      const daemon = daemonWithRuntime({
+        component: "sessiond",
+        label: "Session daemon",
+        runtimeVersion: "1.202605.7",
+        available: true,
+        capabilities: [],
+      });
+
+      const status = await getPiWebVersionStatus(daemon, { agentCommand: "omp", agentDir });
+
+      expect(status.components.sessiond.installation).toMatchObject({ kind: "pi-package", source: process.cwd(), scope: "user" });
+    } finally {
+      await rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
   it("reports stale session daemon versions as messages", async () => {
     process.env["PI_WEB_SKIP_VERSION_CHECK"] = "1";
     const daemon = daemonWithComponent({
@@ -60,6 +80,19 @@ describe("PI WEB status", () => {
     expect(status.messages.map((message) => message.id)).toContain("sessiond-stale");
   });
 
+  it("shell-quotes pi-package agent update commands", async () => {
+    const updateCommand = await updateCommandFor(
+      { kind: "pi-package", source: "npm:@jmfederico/pi-web", scope: "user", path: "/tmp/pi-web" },
+      "pi-web restart",
+      {
+        agentCommand: "/tmp/agent's/omp",
+        hasCommand: (command) => Promise.resolve(command === "/tmp/agent's/omp"),
+      },
+    );
+
+    expect(updateCommand).toBe("'/tmp/agent'\\''s/omp' update 'npm:@jmfederico/pi-web' && pi-web restart");
+  });
+
   it("suggests native systemd commands for local development services", async () => {
     if (process.platform !== "linux") return;
     process.env["PI_WEB_SKIP_VERSION_CHECK"] = "1";
@@ -109,6 +142,16 @@ function daemonWithComponent(component: PiWebComponentStatus): SessionDaemonClie
   return daemon;
 }
 
+function daemonWithRuntime(component: PiWebRuntimeComponent): SessionDaemonClient {
+  const daemon = new SessionDaemonClient();
+  vi.spyOn(daemon, "request").mockResolvedValue({
+    statusCode: 200,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(component),
+  });
+  return daemon;
+}
+
 function staleLocalSessiond(): PiWebComponentStatus {
   return {
     component: "sessiond",
@@ -131,6 +174,11 @@ async function installSystemdServiceFiles(home: string, names: string[]): Promis
   await Promise.all(names.map((name) => writeFile(join(dir, name), "")));
 }
 
+async function installConfiguredPiWebPackage(agentDir: string): Promise<void> {
+  await writeFile(join(agentDir, "settings.json"), `${JSON.stringify({ packages: [process.cwd()] }, null, 2)}\n`, "utf8");
+}
+
+
 function restoreEnv(key: string, value: string | undefined): void {
   if (value === undefined) Reflect.deleteProperty(process.env, key);
   else process.env[key] = value;
diff --git a/src/server/piWebStatus.ts b/src/server/piWebStatus.ts
index a7d4dd4..7aa3187 100644
--- a/src/server/piWebStatus.ts
+++ b/src/server/piWebStatus.ts
@@ -5,11 +5,12 @@ import { promisify } from "node:util";
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { DefaultPackageManager, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { PiWebCapability, PiWebComponentStatus, PiWebInstallationInfo, PiWebReleaseStatus, PiWebRuntimeComponent, PiWebRuntimeResponse, PiWebServiceComponent, PiWebStatusMessage, PiWebStatusResponse, PiWebVersionResponse } from "../shared/apiTypes.js";
 import { effectivePiWebCapabilities, WEB_RUNTIME_CAPABILITIES } from "../shared/capabilities.js";
 import { parsePiWebComponentStatus, parsePiWebRuntimeComponent } from "../shared/piWebStatusParsing.js";
 import { SessionDaemonClient } from "../sessiond/sessionDaemonClient.js";
+import { effectiveAgentConfig } from "../config.js";
 
 const PI_WEB_PACKAGE_NAME = "@jmfederico/pi-web";
 const PI_WEB_NPM_SOURCE = `npm:${PI_WEB_PACKAGE_NAME}`;
@@ -73,6 +74,22 @@ interface PiWebStatusDaemon {
   request(method: string, path: string, body?: unknown): Promise<{ statusCode: number; headers: Record<string, string>; body: string }>;
 }
 
+interface PiWebStatusOptions {
+  agentCommand?: string;
+  agentDir?: string;
+  hasCommand?: (command: string) => Promise<boolean>;
+}
+
+function effectiveStatusAgentConfig(options: PiWebStatusOptions): { command: string; dir: string } {
+  const agent = effectiveAgentConfig(process.env, {
+    agent: {
+      ...(options.agentCommand === undefined ? {} : { command: options.agentCommand }),
+      ...(options.agentDir === undefined ? {} : { dir: options.agentDir }),
+    },
+  });
+  return { command: agent.command, dir: agent.dir };
+}
+
 let latestReleaseCache: { checkedAtMs: number; latestVersion?: string; error?: string } | undefined;
 
 const runtimePackageInfo = readPackageInfoSync();
@@ -98,10 +115,10 @@ export async function getPiWebRuntime(daemon: PiWebStatusDaemon = new SessionDae
   };
 }
 
-export async function getPiWebComponentStatus(component: PiWebServiceComponent): Promise<PiWebComponentStatus> {
+export async function getPiWebComponentStatus(component: PiWebServiceComponent, options: PiWebStatusOptions = {}): Promise<PiWebComponentStatus> {
   const [installed, installation] = await Promise.all([
     readInstalledPackageInfo(),
-    detectPiWebInstallation(),
+    detectPiWebInstallation(options.agentDir),
   ]);
   const runtimeVersion = runtimePackageInfo?.version ?? DEFAULT_VERSION;
   const installedVersion = installed?.version;
@@ -116,10 +133,10 @@ export async function getPiWebComponentStatus(component: PiWebServiceComponent):
   };
 }
 
-export async function getPiWebVersionStatus(daemon: PiWebStatusDaemon = new SessionDaemonClient()): Promise<PiWebVersionResponse> {
+export async function getPiWebVersionStatus(daemon: PiWebStatusDaemon = new SessionDaemonClient(), options: PiWebStatusOptions = {}): Promise<PiWebVersionResponse> {
   const [web, sessiond] = await Promise.all([
-    getPiWebComponentStatus("web"),
-    getSessiondComponentStatus(daemon),
+    getPiWebComponentStatus("web", options),
+    getSessiondComponentStatus(daemon, options),
   ]);
   return {
     packageName: PI_WEB_PACKAGE_NAME,
@@ -128,12 +145,13 @@ export async function getPiWebVersionStatus(daemon: PiWebStatusDaemon = new Sess
   };
 }
 
-export async function getPiWebStatus(daemon: PiWebStatusDaemon = new SessionDaemonClient()): Promise<PiWebStatusResponse> {
-  const versionStatus = await getPiWebVersionStatus(daemon);
+export async function getPiWebStatus(daemon: PiWebStatusDaemon = new SessionDaemonClient(), options: PiWebStatusOptions = {}): Promise<PiWebStatusResponse> {
+  const agent = effectiveStatusAgentConfig(options);
+  const versionStatus = await getPiWebVersionStatus(daemon, { ...options, agentDir: agent.dir });
   const { web, sessiond } = versionStatus.components;
   const release = await getLatestReleaseStatus(web.installedVersion ?? web.runtimeVersion ?? DEFAULT_VERSION);
   const components = { web, sessiond };
-  const commands = await commandsFor(components);
+  const commands = await commandsFor(components, { agentCommand: agent.command, hasCommand: options.hasCommand ?? hasCommand });
   const messages = buildMessages(components, release, commands);
   return {
     ...versionStatus,
@@ -187,19 +205,18 @@ function parsePackageInfo(value: unknown, path: string): PackageInfo | undefined
   return { name, version, path };
 }
 
-async function detectPiWebInstallation(): Promise<PiWebInstallationInfo> {
+async function detectPiWebInstallation(agentDir = effectiveAgentConfig().dir): Promise<PiWebInstallationInfo> {
   const root = packageRootPath();
   const realRoot = await realPathOrSelf(root);
-  const piPackage = await detectPiPackageInstallation(realRoot, root);
+  const piPackage = await detectPiPackageInstallation(realRoot, root, agentDir);
   if (piPackage !== undefined) return piPackage;
   const npmGlobal = await detectNpmGlobalInstallation(realRoot, root);
   if (npmGlobal !== undefined) return npmGlobal;
   return { kind: "local", path: root };
 }
 
-async function detectPiPackageInstallation(realRoot: string, displayPath: string): Promise<PiWebInstallationInfo | undefined> {
+async function detectPiPackageInstallation(realRoot: string, displayPath: string, agentDir: string): Promise<PiWebInstallationInfo | undefined> {
   try {
-    const agentDir = getAgentDir();
     const packageManager = new DefaultPackageManager({
       cwd: process.cwd(),
       agentDir,
@@ -267,7 +284,7 @@ async function getSessiondRuntimeComponent(daemon: PiWebStatusDaemon): Promise<P
   }
 }
 
-async function getSessiondComponentStatus(daemon: PiWebStatusDaemon): Promise<PiWebComponentStatus> {
+async function getSessiondComponentStatus(daemon: PiWebStatusDaemon, options: PiWebStatusOptions = {}): Promise<PiWebComponentStatus> {
   try {
     const upstream = await daemon.request("GET", "/runtime");
     if (upstream.statusCode < 200 || upstream.statusCode >= 300) {
@@ -278,7 +295,7 @@ async function getSessiondComponentStatus(daemon: PiWebStatusDaemon): Promise<Pi
     if (legacyVersion !== undefined) return legacyVersion;
     const runtime = parsePiWebRuntimeComponent(parsed);
     if (runtime?.available !== true) return await legacySessiondComponentStatus(daemon) ?? unavailableSessiond(runtime?.error ?? "runtime response did not include valid runtime information");
-    const status = await getPiWebComponentStatus("sessiond");
+    const status = await getPiWebComponentStatus("sessiond", options);
     return { ...status, ...(runtime.runtimeVersion === undefined ? {} : { runtimeVersion: runtime.runtimeVersion }), available: true };
   } catch (error) {
     return unavailableSessiond(error instanceof Error ? error.message : String(error));
@@ -375,7 +392,7 @@ async function fetchLatestNpmVersion(currentVersion: string): Promise<string> {
   return version;
 }
 
-async function commandsFor(components: PiWebStatusResponse["components"]): Promise<PiWebStatusResponse["commands"]> {
+async function commandsFor(components: PiWebStatusResponse["components"], options: { agentCommand: string; hasCommand: (command: string) => Promise<boolean> }): Promise<PiWebStatusResponse["commands"]> {
   const installation = preferredInstallation(components);
   const [serviceCommands, cliCommands] = await Promise.all([
     nativeServiceCommands(),
@@ -385,7 +402,7 @@ async function commandsFor(components: PiWebStatusResponse["components"]): Promi
   const restartWeb = serviceCommands.restartWeb ?? cliCommands.restart;
   const restartSessiond = serviceCommands.restartSessiond ?? cliCommands.restart;
   const status = serviceCommands.status ?? cliCommands.status;
-  const update = await updateCommandFor(installation, restart);
+  const update = await updateCommandFor(installation, restart, options);
 
   return {
     ...(update === undefined ? {} : { update }),
@@ -413,11 +430,11 @@ function restartCommandFor(installation: PiWebInstallationInfo | undefined, serv
   return cliCommands.restart ?? serviceCommands.restart;
 }
 
-async function updateCommandFor(installation: PiWebInstallationInfo | undefined, restartCommand: string | undefined): Promise<string | undefined> {
+export async function updateCommandFor(installation: PiWebInstallationInfo | undefined, restartCommand: string | undefined, options: { agentCommand: string; hasCommand: (command: string) => Promise<boolean> }): Promise<string | undefined> {
   if (restartCommand === undefined) return undefined;
   if (installation?.kind === "pi-package") {
-    if (!(await hasCommand("pi"))) return undefined;
-    return `pi update ${installation.source ?? PI_WEB_NPM_SOURCE} && ${restartCommand}`;
+    if (!(await options.hasCommand(options.agentCommand))) return undefined;
+    return `${shellQuote(options.agentCommand)} update ${shellQuote(installation.source ?? PI_WEB_NPM_SOURCE)} && ${restartCommand}`;
   }
   if (installation?.kind === "local" && installation.path !== undefined) {
     if (!(await hasCommand("npm")) || !(await isGitCheckoutWithUpstream(installation.path))) return undefined;
@@ -497,7 +514,7 @@ async function isGitCheckoutWithUpstream(path: string): Promise<boolean> {
 }
 
 function hasCommand(command: string): Promise<boolean> {
-  return commandSucceeds("/usr/bin/env", ["sh", "-c", `command -v ${command}`]);
+  return commandSucceeds("/usr/bin/env", ["sh", "-c", `command -v ${shellQuote(command)}`]);
 }
 
 async function commandSucceeds(command: string, args: string[]): Promise<boolean> {
diff --git a/src/server/sessiond.ts b/src/server/sessiond.ts
index f4cc36e..579eed2 100644
--- a/src/server/sessiond.ts
+++ b/src/server/sessiond.ts
@@ -9,6 +9,7 @@ import { SessionEventHub } from "./realtime/sessionEventHub.js";
 import { AuthService } from "./sessions/authService.js";
 import { registerAuthRoutes } from "./sessions/authRoutes.js";
 import { PiSessionService } from "./sessions/piSessionService.js";
+import { createPiSessionManagerGateway } from "./sessions/piSessionManagerGateway.js";
 import { registerSessionRoutes } from "./sessions/sessionRoutes.js";
 import { ProjectScopedSpawnTargetResolver } from "./sessions/spawnTargetResolver.js";
 import { ProjectService } from "./projects/projectService.js";
@@ -19,24 +20,27 @@ import { TerminalService } from "./terminals/terminalService.js";
 import { registerTerminalRoutes } from "./terminals/terminalRoutes.js";
 import { getPiWebRuntimeComponent } from "./piWebStatus.js";
 import { SESSIOND_RUNTIME_CAPABILITIES } from "../shared/capabilities.js";
-import { effectivePiWebConfig, maxUploadBytes, spawnSessionsEnabled, subsessionsEnabled } from "../config.js";
+import { effectiveAgentConfig, effectivePiWebConfig, maxUploadBytes, spawnSessionsEnabled, subsessionsEnabled } from "../config.js";
 
 const { config } = effectivePiWebConfig();
+const agent = effectiveAgentConfig(process.env, config);
 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 auth = new AuthService({ agentDir: agent.dir });
 const spawnTargets = spawnSessionsEnabled(process.env, config)
   ? new ProjectScopedSpawnTargetResolver({ projects: new ProjectService(new ProjectStore()), workspaces: new WorkspaceService() })
   : undefined;
 const sessions = new PiSessionService(eventHub, {
   modelRegistry: auth.modelRegistry,
+  agentDir: agent.dir,
   workspaceActivity,
   logger: app.log,
   ...(spawnTargets === undefined ? {} : { spawnTargets }),
   subsessionsEnabled: spawnTargets !== undefined && subsessionsEnabled(process.env, config),
+  sessionManager: createPiSessionManagerGateway({ agentDir: agent.dir, sessionDirEnvKeys: agent.sessionDirEnvKeys }),
 });
 auth.subscribe((change) => { sessions.applyAuthChange(change); });
 const terminals = new TerminalService(eventHub, workspaceActivity);
diff --git a/src/server/sessions/authService.test.ts b/src/server/sessions/authService.test.ts
index 3efe1b3..04c3e4b 100644
--- a/src/server/sessions/authService.test.ts
+++ b/src/server/sessions/authService.test.ts
@@ -1,7 +1,16 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { AuthService, type AuthChange } from "./authService.js";
 
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
 describe("AuthService", () => {
   it("saves API keys and emits a global auth change", () => {
     const { auth, authStorage, changes } = createAuthService();
@@ -30,6 +39,16 @@ describe("AuthService", () => {
     expect(changes).toEqual([]);
     auth.dispose();
   });
+
+  it("stores credentials in the configured agent directory", async () => {
+    const agentDir = await tempAgentDir();
+    const auth = new AuthService({ agentDir });
+
+    auth.saveApiKey("anthropic", "sk-omp");
+
+    await expect(readFile(join(agentDir, "auth.json"), "utf8")).resolves.toContain("sk-omp");
+    auth.dispose();
+  });
 });
 
 function createAuthService(data: Parameters<typeof AuthStorage.inMemory>[0] = {}) {
@@ -40,3 +59,9 @@ function createAuthService(data: Parameters<typeof AuthStorage.inMemory>[0] = {}
   auth.subscribe((change) => { changes.push(change); });
   return { auth, authStorage, changes };
 }
+
+async function tempAgentDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "pi-web-auth-agent-"));
+  tempDirs.push(dir);
+  return dir;
+}
diff --git a/src/server/sessions/authService.ts b/src/server/sessions/authService.ts
index c884af9..3cb1305 100644
--- a/src/server/sessions/authService.ts
+++ b/src/server/sessions/authService.ts
@@ -1,3 +1,4 @@
+import { join } from "node:path";
 import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
 import type { AuthProvidersResponse, AuthType, OAuthFlowState } from "../../shared/apiTypes.js";
 import { getLoginProviderOptions, getLogoutProviderOptions } from "./authProviderOptions.js";
@@ -11,17 +12,23 @@ type AuthChangeListener = (change: AuthChange) => void;
 type ModelRegistryInstance = ReturnType<typeof ModelRegistry.create>;
 
 export interface AuthServiceDependencies {
+  agentDir?: string;
   modelRegistry?: ModelRegistryInstance;
   authFlows?: OAuthLoginFlowService;
 }
 
+export function createModelRegistryForAgentDir(agentDir: string): ModelRegistryInstance {
+  const authStorage = AuthStorage.create(join(agentDir, "auth.json"));
+  return ModelRegistry.create(authStorage, join(agentDir, "models.json"));
+}
+
 export class AuthService {
   readonly modelRegistry: ModelRegistryInstance;
   private readonly authFlows: OAuthLoginFlowService;
   private readonly listeners = new Set<AuthChangeListener>();
 
   constructor(deps: AuthServiceDependencies = {}) {
-    this.modelRegistry = deps.modelRegistry ?? ModelRegistry.create(AuthStorage.create());
+    this.modelRegistry = deps.modelRegistry ?? (deps.agentDir === undefined ? ModelRegistry.create(AuthStorage.create()) : createModelRegistryForAgentDir(deps.agentDir));
     this.authFlows = deps.authFlows ?? new OAuthLoginFlowService();
   }
 
diff --git a/src/server/sessions/piSessionManagerGateway.test.ts b/src/server/sessions/piSessionManagerGateway.test.ts
index d787ae6..eda4d73 100644
--- a/src/server/sessions/piSessionManagerGateway.test.ts
+++ b/src/server/sessions/piSessionManagerGateway.test.ts
@@ -59,6 +59,16 @@ describe("SessionDirResolver", () => {
 
     expect(resolver.resolve(cwd)).toMatchObject({ source: "env", sessionDir: envDir, usesConfiguredSessionDir: true });
   });
+
+  it("uses OMP sessionDir environment overrides before settings", async () => {
+    const envDir = join(tempDir, "omp-env-sessions");
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(join(agentDir, "settings.json"), `${JSON.stringify({ sessionDir: join(tempDir, "settings-sessions") }, null, 2)}\n`, "utf8");
+
+    const resolver = new SessionDirResolver({ agentDir, env: { OMP_CODING_AGENT_SESSION_DIR: envDir }, sessionDirEnvKeys: ["PI_WEB_AGENT_SESSION_DIR", "OMP_CODING_AGENT_SESSION_DIR", "PI_CODING_AGENT_SESSION_DIR"] });
+
+    expect(resolver.resolve(cwd)).toMatchObject({ source: "env", sessionDir: envDir, usesConfiguredSessionDir: true });
+  });
 });
 
 describe("Pi session manager gateway", () => {
@@ -82,6 +92,21 @@ describe("Pi session manager gateway", () => {
     await expect(gateway.listAll()).resolves.toEqual(expect.arrayContaining([expect.objectContaining({ id: "default-session", cwd }), expect.objectContaining({ id: "env-session", cwd })]));
   });
 
+  it("includes command-specific env session directories in global listing", async () => {
+    for (const envKey of ["PI_WEB_AGENT_SESSION_DIR", "OMP_CODING_AGENT_SESSION_DIR"]) {
+      const envSessionDir = join(tempDir, `${envKey.toLowerCase()}-sessions`);
+      await writeSessionFile(envSessionDir, `${envKey.toLowerCase()}-session`, cwd);
+      const gateway = createPiSessionManagerGateway({
+        agentDir,
+        env: { [envKey]: envSessionDir },
+        sessionDirEnvKeys: ["PI_WEB_AGENT_SESSION_DIR", "OMP_CODING_AGENT_SESSION_DIR", "PI_CODING_AGENT_SESSION_DIR"],
+      });
+
+      if (gateway.listAll === undefined) throw new Error("Expected legacy listing support");
+      await expect(gateway.listAll()).resolves.toEqual(expect.arrayContaining([expect.objectContaining({ id: `${envKey.toLowerCase()}-session`, cwd })]));
+    }
+  });
+
   it("lists only sessions for the requested cwd when a custom Pi sessionDir is shared", async () => {
     const sharedSessionDir = join(tempDir, "shared-sessions");
     const otherCwd = join(tempDir, "other-workspace");
diff --git a/src/server/sessions/piSessionManagerGateway.ts b/src/server/sessions/piSessionManagerGateway.ts
index 57a2446..7b06eaf 100644
--- a/src/server/sessions/piSessionManagerGateway.ts
+++ b/src/server/sessions/piSessionManagerGateway.ts
@@ -19,15 +19,18 @@ export interface SessionDirResolution {
 export interface SessionDirResolverOptions {
   agentDir?: string;
   env?: NodeJS.ProcessEnv;
+  sessionDirEnvKeys?: readonly string[];
 }
 
 export class SessionDirResolver {
   private readonly agentDir: string;
   private readonly env: NodeJS.ProcessEnv;
+  private readonly sessionDirEnvKeys: readonly string[];
 
   constructor(options: SessionDirResolverOptions = {}) {
     this.agentDir = options.agentDir ?? getAgentDir();
     this.env = options.env ?? process.env;
+    this.sessionDirEnvKeys = options.sessionDirEnvKeys ?? [PI_SESSION_DIR_ENV];
   }
 
   defaultSessionsRoot(): string {
@@ -35,15 +38,15 @@ export class SessionDirResolver {
   }
 
   globalEnvSessionDir(): string | undefined {
-    const envSessionDir = this.env[PI_SESSION_DIR_ENV];
-    if (envSessionDir === undefined || envSessionDir === "") return undefined;
+    const envSessionDir = this.envSessionDir();
+    if (envSessionDir === undefined) return undefined;
     const expanded = expandTildePath(envSessionDir);
     return isAbsolute(expanded) ? expanded : undefined;
   }
 
   resolve(cwd: string): SessionDirResolution {
-    const envSessionDir = this.env[PI_SESSION_DIR_ENV];
-    if (envSessionDir !== undefined && envSessionDir !== "") {
+    const envSessionDir = this.envSessionDir();
+    if (envSessionDir !== undefined) {
       return { source: "env", sessionDir: resolveConfiguredPath(envSessionDir, cwd), usesConfiguredSessionDir: true };
     }
 
@@ -54,6 +57,10 @@ export class SessionDirResolver {
 
     return { source: "pi-default", sessionDir: defaultPiSessionDir(cwd, this.agentDir), usesConfiguredSessionDir: false };
   }
+
+  private envSessionDir(): string | undefined {
+    return this.sessionDirEnvKeys.map((key) => this.env[key]).find((value) => value !== undefined && value !== "");
+  }
 }
 
 export type PiSessionManagerGatewayOptions = SessionDirResolverOptions;
diff --git a/src/server/sessions/piSessionService.ts b/src/server/sessions/piSessionService.ts
index afe919f..bf0d12a 100644
--- a/src/server/sessions/piSessionService.ts
+++ b/src/server/sessions/piSessionService.ts
@@ -21,7 +21,7 @@ import { SessionCommandService } from "./sessionCommandService.js";
 import { SessionArchiveStore, type ArchivedSessionRecord, type ArchiveSessionInput } from "./sessionArchiveStore.js";
 import { findArchiveCandidateByIdOrPrefix, planSessionArchiveTree, type SessionArchiveTreeCandidate } from "./sessionArchiveTree.js";
 import type { ActiveSession } from "./sessionRuntimeStore.js";
-import type { AuthChange } from "./authService.js";
+import { createModelRegistryForAgentDir, type AuthChange } from "./authService.js";
 import { fallbackSessionName, generateShortSessionName } from "./sessionNameGenerator.js";
 import { computeEditPreview, type EditPreviewResult } from "./editPreview.js";
 import { createPiSessionManagerGateway } from "./piSessionManagerGateway.js";
@@ -340,7 +340,7 @@ export class PiSessionService implements SessionRouteService {
     this.archiveStore = deps.archiveStore ?? new SessionArchiveStore();
     this.agentDir = deps.agentDir ?? getAgentDir();
     this.sessionManager = deps.sessionManager ?? createPiSessionManagerGateway({ agentDir: this.agentDir });
-    this.modelRegistry = deps.modelRegistry ?? ModelRegistry.create(AuthStorage.create());
+    this.modelRegistry = deps.modelRegistry ?? createModelRegistryForAgentDir(this.agentDir);
     this.spawnTargets = deps.spawnTargets;
     this.logger = deps.logger ?? noopLogger;
     this.now = deps.now ?? (() => new Date());
diff --git a/src/shared/apiTypes.ts b/src/shared/apiTypes.ts
index cf028dc..b225908 100644
--- a/src/shared/apiTypes.ts
+++ b/src/shared/apiTypes.ts
@@ -61,6 +61,13 @@ export interface PiWebUploadsConfig {
   defaultFolder?: string;
 }
 
+export interface PiWebAgentConfig {
+  /** Agent CLI command used for diagnostics and package-managed updates. */
+  command?: string;
+  /** Agent config/state directory containing auth.json, models.json, settings.json, and sessions/. */
+  dir?: string;
+}
+
 export interface PiWebConfigValues {
   host?: string;
   port?: number;
@@ -82,6 +89,8 @@ export interface PiWebConfigValues {
    * while the capability stabilizes. Requires spawnSessions to be enabled.
    */
   subsessions?: boolean;
+  /** Agent runtime state used by the session daemon (Pi by default; OMP compatible). */
+  agent?: PiWebAgentConfig;
 }
 
 export type PiWebPluginScope = "bundled" | "local" | "user" | "project";
@@ -105,6 +114,9 @@ export interface PiWebConfigEnvOverrides {
   allowedHosts: boolean;
   spawnSessions: boolean;
   subsessions: boolean;
+  agentCommand: boolean;
+  agentDir: boolean;
+  agentSessionDir: boolean;
 }
 
 export interface PiWebConfigResponse {