└─$ cat /tmp/pi-web-omp.md
# Running PI WEB with Oh My Pi (OMP)

This guide explains how to run [PI WEB](https://pi-web.dev/) against an existing [Oh My Pi](https://github.com/umans-ai/oh-my-pi) (`omp`) installation.

PI WEB is built for upstream Pi Coding Agent. OMP is built on the same ecosystem, so PI WEB can usually be made to work, but the integration needs a compatibility layer because PI WEB expects a `pi` CLI and ships its own bundled upstream Pi SDK.

## What Works

With the setup below, PI WEB can:

- run as persistent user services;
- expose a browser UI for projects, workspaces, sessions, files, and terminals;
- store/read sessions from OMP's agent directory;
- use compatible credentials from OMP/Pi auth state;
- use providers supported by PI WEB's bundled Pi SDK.

## Important Limitation

PI WEB does **not** execute model requests through your installed `omp` binary. It uses its own bundled upstream Pi SDK from the npm package:

```text
@jmfederico/pi-web/node_modules/@earendil-works/pi-coding-agent
```

That means provider support is determined by the PI WEB bundle, not by the local OMP binary.

For example, if OMP supports a provider but PI WEB's bundled SDK does not, copying credentials alone will not make the provider work. The bundled SDK must contain the provider implementation, model catalog, auth refresh logic, and API transport.

## Requirements

Install these first:

- Linux/macOS/WSL with a supported user-service manager, or use PI WEB's manual process mode.
- Node.js `>=22`.
- npm.
- OMP installed and working for the same user.
- Git and the development tools your agents need.
- A login shell that exposes `node`, `npm`, `omp`, and the compatibility `pi` shim.

Check OMP:

```bash
command -v omp
omp --version
```

Check Node/npm:

```bash
node --version
npm --version
```

PI WEB services run commands through a non-interactive login shell. If a command works only in your interactive shell, move PATH/version-manager setup into your login shell file:

- zsh: `~/.zprofile`
- bash: `~/.bash_profile` or `~/.profile`
- fish: universal PATH setup such as `fish_add_path -U ...`

## 1. Back Up Existing Agent State

Before changing auth or session state, back up both OMP and upstream Pi directories if they exist:

```bash
mkdir -p ~/backups
tar -C ~ -czf ~/backups/omp-pi-agent-before-pi-web-$(date +%Y%m%d-%H%M%S).tgz .omp/agent .pi/agent 2>/dev/null || true
```

## 2. Install Node.js and npm

PI WEB requires Node.js 22 or newer.

Use your OS package manager, NodeSource, Homebrew, mise/asdf shims, or another method that is visible to login shells and user services.

Verify through the login shell PI WEB will use:

```bash
zsh -lc 'node --version && npm --version'
# or
bash -lc 'node --version && npm --version'
```

The Node major version must be `22` or newer.

## 3. Add a `pi` Compatibility Shim

PI WEB's installer and doctor require a command named `pi`. OMP installs `omp`, not `pi`, so create a compatibility shim somewhere in your login-shell PATH.

Common location:

```bash
mkdir -p ~/.local/bin
cat > ~/.local/bin/pi <<'EOF'
#!/usr/bin/env sh
exec "$HOME/.local/bin/omp" "$@"
EOF
chmod +x ~/.local/bin/pi
```

If your `omp` binary lives somewhere else, adjust the `exec` path or use:

```sh
exec omp "$@"
```

Verify:

```bash
zsh -lc 'command -v pi && pi --version && command -v omp && omp --version'
```

Expected result: both `pi` and `omp` resolve, and `pi --version` prints the OMP version.

## 4. Point PI WEB at OMP's Agent Directory

OMP's active state is normally under:

```text
~/.omp/agent
```

Upstream Pi's default is normally:

```text
~/.pi/agent
```

PI WEB's bundled SDK uses `PI_CODING_AGENT_DIR` to choose the agent directory. Set it to OMP's agent directory:

```text
PI_CODING_AGENT_DIR=$HOME/.omp/agent
```

### systemd user services

For Linux systemd user services, persist the env var:

```bash
mkdir -p ~/.config/environment.d
cat > ~/.config/environment.d/10-pi-web-omp.conf <<EOF
PI_CODING_AGENT_DIR=$HOME/.omp/agent
EOF

systemctl --user daemon-reload
systemctl --user set-environment PI_CODING_AGENT_DIR=$HOME/.omp/agent
```

Verify:

```bash
systemctl --user show-environment | grep PI_CODING_AGENT_DIR
```

### Why this is required

Passing the env var only to `pi-web install` is not enough:

```bash
PI_CODING_AGENT_DIR=$HOME/.omp/agent pi-web install
```

PI WEB's generated service files do not automatically persist arbitrary environment variables. The service manager environment must provide `PI_CODING_AGENT_DIR`, or you must use wrapper scripts.

### Wrapper alternative

If you do not want to rely on the service manager environment, create wrappers:

```bash
mkdir -p ~/.local/bin/pi-web-omp

cat > ~/.local/bin/pi-web-omp/pi-web-server <<'EOF'
#!/usr/bin/env sh
export PI_CODING_AGENT_DIR="$HOME/.omp/agent"
exec pi-web-server "$@"
EOF

cat > ~/.local/bin/pi-web-omp/pi-web-sessiond <<'EOF'
#!/usr/bin/env sh
export PI_CODING_AGENT_DIR="$HOME/.omp/agent"
exec pi-web-sessiond "$@"
EOF

chmod +x ~/.local/bin/pi-web-omp/pi-web-server ~/.local/bin/pi-web-omp/pi-web-sessiond
```

Then install services with executable overrides:

```bash
PI_WEB_SERVER_EXEC="$HOME/.local/bin/pi-web-omp/pi-web-server" \
PI_WEB_SESSIOND_EXEC="$HOME/.local/bin/pi-web-omp/pi-web-sessiond" \
pi-web install
```

## 5. Create PI WEB Config

PI WEB config lives at:

```text
~/.config/pi-web/config.json
```

Safe local-only starting config:

```bash
mkdir -p ~/.config/pi-web
cat > ~/.config/pi-web/config.json <<'EOF'
{
  "host": "127.0.0.1",
  "port": 8504,
  "spawnSessions": true,
  "subsessions": false,
  "pathAccess": {
    "allowedPaths": []
  }
}
EOF
```

Open locally at:

```text
http://127.0.0.1:8504
```

For remote access, prefer an SSH tunnel:

```bash
ssh -L 8504:127.0.0.1:8504 user@host
```

Then open locally:

```text
http://127.0.0.1:8504
```

### Optional: bind to all interfaces

If you intentionally want PI WEB reachable on the network, update:

```json
{
  "host": "0.0.0.0",
  "port": 80
}
```

Then restart:

```bash
pi-web restart
```

Check whether unprivileged users may bind low ports:

```bash
sysctl net.ipv4.ip_unprivileged_port_start
```

If the value is `0`, a user service can bind port `80`. Otherwise use a higher port, a reverse proxy, or grant a specific capability to the Node binary.

Security warning: PI WEB is not a sandbox or multi-tenant service. Do not expose it directly to the public internet. Use a trusted network, VPN, firewall, SSH tunnel, or authenticated reverse proxy.

## 6. Install PI WEB

Install the npm package globally:

```bash
npm install -g @jmfederico/pi-web
```

Depending on your npm prefix, you may need `sudo`:

```bash
sudo npm install -g @jmfederico/pi-web
```

Verify:

```bash
command -v pi-web
command -v pi-web-server
command -v pi-web-sessiond
pi-web version
```

Install user services:

```bash
pi-web install
```

Check:

```bash
pi-web doctor
pi-web status
```

Expected required checks:

```text
node >= 22 found
npm found
pi found
pi-web-server found
pi-web-sessiond found
session daemon running
web server running
```

Optional warnings such as missing `rg` are not fatal. Installing ripgrep improves file suggestion performance:

```bash
sudo apt-get install -y ripgrep
```

## 7. Verify the Agent Directory Bridge

After services start, confirm the running session daemon has the expected env var.

Get the session daemon PID:

```bash
systemctl --user show pi-web-sessiond.service --property=MainPID --value
```

Check the process environment:

```bash
tr '\0' '\n' < /proc/<PID>/environ | grep PI_CODING_AGENT_DIR
```

Expected:

```text
PI_CODING_AGENT_DIR=/home/<user>/.omp/agent
```

Then open PI WEB and create a test session in a harmless workspace. Confirm new session files are created under:

```text
~/.omp/agent/sessions/
```

not primarily under:

```text
~/.pi/agent/sessions/
```

## 8. Configure Provider Credentials

PI WEB's bundled SDK reads credentials from:

```text
$PI_CODING_AGENT_DIR/auth.json
```

With the OMP bridge, that means:

```text
~/.omp/agent/auth.json
```

Credentials may also exist elsewhere depending on how OMP was set up:

- `~/.pi/agent/auth.json`
- `~/.omp/agent/agent.db`
- environment variables
- `~/.omp/agent/.env`

### Inspect credential locations without printing secrets

Use key/provider names only. Do not print token values.

Example Python snippet:

```bash
python3 - <<'PY'
import json
from pathlib import Path

for p in [Path('~/.omp/agent/auth.json').expanduser(), Path('~/.pi/agent/auth.json').expanduser()]:
    if p.exists():
        data = json.loads(p.read_text() or '{}')
        print(p, sorted(data.keys()))
PY
```

For SQLite-backed OMP auth, inspect only metadata:

```bash
sqlite3 ~/.omp/agent/agent.db \
  "SELECT provider, credential_type, disabled_cause IS NOT NULL AS disabled, identity_key IS NOT NULL AS has_identity FROM auth_credentials;"
```

### Copy compatible upstream Pi auth

If `~/.pi/agent/auth.json` contains credentials that PI WEB should use, and `~/.omp/agent/auth.json` is empty or missing, copy it:

```bash
cp ~/.omp/agent/auth.json ~/.omp/agent/auth.json.before-pi-web-auth 2>/dev/null || true
cp ~/.pi/agent/auth.json ~/.omp/agent/auth.json
chmod 600 ~/.omp/agent/auth.json
pi-web restart
```

Verify through PI WEB:

```text
http://127.0.0.1:8504/api/auth/providers
```

or, if bound to port 80:

```text
http://127.0.0.1/api/auth/providers
```

Providers should show:

```json
{
  "configured": true,
  "source": "stored"
}
```

### Add an API-key provider from OMP's auth database

If OMP stores a provider API key in `~/.omp/agent/agent.db`, merge it into `~/.omp/agent/auth.json` in upstream Pi auth-file format:

```json
{
  "provider-id": {
    "type": "api_key",
    "key": "..."
  }
}
```

Provider IDs must match the IDs known to PI WEB's bundled SDK, such as:

```text
openai
openai-codex
opencode-go
opencode
google
google-vertex
anthropic
mistral
openrouter
xai
```

For example, `opencode-go` uses:

```json
{
  "opencode-go": {
    "type": "api_key",
    "key": "..."
  }
}
```

After editing:

```bash
chmod 600 ~/.omp/agent/auth.json
pi-web restart
```

### Add an API-key provider from an env file

If you have a key in `~/.omp/agent/.env`, either:

1. copy the literal key into `auth.json`; or
2. configure the service environment and use an env reference in `auth.json`.

Example auth-file entry using an env var:

```json
{
  "google": {
    "type": "api_key",
    "key": "$GEMINI_API_KEY"
  }
}
```

If using env references, ensure the PI WEB services actually receive that env var.

## 9. Provider Compatibility Caveats

Provider credentials are useful only if PI WEB's bundled SDK supports that provider.

A provider is compatible when all of these are true:

- it appears in `/api/auth/providers`, or is available as a custom model/provider supported by the SDK;
- the bundled SDK has an auth resolver for it;
- the bundled SDK has model catalog entries or a valid custom `models.json` configuration;
- the bundled SDK has an API transport implementation for its API type.

If OMP supports a provider but PI WEB's SDK does not, PI WEB cannot use it merely by copying credentials.

### Google Antigravity example

OMP may contain a `google-antigravity` OAuth credential, for example in `~/.omp/agent/agent.db`.

However, current PI WEB npm builds using `@earendil-works/pi-coding-agent 0.80.3` do not support Google Antigravity. The installed SDK changelog states:

```text
0.71.0 Breaking Changes:
Removed built-in Google Gemini CLI and Google Antigravity support.
Existing configurations using those providers must switch to another supported provider.
```

Runtime behavior:

- `google-antigravity` is not listed by `/api/auth/providers`.
- `google-antigravity` is not present in the bundled provider registry.
- `google-antigravity` is not present in the bundled model catalog.
- OAuth credentials for unknown providers cannot be refreshed or converted into API keys.

The bundled SDK's auth logic requires a known OAuth provider:

```js
if (cred?.type === "oauth") {
  const provider = getOAuthProvider(providerId);
  if (!provider) return undefined;
}
```

So copying an OMP `google-antigravity` OAuth credential into `auth.json` is not enough.

To use Google Antigravity in PI WEB, one of these would be required:

1. a PI WEB release built against a Pi/OMP runtime that still includes `google-antigravity`;
2. a PI WEB plugin/custom provider that implements Antigravity auth, models, and transport;
3. a PI WEB execution mode that delegates model execution to the installed `omp` binary instead of PI WEB's bundled SDK.

## 10. Smoke Test

After setup:

1. Open PI WEB.
2. Add a project.
3. Choose a workspace.
4. Start a session.
5. Confirm models are available.
6. Send a harmless prompt such as:

```text
Print the current working directory and list the top-level files.
```

Verify:

- session starts;
- transcript streams;
- tool execution works;
- browser refresh does not kill the session;
- session files appear under `~/.omp/agent/sessions`;
- expected providers are configured at `/api/auth/providers`.

## Troubleshooting

### `No API key found for the selected model`

Likely causes:

- `PI_CODING_AGENT_DIR` points to an agent dir whose `auth.json` lacks the selected provider.
- Credentials exist in `~/.pi/agent/auth.json`, but PI WEB is reading `~/.omp/agent/auth.json`.
- Credentials exist in OMP's SQLite auth database but have not been converted into upstream Pi `auth.json` format.
- Provider exists in OMP but not in PI WEB's bundled SDK.

Checks:

```bash
pi-web status
pi-web logs
cat ~/.config/environment.d/10-pi-web-omp.conf
```

Check provider status:

```bash
curl http://127.0.0.1:8504/api/auth/providers
```

or:

```bash
curl http://127.0.0.1/api/auth/providers
```

### `pi-web doctor` cannot find `pi`

Check the shim:

```bash
command -v pi
pi --version
```

Check through login shell:

```bash
zsh -lc 'command -v pi && pi --version'
```

If systemd user checks fail, ensure the shim directory is in login-shell PATH, not only interactive-shell PATH.

### Services start but use `~/.pi/agent`

The service did not receive `PI_CODING_AGENT_DIR`.

Fix systemd user environment:

```bash
systemctl --user set-environment PI_CODING_AGENT_DIR=$HOME/.omp/agent
pi-web restart
```

Persist it:

```bash
mkdir -p ~/.config/environment.d
cat > ~/.config/environment.d/10-pi-web-omp.conf <<EOF
PI_CODING_AGENT_DIR=$HOME/.omp/agent
EOF
```

### Port 80 fails

Use a higher port, e.g. `8504`, or check low-port policy:

```bash
sysctl net.ipv4.ip_unprivileged_port_start
```

If low ports are privileged on your system, use a reverse proxy or run on a high port.

## Useful Commands

```bash
pi-web status
pi-web doctor
pi-web logs
pi-web restart
pi-web version
```

Uninstall PI WEB services:

```bash
pi-web uninstall
```

Remove package:

```bash
npm uninstall -g @jmfederico/pi-web
```

## Summary

The essential integration points are:

1. Install Node.js `>=22` and npm.
2. Add a `pi` shim that invokes `omp`.
3. Persist `PI_CODING_AGENT_DIR=$HOME/.omp/agent` into the PI WEB service environment.
4. Install PI WEB globally and run `pi-web install`.
5. Copy or merge compatible credentials into `$PI_CODING_AGENT_DIR/auth.json`.
6. Verify providers through `/api/auth/providers`.
7. Remember that provider support comes from PI WEB's bundled Pi SDK, not from the local OMP binary.