Like 0
Fork 0

Last active 1 month ago

bartoo's Avatar bartoo revised this gist 1 month ago. Go to revision

1 file changed, 680 insertions

pi-web-omp.md(file created)

@@ -0,0 +1,680 @@
1 + └─$ cat /tmp/pi-web-omp.md
2 + # Running PI WEB with Oh My Pi (OMP)
3 +
4 + 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.
5 +
6 + 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.
7 +
8 + ## What Works
9 +
10 + With the setup below, PI WEB can:
11 +
12 + - run as persistent user services;
13 + - expose a browser UI for projects, workspaces, sessions, files, and terminals;
14 + - store/read sessions from OMP's agent directory;
15 + - use compatible credentials from OMP/Pi auth state;
16 + - use providers supported by PI WEB's bundled Pi SDK.
17 +
18 + ## Important Limitation
19 +
20 + PI WEB does **not** execute model requests through your installed `omp` binary. It uses its own bundled upstream Pi SDK from the npm package:
21 +
22 + ```text
23 + @jmfederico/pi-web/node_modules/@earendil-works/pi-coding-agent
24 + ```
25 +
26 + That means provider support is determined by the PI WEB bundle, not by the local OMP binary.
27 +
28 + 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.
29 +
30 + ## Requirements
31 +
32 + Install these first:
33 +
34 + - Linux/macOS/WSL with a supported user-service manager, or use PI WEB's manual process mode.
35 + - Node.js `>=22`.
36 + - npm.
37 + - OMP installed and working for the same user.
38 + - Git and the development tools your agents need.
39 + - A login shell that exposes `node`, `npm`, `omp`, and the compatibility `pi` shim.
40 +
41 + Check OMP:
42 +
43 + ```bash
44 + command -v omp
45 + omp --version
46 + ```
47 +
48 + Check Node/npm:
49 +
50 + ```bash
51 + node --version
52 + npm --version
53 + ```
54 +
55 + 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:
56 +
57 + - zsh: `~/.zprofile`
58 + - bash: `~/.bash_profile` or `~/.profile`
59 + - fish: universal PATH setup such as `fish_add_path -U ...`
60 +
61 + ## 1. Back Up Existing Agent State
62 +
63 + Before changing auth or session state, back up both OMP and upstream Pi directories if they exist:
64 +
65 + ```bash
66 + mkdir -p ~/backups
67 + 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
68 + ```
69 +
70 + ## 2. Install Node.js and npm
71 +
72 + PI WEB requires Node.js 22 or newer.
73 +
74 + Use your OS package manager, NodeSource, Homebrew, mise/asdf shims, or another method that is visible to login shells and user services.
75 +
76 + Verify through the login shell PI WEB will use:
77 +
78 + ```bash
79 + zsh -lc 'node --version && npm --version'
80 + # or
81 + bash -lc 'node --version && npm --version'
82 + ```
83 +
84 + The Node major version must be `22` or newer.
85 +
86 + ## 3. Add a `pi` Compatibility Shim
87 +
88 + 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.
89 +
90 + Common location:
91 +
92 + ```bash
93 + mkdir -p ~/.local/bin
94 + cat > ~/.local/bin/pi <<'EOF'
95 + #!/usr/bin/env sh
96 + exec "$HOME/.local/bin/omp" "$@"
97 + EOF
98 + chmod +x ~/.local/bin/pi
99 + ```
100 +
101 + If your `omp` binary lives somewhere else, adjust the `exec` path or use:
102 +
103 + ```sh
104 + exec omp "$@"
105 + ```
106 +
107 + Verify:
108 +
109 + ```bash
110 + zsh -lc 'command -v pi && pi --version && command -v omp && omp --version'
111 + ```
112 +
113 + Expected result: both `pi` and `omp` resolve, and `pi --version` prints the OMP version.
114 +
115 + ## 4. Point PI WEB at OMP's Agent Directory
116 +
117 + OMP's active state is normally under:
118 +
119 + ```text
120 + ~/.omp/agent
121 + ```
122 +
123 + Upstream Pi's default is normally:
124 +
125 + ```text
126 + ~/.pi/agent
127 + ```
128 +
129 + PI WEB's bundled SDK uses `PI_CODING_AGENT_DIR` to choose the agent directory. Set it to OMP's agent directory:
130 +
131 + ```text
132 + PI_CODING_AGENT_DIR=$HOME/.omp/agent
133 + ```
134 +
135 + ### systemd user services
136 +
137 + For Linux systemd user services, persist the env var:
138 +
139 + ```bash
140 + mkdir -p ~/.config/environment.d
141 + cat > ~/.config/environment.d/10-pi-web-omp.conf <<EOF
142 + PI_CODING_AGENT_DIR=$HOME/.omp/agent
143 + EOF
144 +
145 + systemctl --user daemon-reload
146 + systemctl --user set-environment PI_CODING_AGENT_DIR=$HOME/.omp/agent
147 + ```
148 +
149 + Verify:
150 +
151 + ```bash
152 + systemctl --user show-environment | grep PI_CODING_AGENT_DIR
153 + ```
154 +
155 + ### Why this is required
156 +
157 + Passing the env var only to `pi-web install` is not enough:
158 +
159 + ```bash
160 + PI_CODING_AGENT_DIR=$HOME/.omp/agent pi-web install
161 + ```
162 +
163 + 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.
164 +
165 + ### Wrapper alternative
166 +
167 + If you do not want to rely on the service manager environment, create wrappers:
168 +
169 + ```bash
170 + mkdir -p ~/.local/bin/pi-web-omp
171 +
172 + cat > ~/.local/bin/pi-web-omp/pi-web-server <<'EOF'
173 + #!/usr/bin/env sh
174 + export PI_CODING_AGENT_DIR="$HOME/.omp/agent"
175 + exec pi-web-server "$@"
176 + EOF
177 +
178 + cat > ~/.local/bin/pi-web-omp/pi-web-sessiond <<'EOF'
179 + #!/usr/bin/env sh
180 + export PI_CODING_AGENT_DIR="$HOME/.omp/agent"
181 + exec pi-web-sessiond "$@"
182 + EOF
183 +
184 + chmod +x ~/.local/bin/pi-web-omp/pi-web-server ~/.local/bin/pi-web-omp/pi-web-sessiond
185 + ```
186 +
187 + Then install services with executable overrides:
188 +
189 + ```bash
190 + PI_WEB_SERVER_EXEC="$HOME/.local/bin/pi-web-omp/pi-web-server" \
191 + PI_WEB_SESSIOND_EXEC="$HOME/.local/bin/pi-web-omp/pi-web-sessiond" \
192 + pi-web install
193 + ```
194 +
195 + ## 5. Create PI WEB Config
196 +
197 + PI WEB config lives at:
198 +
199 + ```text
200 + ~/.config/pi-web/config.json
201 + ```
202 +
203 + Safe local-only starting config:
204 +
205 + ```bash
206 + mkdir -p ~/.config/pi-web
207 + cat > ~/.config/pi-web/config.json <<'EOF'
208 + {
209 + "host": "127.0.0.1",
210 + "port": 8504,
211 + "spawnSessions": true,
212 + "subsessions": false,
213 + "pathAccess": {
214 + "allowedPaths": []
215 + }
216 + }
217 + EOF
218 + ```
219 +
220 + Open locally at:
221 +
222 + ```text
223 + http://127.0.0.1:8504
224 + ```
225 +
226 + For remote access, prefer an SSH tunnel:
227 +
228 + ```bash
229 + ssh -L 8504:127.0.0.1:8504 user@host
230 + ```
231 +
232 + Then open locally:
233 +
234 + ```text
235 + http://127.0.0.1:8504
236 + ```
237 +
238 + ### Optional: bind to all interfaces
239 +
240 + If you intentionally want PI WEB reachable on the network, update:
241 +
242 + ```json
243 + {
244 + "host": "0.0.0.0",
245 + "port": 80
246 + }
247 + ```
248 +
249 + Then restart:
250 +
251 + ```bash
252 + pi-web restart
253 + ```
254 +
255 + Check whether unprivileged users may bind low ports:
256 +
257 + ```bash
258 + sysctl net.ipv4.ip_unprivileged_port_start
259 + ```
260 +
261 + 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.
262 +
263 + 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.
264 +
265 + ## 6. Install PI WEB
266 +
267 + Install the npm package globally:
268 +
269 + ```bash
270 + npm install -g @jmfederico/pi-web
271 + ```
272 +
273 + Depending on your npm prefix, you may need `sudo`:
274 +
275 + ```bash
276 + sudo npm install -g @jmfederico/pi-web
277 + ```
278 +
279 + Verify:
280 +
281 + ```bash
282 + command -v pi-web
283 + command -v pi-web-server
284 + command -v pi-web-sessiond
285 + pi-web version
286 + ```
287 +
288 + Install user services:
289 +
290 + ```bash
291 + pi-web install
292 + ```
293 +
294 + Check:
295 +
296 + ```bash
297 + pi-web doctor
298 + pi-web status
299 + ```
300 +
301 + Expected required checks:
302 +
303 + ```text
304 + node >= 22 found
305 + npm found
306 + pi found
307 + pi-web-server found
308 + pi-web-sessiond found
309 + session daemon running
310 + web server running
311 + ```
312 +
313 + Optional warnings such as missing `rg` are not fatal. Installing ripgrep improves file suggestion performance:
314 +
315 + ```bash
316 + sudo apt-get install -y ripgrep
317 + ```
318 +
319 + ## 7. Verify the Agent Directory Bridge
320 +
321 + After services start, confirm the running session daemon has the expected env var.
322 +
323 + Get the session daemon PID:
324 +
325 + ```bash
326 + systemctl --user show pi-web-sessiond.service --property=MainPID --value
327 + ```
328 +
329 + Check the process environment:
330 +
331 + ```bash
332 + tr '\0' '\n' < /proc/<PID>/environ | grep PI_CODING_AGENT_DIR
333 + ```
334 +
335 + Expected:
336 +
337 + ```text
338 + PI_CODING_AGENT_DIR=/home/<user>/.omp/agent
339 + ```
340 +
341 + Then open PI WEB and create a test session in a harmless workspace. Confirm new session files are created under:
342 +
343 + ```text
344 + ~/.omp/agent/sessions/
345 + ```
346 +
347 + not primarily under:
348 +
349 + ```text
350 + ~/.pi/agent/sessions/
351 + ```
352 +
353 + ## 8. Configure Provider Credentials
354 +
355 + PI WEB's bundled SDK reads credentials from:
356 +
357 + ```text
358 + $PI_CODING_AGENT_DIR/auth.json
359 + ```
360 +
361 + With the OMP bridge, that means:
362 +
363 + ```text
364 + ~/.omp/agent/auth.json
365 + ```
366 +
367 + Credentials may also exist elsewhere depending on how OMP was set up:
368 +
369 + - `~/.pi/agent/auth.json`
370 + - `~/.omp/agent/agent.db`
371 + - environment variables
372 + - `~/.omp/agent/.env`
373 +
374 + ### Inspect credential locations without printing secrets
375 +
376 + Use key/provider names only. Do not print token values.
377 +
378 + Example Python snippet:
379 +
380 + ```bash
381 + python3 - <<'PY'
382 + import json
383 + from pathlib import Path
384 +
385 + for p in [Path('~/.omp/agent/auth.json').expanduser(), Path('~/.pi/agent/auth.json').expanduser()]:
386 + if p.exists():
387 + data = json.loads(p.read_text() or '{}')
388 + print(p, sorted(data.keys()))
389 + PY
390 + ```
391 +
392 + For SQLite-backed OMP auth, inspect only metadata:
393 +
394 + ```bash
395 + sqlite3 ~/.omp/agent/agent.db \
396 + "SELECT provider, credential_type, disabled_cause IS NOT NULL AS disabled, identity_key IS NOT NULL AS has_identity FROM auth_credentials;"
397 + ```
398 +
399 + ### Copy compatible upstream Pi auth
400 +
401 + If `~/.pi/agent/auth.json` contains credentials that PI WEB should use, and `~/.omp/agent/auth.json` is empty or missing, copy it:
402 +
403 + ```bash
404 + cp ~/.omp/agent/auth.json ~/.omp/agent/auth.json.before-pi-web-auth 2>/dev/null || true
405 + cp ~/.pi/agent/auth.json ~/.omp/agent/auth.json
406 + chmod 600 ~/.omp/agent/auth.json
407 + pi-web restart
408 + ```
409 +
410 + Verify through PI WEB:
411 +
412 + ```text
413 + http://127.0.0.1:8504/api/auth/providers
414 + ```
415 +
416 + or, if bound to port 80:
417 +
418 + ```text
419 + http://127.0.0.1/api/auth/providers
420 + ```
421 +
422 + Providers should show:
423 +
424 + ```json
425 + {
426 + "configured": true,
427 + "source": "stored"
428 + }
429 + ```
430 +
431 + ### Add an API-key provider from OMP's auth database
432 +
433 + 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:
434 +
435 + ```json
436 + {
437 + "provider-id": {
438 + "type": "api_key",
439 + "key": "..."
440 + }
441 + }
442 + ```
443 +
444 + Provider IDs must match the IDs known to PI WEB's bundled SDK, such as:
445 +
446 + ```text
447 + openai
448 + openai-codex
449 + opencode-go
450 + opencode
451 + google
452 + google-vertex
453 + anthropic
454 + mistral
455 + openrouter
456 + xai
457 + ```
458 +
459 + For example, `opencode-go` uses:
460 +
461 + ```json
462 + {
463 + "opencode-go": {
464 + "type": "api_key",
465 + "key": "..."
466 + }
467 + }
468 + ```
469 +
470 + After editing:
471 +
472 + ```bash
473 + chmod 600 ~/.omp/agent/auth.json
474 + pi-web restart
475 + ```
476 +
477 + ### Add an API-key provider from an env file
478 +
479 + If you have a key in `~/.omp/agent/.env`, either:
480 +
481 + 1. copy the literal key into `auth.json`; or
482 + 2. configure the service environment and use an env reference in `auth.json`.
483 +
484 + Example auth-file entry using an env var:
485 +
486 + ```json
487 + {
488 + "google": {
489 + "type": "api_key",
490 + "key": "$GEMINI_API_KEY"
491 + }
492 + }
493 + ```
494 +
495 + If using env references, ensure the PI WEB services actually receive that env var.
496 +
497 + ## 9. Provider Compatibility Caveats
498 +
499 + Provider credentials are useful only if PI WEB's bundled SDK supports that provider.
500 +
501 + A provider is compatible when all of these are true:
502 +
503 + - it appears in `/api/auth/providers`, or is available as a custom model/provider supported by the SDK;
504 + - the bundled SDK has an auth resolver for it;
505 + - the bundled SDK has model catalog entries or a valid custom `models.json` configuration;
506 + - the bundled SDK has an API transport implementation for its API type.
507 +
508 + If OMP supports a provider but PI WEB's SDK does not, PI WEB cannot use it merely by copying credentials.
509 +
510 + ### Google Antigravity example
511 +
512 + OMP may contain a `google-antigravity` OAuth credential, for example in `~/.omp/agent/agent.db`.
513 +
514 + 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:
515 +
516 + ```text
517 + 0.71.0 Breaking Changes:
518 + Removed built-in Google Gemini CLI and Google Antigravity support.
519 + Existing configurations using those providers must switch to another supported provider.
520 + ```
521 +
522 + Runtime behavior:
523 +
524 + - `google-antigravity` is not listed by `/api/auth/providers`.
525 + - `google-antigravity` is not present in the bundled provider registry.
526 + - `google-antigravity` is not present in the bundled model catalog.
527 + - OAuth credentials for unknown providers cannot be refreshed or converted into API keys.
528 +
529 + The bundled SDK's auth logic requires a known OAuth provider:
530 +
531 + ```js
532 + if (cred?.type === "oauth") {
533 + const provider = getOAuthProvider(providerId);
534 + if (!provider) return undefined;
535 + }
536 + ```
537 +
538 + So copying an OMP `google-antigravity` OAuth credential into `auth.json` is not enough.
539 +
540 + To use Google Antigravity in PI WEB, one of these would be required:
541 +
542 + 1. a PI WEB release built against a Pi/OMP runtime that still includes `google-antigravity`;
543 + 2. a PI WEB plugin/custom provider that implements Antigravity auth, models, and transport;
544 + 3. a PI WEB execution mode that delegates model execution to the installed `omp` binary instead of PI WEB's bundled SDK.
545 +
546 + ## 10. Smoke Test
547 +
548 + After setup:
549 +
550 + 1. Open PI WEB.
551 + 2. Add a project.
552 + 3. Choose a workspace.
553 + 4. Start a session.
554 + 5. Confirm models are available.
555 + 6. Send a harmless prompt such as:
556 +
557 + ```text
558 + Print the current working directory and list the top-level files.
559 + ```
560 +
561 + Verify:
562 +
563 + - session starts;
564 + - transcript streams;
565 + - tool execution works;
566 + - browser refresh does not kill the session;
567 + - session files appear under `~/.omp/agent/sessions`;
568 + - expected providers are configured at `/api/auth/providers`.
569 +
570 + ## Troubleshooting
571 +
572 + ### `No API key found for the selected model`
573 +
574 + Likely causes:
575 +
576 + - `PI_CODING_AGENT_DIR` points to an agent dir whose `auth.json` lacks the selected provider.
577 + - Credentials exist in `~/.pi/agent/auth.json`, but PI WEB is reading `~/.omp/agent/auth.json`.
578 + - Credentials exist in OMP's SQLite auth database but have not been converted into upstream Pi `auth.json` format.
579 + - Provider exists in OMP but not in PI WEB's bundled SDK.
580 +
581 + Checks:
582 +
583 + ```bash
584 + pi-web status
585 + pi-web logs
586 + cat ~/.config/environment.d/10-pi-web-omp.conf
587 + ```
588 +
589 + Check provider status:
590 +
591 + ```bash
592 + curl http://127.0.0.1:8504/api/auth/providers
593 + ```
594 +
595 + or:
596 +
597 + ```bash
598 + curl http://127.0.0.1/api/auth/providers
599 + ```
600 +
601 + ### `pi-web doctor` cannot find `pi`
602 +
603 + Check the shim:
604 +
605 + ```bash
606 + command -v pi
607 + pi --version
608 + ```
609 +
610 + Check through login shell:
611 +
612 + ```bash
613 + zsh -lc 'command -v pi && pi --version'
614 + ```
615 +
616 + If systemd user checks fail, ensure the shim directory is in login-shell PATH, not only interactive-shell PATH.
617 +
618 + ### Services start but use `~/.pi/agent`
619 +
620 + The service did not receive `PI_CODING_AGENT_DIR`.
621 +
622 + Fix systemd user environment:
623 +
624 + ```bash
625 + systemctl --user set-environment PI_CODING_AGENT_DIR=$HOME/.omp/agent
626 + pi-web restart
627 + ```
628 +
629 + Persist it:
630 +
631 + ```bash
632 + mkdir -p ~/.config/environment.d
633 + cat > ~/.config/environment.d/10-pi-web-omp.conf <<EOF
634 + PI_CODING_AGENT_DIR=$HOME/.omp/agent
635 + EOF
636 + ```
637 +
638 + ### Port 80 fails
639 +
640 + Use a higher port, e.g. `8504`, or check low-port policy:
641 +
642 + ```bash
643 + sysctl net.ipv4.ip_unprivileged_port_start
644 + ```
645 +
646 + If low ports are privileged on your system, use a reverse proxy or run on a high port.
647 +
648 + ## Useful Commands
649 +
650 + ```bash
651 + pi-web status
652 + pi-web doctor
653 + pi-web logs
654 + pi-web restart
655 + pi-web version
656 + ```
657 +
658 + Uninstall PI WEB services:
659 +
660 + ```bash
661 + pi-web uninstall
662 + ```
663 +
664 + Remove package:
665 +
666 + ```bash
667 + npm uninstall -g @jmfederico/pi-web
668 + ```
669 +
670 + ## Summary
671 +
672 + The essential integration points are:
673 +
674 + 1. Install Node.js `>=22` and npm.
675 + 2. Add a `pi` shim that invokes `omp`.
676 + 3. Persist `PI_CODING_AGENT_DIR=$HOME/.omp/agent` into the PI WEB service environment.
677 + 4. Install PI WEB globally and run `pi-web install`.
678 + 5. Copy or merge compatible credentials into `$PI_CODING_AGENT_DIR/auth.json`.
679 + 6. Verify providers through `/api/auth/providers`.
680 + 7. Remember that provider support comes from PI WEB's bundled Pi SDK, not from the local OMP binary.
Newer Older

Powered by Opengist ⋅ Load: 44ms⋅

English