OMP Session Gateway

Every live OMP session. One private mobile page.

An Android-first PWA that auto-discovers running
Oh My Pi sessions, alerts you when one needs input,
and opens the exact encrypted OMP collaboration surface — without QR codes or copied links.

Website · Build and run ·
How it works · Security model ·
Compatibility ·
Latest release

_{Private by design: loopback-only gateway · allowlisted tailnet identity · memory-only capabilities · no transcript storage}

Qualified for stable v0.3.0 — exact patched OMP v18.1.14.
Phone Take photo / Choose existing, native MathML, reconnect tail recovery, and
configuration-preserving upgrades are qualified through signed candidate
v0.3.0-prealpha.3.
Fresh Debian 13 x86-64, macOS 26.6.1 arm64, and Chrome 152 / Android 17 Pixel qualification,
eight-hour relay endurance, and candidate-to-stable runtime equivalence passed.
No historical qualification transfers. Stable publication is recorded on the
v0.3.0 release page.

Tailscale Serve with the TUN-mode client, Funnel disabled, exact patched OMP v18.1.14, and
Bun 1.4.0 are mandatory. Windows, background Push qualification, Portal Tunnel, userspace
networking, and self-hosted/proxied relays remain outside the stable support claim. Details:
Compatibility and release status ·
compatibility matrix · release ledger.

OMP Session Gateway is a local-first companion for Oh My Pi (OMP). The terminal remains the source
of truth: the gateway is a private directory for already-running interactive OMP processes, a
metadata-only attention queue, and a just-in-time View/Control capability broker — not a
second agent client. Opening a session hands off to OMP's existing encrypted collab-web
interface; the gateway never stores or renders transcripts.

This is a community project and is not affiliated with or endorsed by the Oh My Pi maintainers.

How it works

Every session, automatically No per-session command, QR scan, or link copy.

The oldest ask first Bounded metadata outside; the authoritative prompt stays in OMP.

One tap to the real session View or Control opens OMP's existing encrypted client.

_{All media on this page is captured from the built app and pinned collaboration client, driven
by seeded synthetic fixture data — no real sessions, hosts, accounts, or capabilities. The media
reflects its recorded capture baseline, not qualification of the current OMP pin. Regeneration
steps: docs/media/README.md · MP4 master:
omp-session-gateway-demo.mp4.}

The problem

OMP's /collab feature already provides an excellent browser experience, but each running session
must be started and opened individually — a per-session command, then a link or QR code moved to
the phone. With several terminals that does not scale. The gateway removes that per-session
ceremony without widening exposure: it lists every live OMP session automatically, surfaces a
metadata-only Needs you state when one is waiting for human input, opens read-only or
full-control collaboration in one tap, removes stale sessions on its own, and keeps collaboration
capabilities out of the public Internet, logs, notifications, and persistent browser storage.

User experience

After installation and tailnet configuration:

1. omp-gatewayd starts automatically when the desktop user logs in; omp-gateway serve provides
   the equivalent foreground/development entry point.
2. Tailscale Serve exposes only the loopback dashboard/API to approved tailnet identities.
3. Each interactive omp process automatically starts collaboration when configured and registers
   its current view/control capability through authenticated local IPC.
4. The Android PWA lists every live process within a few seconds: a FIFO Needs you queue when
   anything is waiting, otherwise All clear and the working sessions.
5. Open request launches Control for the oldest ask; Hold for desk defers that exact ask on
   this device and advances to the next one without clearing attention; Transcript stays
   read-only. Hide can remove a non-attention row on this device with Undo and Show all,
   but OMP keeps running. The healthy gateway shell stays quiet, distinguishes gateway and relay
   interruptions when they persist, and keeps each answer at Sending… until OMP acknowledges
   it. After an authoritative answer, it offers the next ask or returns to the exact directory
   order and scroll position.
6. Experimental outside the stable core claim: the Settings sheet behind the masthead control can enable
   background Web Push alerts and choose Private, Session, or Preview detail. The no-store tap
   path is implemented and capability-free, but closed-PWA/lock-screen/force-stop/network behavior
   is not stable-qualified.
7. Session switches, exits, crashes, daemon restarts, and ordinary foreground/online transport
   replacement reconcile without a prominent Refresh control. Abrupt Android radio transitions do
   not reliably self-heal and may require force-stopping Chrome.

_{Notification detail is chosen per device; payloads are built at the chosen level — the phone never redacts.}

Compatibility and release status

Support is qualified for exact combinations, not platform families. The v0.3.0 support boundary is:

Current upstream baseline. This checkout targets OMP v18.1.14,
commit daf07999c2fee9b22edc7bf8fea1fb6272e0df5e, observed 2026-09-08.
Stock OMP is insufficient: use the exact controller/publisher patch and versioned build route in
patches/oh-my-pi/README.md.
Exact source and package metadata: UPSTREAM.lock.json.

Historical v0.2.1 and v0.3.0-prealpha.2 retain their recorded patched v17.4.1 baseline.
Use each release's matching source and instructions when rolling back; gateway rollback does not
switch the OMP binary. The v18.1.14 matrix and endurance evidence were rerun independently.

Known limits are part of the claim — read them before installing:

• TUN mode is mandatory. With userspace-networking tailscaled there is no tunnel device,
  every tailnet peer arrives as a loopback peer, and the gateway fails closed rather than believing
  an identity header (#98). See
  Build and run for the doctor signal.
• Never enable Tailscale Funnel. There is no supported public-Internet path.
• Android radio transitions have a browser-process limitation. Chrome for Android can wedge its
  process-wide network stack after a radio change while Android remains healthy. The PWA retries
  and, after 45 seconds of uninterrupted visible failure, opens force-stop/reopen help already
  loaded in the PWA shell; it does not
  claim page JavaScript can repair Chrome (#65).
• Background Web Push is outside the stable core claim. Repository and desktop Chromium
  coverage exists, but the exact physical closed-PWA, lock-screen, tap-to-Control,
  stale-generation, force-stop, network-change, and forbidden-sink matrix has not passed.
• Preview notification detail currently falls back to Session detail — the OMP publisher
  carries no bounded preview field yet.
• Windows source acceptance passes, but Windows is not advertised. A persistent Server 2025 VM
  passed install, reboot→interactive-login startup, doctor 17/17, rotation, upgrade/rollback,
  patched OMP publication, and uninstall. Exact signed gateway/OMP artifacts must repeat the lane
  before support is claimed (#90).
• Untrusted local accounts are out of scope. V1 assumes a user-controlled workstation: a direct
  loopback caller can forge non-cryptographic Tailscale identity headers. Do not deploy on a shared
  shell host.
• Portal Tunnel and self-hosted or proxied relay modes are unsupported. The gateway supports only
  Tailscale Serve and keeps OMP's existing end-to-end-encrypted relay.

The compatibility matrix defines the supported boundary; the
release ledger holds the exact per-candidate evidence and is
authoritative where they disagree.

Build and run

Use the signed v0.3.0 archive
for a qualified installation, or check out the exact v0.3.0 source tag before building.
Unreleased changes on main do not inherit qualification. Both routes require Bun 1.4.0
and the exact patched OMP v18.1.14 prerequisite:

bun install --frozen-lockfile
bun run check

# Loopback-only development mode
bun apps/gateway/src/cli.ts serve \
  --dev-localhost \
  --port 4317 \
  --origin http://127.0.0.1:4317

Production installation requires an exact tailnet HTTPS origin and at least one normalized
Tailscale login:

bun run build
bun apps/gateway/src/cli.ts install \
  --origin https://host.tailnet.ts.net \
  --allow [email protected]
bun apps/gateway/src/cli.ts serve-guidance
bun apps/gateway/src/cli.ts doctor

Run Tailscale's TUN-mode client on the gateway host. With
tailscaled --tun=userspace-networking there is no tunnel device, so its netstack forwards inbound
tailnet connections to localhost and every tailnet peer reaches the loopback listener as a
loopback peer. The daemon detects that and returns 403 to every request rather than believing an
identity header, doctor reports loopbackTrustSound: false, and the log carries one
http.identity_trust_unsound. If a correctly configured host is refused, that check is what to
look at first.

Never enable Tailscale Funnel. Stock OMP is insufficient: build and launch participating sessions
with the exact versioned v18.1.14 patch route in
patches/oh-my-pi/README.md,
then set collab.autoStart to view or control; see
docs/OPERATIONS.md.

Build the deterministic Bun-runtime archive and checksum manifest with bun run release:build.
An archive is qualified only for the exact platform and candidate combination recorded in
docs/RELEASE_STATUS.md; a build from main carries no native
qualification until a lane has been run against those bytes and its record attached to a tag.

Architecture

flowchart LR
    OMP1[OMP process A] -->|user-only IPC| GATEWAY[Session Gateway daemon]
    OMP2[OMP process B] -->|user-only IPC| GATEWAY
    OMPN[OMP process N] -->|user-only IPC| GATEWAY

    PHONE[Android PWA] -->|tailnet HTTPS| SERVE[Tailscale Serve]
    SERVE -->|loopback HTTP + identity headers| GATEWAY

    PHONE -->|encrypted collaboration frames| RELAY[OMP relay]
    OMP1 -->|encrypted collaboration frames| RELAY
    OMP2 -->|encrypted collaboration frames| RELAY
    GATEWAY -->|encrypted metadata-only push| PUSH[Browser push service]
    PUSH -->|wake service worker| PHONE

The recommended v1 keeps OMP's existing end-to-end-encrypted relay and uses the gateway only for
private discovery and just-in-time capability delivery. A self-hosted relay remains an optional
later deployment mode. Deeper detail: architecture ·
protocol · operations.

Why PWA first

OMP already ships packages/collab-web, which renders the transcript, streaming output, tool
cards, prompts, interrupts, and subagent controls. A native Android client would duplicate the most
security-sensitive and compatibility-sensitive parts of OMP.

The v1 path is therefore:

• mobile-first PWA for the session directory;
• existing OMP collab-web for the actual session;
• optional Trusted Web Activity packaging later; and
• no independent native implementation of OMP's collaboration protocol.

Security model

OMP collaboration links are bearer capabilities. The implementation treats both view and control
links as secrets.

Release-blocking invariants include:

• capabilities remain in OMP/gateway/browser memory only;
• list and SSE APIs return metadata only;
• launch capabilities are fetched only after an explicit tap and use Cache-Control: no-store;
• no capability enters logs, telemetry, crash reports, files, cookies, Local Storage, IndexedDB, Cache Storage, query strings, or service-worker caches;
• the HTTP server binds only to loopback by default;
• identity headers are believed only while Tailscale's tunnel device is present, because a
  userspace-networking tailscaled forwards inbound tailnet traffic to that loopback listener and
  the caller then arrives indistinguishable from a local one;
• production requests require a verified and allowlisted Tailscale identity;
• the local registry uses user-only IPC plus a random 256-bit installation token;
• stale and replaced generations become unlaunchable promptly; and
• the default deployment never enables Tailscale Funnel.

See the threat model and security reporting policy.

How it compares

Remote access to live OMP sessions is an active ecosystem — see the upstream
discussion that inventories these efforts.
The comparison below was source-verified against each project's public README and package metadata
on 2026-08-21, with release metadata and PR #1143 status refreshed 2026-09-08.
The other projects’ feature descriptions remain that dated snapshot; check current documentation before
choosing. None of them — including this one — is affiliated with or endorsed by the Oh My Pi
maintainers, and OMP itself may grow first-party enrollment and session listing
(oh-my-pi#6171,
oh-my-pi#6354) that would reshape this landscape.

Where each one shines:

• omp-deck has the strongest around-the-chat workflow layer — kanban, routines, a knowledge
  base, an inbox, plan-mode approvals, and durable resumable sessions. Choose it when the browser
  should be a persistent cockpit and hosting sessions inside it is acceptable.
• oh-my-portal has the broadest agent coverage, and is the only one offering full terminal
  access and per-person teammate sharing from a phone, with conversational skill-driven setup.
• claudecodeui (CloudCLI) has the most established distribution — npm, Docker, desktop apps,
  and a hosted cloud — but the linked OMP integration proposal was closed without merging; do not infer OMP
  support from it.
• pi-agent-dashboard is the richest dashboard in the pi ecosystem (session spawning, flows,
  OpenSpec, plugins, polished installers) — but it targets pi, not OMP.
• OMP Session Gateway is the only one that attaches through OMP's own encrypted collaboration
  path and reuses the exact upstream client, with zero-touch discovery of terminal sessions, a
  metadata-only attention queue, memory-only capability handling, and per-release qualification
  evidence. The cost of that approach today is an exact OMP version pin plus the repository's
  controller/publisher patch.

Choose OMP Session Gateway when the desired change is narrowly: “make every current terminal OMP
session safely reachable from my phone without copying links.” Choose one of the others when the
desired change is a broader browser-first working environment, multi-agent coverage, or raw
terminal access. The gateway is intentionally not a chat rewrite, task system, routine engine,
knowledge base, or messaging hub; reusing collab-web is the point.

Repository layout

Contributing and releases

The project is intended to be developed in public. See:

• Contributing
• Backlog
• Release status
• Security policy

The project has no telemetry, analytics, or hosted control plane.

License

MIT. See LICENSE.