OMP Session Gateway

Every live OMP session. One private mobile page.

Native integration with stock OMP 18.1.20+. No fork or custom OMP build.

Keep using Oh My Pi in your terminal. OMP Session Gateway discovers your collaboration-enabled sessions, shows which need attention, and opens OMP's own encrypted View or Control client from your phone — no QR scans, copied links, or per-session setup.

_{Synthetic product demo—not release-qualification evidence. Capture provenance.}

Website · Build and run · How it works · Security model · Compatibility · Stable v0.4.0

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

Works with upstream OMP, not a gateway-specific build. OMP's native collaboration registry shipped in v18.1.20 (PR #11908). Enable collab.autoStart once, install the gateway, and configure Tailscale Serve. Then start sessions with plain omp. Get started with stable v0.4.0 · Exact support and limits · Release evidence.

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.

Build and run

Start with the stable v0.4.0 release, Bun 1.4.0, and stock OMP 18.1.20 or later. Read the exact supported combinations and limits before installing. The gateway and phone need Tailscale on the same tailnet; the gateway host must use the TUN-mode client with Serve over HTTPS. Never enable Funnel.

1. Enable collaboration once in OMP

omp --version # must report at least 18.1.20
omp config set collab.autoStart control # or view for read-only sharing

Then start participating sessions with plain omp. Existing processes do not rerun startup when this setting changes; start new sessions after enabling it. No OMP fork, gateway-specific plugin, custom build, or publisher credential is required.

2. Install the gateway

Download and verify the published archive, then extract omp-session-gateway-0.4.0-bun.tar and enter omp-session-gateway-0.4.0-bun/. The release contains a Bun JavaScript entry point, not standalone native binaries.

Upgrading from v0.3.0 or earlier? Retain its signed archive and private configuration, then use that archive's uninstall command to stop and unregister the old gateway first. Follow the stopped upgrade procedure; do not import a credential bundle. Gateway rollback does not switch the OMP executable.

From the verified release directory:

bun apps/gateway/src/cli.js install \
  --origin https://host.tailnet.ts.net \
  --allow user@example.com
bun apps/gateway/src/cli.js serve-guidance

Use your host's tailnet HTTPS origin and exact Tailscale login. Run the Tailscale Serve command printed by serve-guidance, then check the deployment:

bun apps/gateway/src/cli.js doctor

3. Open OMP Sessions on your phone

Open the configured HTTPS address from your allowlisted, user-authenticated Tailscale device and add OMP Sessions to the home screen. New collaboration-enabled sessions appear on the next discovery poll (10 seconds by default). Tap View or Control; OMP stays in your terminal.

Setup is one-time, not per-session. See operations for discovery overrides, service management, and diagnostics. If doctor reports loopbackTrustSound: false, fix the host's TUN-mode Tailscale setup; do not bypass the identity check.

Build from source for development

Use Bun 1.4.0 in this checkout. A source build does not inherit the signed release's qualification.

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

For a source-based production install, run bun run build, then use the installation commands above with apps/gateway/src/cli.ts instead of the archive's .js entry point. bun run release:build builds the deterministic Bun-runtime archive and checksum manifest; it does not qualify or publish that build.

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 collaboration feature already provides an excellent browser experience. Mainline OMP now starts collaboration and publishes its live hosts automatically when configured; manually opening each link or QR code on a phone still does not scale across several terminals. 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. The gateway reads OMP’s discovery directory and polls metadata; it fetches a capability only when you launch.
4. The Android PWA lists collaboration-enabled processes on the next discovery poll: 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

Published stable v0.4.0 was promoted from qualified candidate v0.4.0-prealpha.1 with identical runtime bytes. Qualification is limited to the exact combinations below; the minimum OMP version does not qualify every host, browser, or future OMP release.

	Current contract
OMP prerequisite	Stock mainline >= 18.1.20; earlier releases lack the local registry
Exact qualified OMP	v18.1.20, commit 1bd60c6fbd0e800a75fd09b1e4804af5a5e6d63b; Bun 1.4.0
OMP settings	collab.autoStart only: off, view, or control
Remote path	Tailscale Serve over tailnet HTTPS, TUN-mode client, Funnel disabled
Qualified Linux host	Debian 13 (trixie) x86-64, Linux 6.12.94+deb13-amd64; 69/69 migration/recovery invariants, stock OMP publication/revocation, persistence, tagged-identity denial/exposure, uninstall and resource teardown
Qualified Mac host	Mac14,3, macOS 26.6.1 arm64; doctor 18/18, rollback 23/23, install/rotation/reboot-to-login persistence, allowlisted identity and forged-header/exposure checks
Qualified core client	Pixel 10 Pro, Android 17 build CP2A.260805.005, Chrome 152.0.7977.82; View read-only, Control writable, prompt accepted, return to directory, same-page lock/Airplane/Doze recovery, seven forbidden capability sinks detectable and clean
Fresh relay check	1,800 seconds, two transitions, final phase live; founder-approved 30-minute gate for v0.4.0, not eight-hour endurance
Migration/rollback predecessor	v0.3.0, fork-era; stopped matching-CLI uninstall/reinstall across the architecture boundary, no credential bundles

Exact source and package metadata: UPSTREAM.lock.json. The upstream merge PR #11908 (4999b98bd5) makes stock OMP sufficient starting with v18.1.20.

The signed-candidate provenance, exact device measurements, and runtime-byte comparison are recorded in the release ledger. Gateway rollback does not switch the OMP executable or restore fork-era configuration. See upgrade and rollback.

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).
• A gateway update can interrupt a pending launch. The worker can still see the directory route while a capability request is in progress; prelaunch route reservation is not implemented. See the current update behavior.
• An initial local View→Control upgrade failed during post-release smoke. Later probes and the full unchanged smoke passed, but the cause remains undetermined; see the release ledger.
• The fresh relay gate is 30 minutes, not eight hours. Eight-hour endurance was not rerun and is not claimed; residual prolonged-operation risk is accepted. No bounded-memory-growth claim follows from this check.
• Specialized attention, branch/resume, and new media qualification are not claimed. The current physical checks qualify the core directory/View/Control path, not these separate lanes.
• 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 snapshot carries no bounded preview field.
• Windows OMP remains unqualified and unadvertised. Exact signed gateway and mainline 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.

Fork-era published-release history

Published v0.3.0 and signed candidate v0.3.0-prealpha.3 retain their exact patched OMP v18.1.14 evidence: Debian 13 x86-64, macOS 26.6.1 arm64, Pixel/Android, relay endurance, and runtime equivalence. Published v0.2.1 retains its fork-era patched OMP v17.4.1 baseline. These archives require their matching source and instructions; no result transfers to mainline.

Fork-era Windows source acceptance on a persistent Server 2025 VM passed install, reboot→interactive-login startup, doctor 17/17, rotation, upgrade/rollback, patched OMP publication, and uninstall. This is historical evidence only, not Windows OMP qualification.

Architecture

flowchart LR
    GATEWAY[Session Gateway daemon] -->|read discovery + query host| OMP1[OMP process A]
    GATEWAY -->|read discovery + query host| OMP2[OMP process B]
    GATEWAY -->|read discovery + query host| OMPN[OMP process N]

    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 -->|experimental encrypted metadata-only push| PUSH[Browser push service]
    PUSH -->|wake service worker| PHONE

Loading

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. Self-hosted or proxied relays remain unsupported; they require separate threat modeling and qualification. 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 are fetched from OMP per launch and never stored by the gateway;
• 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;
• discovery and per-host queries use OMP’s private files, endpoints, and per-host tokens;
• 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

Choose by workflow, not a feature checklist:

• Keep work in running OMP terminals: OMP Session Gateway discovers participating sessions and opens OMP's existing encrypted View/Control client from one private mobile page. Stock OMP ≥18.1.20 supplies the native registry and controller — no fork, custom OMP build, or gateway-specific OMP plugin.
• Move work into a browser-hosted OMP workspace: omp-deck embeds the OMP SDK and shares its session/auth store, with persistent browser sessions and workflow tools such as kanban, routines, and an inbox.
• Choose agent web chat, sharing, or remote terminal access: oh-my-portal provides skills over Portal tunnels. It supports OMP through RPC and an optional omp-collab session-sharing skill.
• Use a browser/mobile workspace for other coding CLIs: CloudCLI (claudecodeui) advertises Claude Code, Cursor CLI, and Codex in its README; that README does not advertise OMP support.
• Use the pi ecosystem: pi-agent-dashboard mirrors pi sessions through a bridge extension. Its README explicitly excludes Oh My Pi.

The gateway still needs one-time setup: a separate install with Bun 1.4.0, collab.autoStart, and TUN-mode Tailscale Serve with an exact allowlist and Funnel disabled. Then use plain omp; no per-session link copying. The minimum OMP version is an integration contract, not qualification of every later version. See exact support and limits.

Primary READMEs and package metadata checked 2026-09-14; this is not a hands-on interoperability or security assessment. The source-linked comparison and upstream discussion provide context.

Repository layout

Path	Purpose
apps/gateway	Loopback daemon, OMP discovery/query reader, launch broker, HTTP API, CLI, services, and diagnostics
apps/web	Mobile session directory PWA and no-secret service worker
packages/protocol	Runtime-validated OMP discovery/query and browser contracts
packages/collab-client	Pinned OMP collab-web source and in-memory bootstrap patch
scripts/build-web.ts	Reproducible hashed PWA/client asset build
scripts/build-release.ts	Deterministic Bun-runtime release archive and SHA-256 manifest
scripts/post-release-smoke.ts	Published-byte local Mac/physical-Android smoke with owned-fixture cleanup
docs/media	Canonical README media plus its seeded-fixture capture provenance
docs/	Architecture, protocol, security, operations, compatibility, and release evidence
UPSTREAM.lock.json	Exact OMP source and package baseline

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.