└─$ 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.