relmio 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ checks the registry separately after publication.
 
 ## Unreleased
 
+## [0.4.0] - 2026-08-13
+
+### Added
+
+- Add a local Docker wizard for private compatible clients through a
+  Platform-key-backed OpenAI-compatible `/v1` endpoint, plus a separate
+  official experimental Codex App Server target for trusted ChatGPT-sign-in
+  clients.
+- Add compact Ko-fi support links to the hosted navigation and public package
+  guides.
+
+### Changed
+
+- Make the local credential boundary explicit across the product: a Platform
+  API key powers compatible `/v1` requests, while ChatGPT sign-in powers only
+  the experimental Codex App Server protocol.
+
+### Fixed
+
+- Keep the controlling terminal attached when the macOS/Linux installer is
+  piped through `sh`, so the Relmio wizard can open its interactive browser
+  setup flow.
+- Install Homebrew dependencies in their required order during release-candidate
+  validation.
+
+### Security
+
+- Bind local endpoints exclusively to loopback, require one-time Relmio
+  capabilities, pin every managed operation to an attested local Docker
+  socket, and isolate provider credentials in target-specific containers.
+- Restrict the managed Codex endpoint to the ChatGPT login method.
+
+## [0.3.1] - 2026-08-10
+
+### Changed
+
+- Make the browser wizard beginner-friendly with a modern fixed-viewport
+  layout: all five active steps fit without document scrolling on common
+  1280x720 laptops, while progress and safety context stay persistent beside
+  the active task.
+- Keep narrow-phone documents fixed to the viewport and contain unavoidable
+  long-form overflow within the active task panel instead of the page.
+- Expand the GitHub and npm walkthroughs with a hosted-install selector and
+  packaged, sanitized screenshots that document the current n8n workflow.
+
+### Security
+
+- Restore a clean hosted-web dependency audit by pinning patched `js-yaml`
+  and `nanoid` releases and using the compatible `vinext` release that does
+  not include the currently vulnerable `image-size` parser.
+
 ## [0.3.0] - 2026-08-05
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/brand/relmio-mark.svg" alt="Relmio logo" width="88">
   <h1>Relmio</h1>
-  <p>Relay a supported ChatGPT/Codex sign-in to OpenAI-compatible clients, starting with self-hosted n8n.</p>
+  <p>Set up private n8n relays, Platform-key OpenAI-compatible local endpoints, and experimental Codex App Server sessions.</p>
   <p>
     <a href="https://github.com/Demonbane18/relmio">Full guide</a>
     &nbsp;·&nbsp;
@@ -11,32 +11,44 @@
     &nbsp;·&nbsp;
     <a href="https://github.com/Demonbane18/relmio/blob/main/docs/roadmap.md">Roadmap</a>
   </p>
+  <p>
+    <a href="https://ko-fi.com/paldogies"><img src="https://img.shields.io/badge/Ko--fi-support-ff5e5b.svg?logo=ko-fi&logoColor=white" alt="Support Relmio on Ko-fi"></a>
+  </p>
 </div>
 
 ## See it working first
 
-Before setup, this sample n8n configuration shows GPT-5.6 model aliases in the
-OpenAI Chat Model selector. The exact model list depends on the signed-in
-ChatGPT account and can change over time.
+This documented example follows a tested n8n OpenAI credential through a
+published Telegram-triggered workflow. It is a product-operation record, not
+an endorsement, sponsorship, or affiliation by OpenAI, n8n, Hostinger,
+Telegram, or AppBuildersPH.
+
+<figure>
+  <img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/examples/n8n-openai-credential-connected.png" alt="n8n OpenAI credential dialog showing that the connection test succeeded" width="960">
+  <figcaption>The n8n OpenAI credential connection test succeeded; the credential value itself is obscured.</figcaption>
+</figure>
 
 <figure>
-  <img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/examples/gpt-56-model-selector.png" alt="Model selector listing GPT-5.6 Sol, Luna, and Terra model aliases" width="480">
-  <figcaption>Compatibility preview: the model selector includes <code>gpt-5.6-sol</code>, <code>gpt-5.6-luna</code>, and <code>gpt-5.6-terra</code>.</figcaption>
+  <img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/examples/gpt-56-model-selector.png" alt="n8n model selector with gpt-5.6-terra selected and an account-specific model list" width="500">
+  <figcaption>This signed-in account's n8n model list includes <code>gpt-5.6-terra</code>; model availability is account-dependent and can change.</figcaption>
 </figure>
 
-After Relmio completes the installation, Docker shows the existing n8n stack
-and the new private OAuth sidecar running together.
+<figure>
+  <img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/examples/telegram-n8n-workflow-execution.png" alt="Successful n8n execution of a Telegram-triggered workflow with HTTP Request, Basic LLM Chain, and AI Agent branches" width="960">
+  <figcaption>The published Telegram-triggered n8n workflow completed successfully across its HTTP Request, Basic LLM Chain, and AI Agent branches.</figcaption>
+</figure>
 
 <figure>
-  <img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/examples/sidecar-docker-containers-running.png" alt="Docker Desktop showing the n8n and n8n-openai-oauth containers running" width="960">
-  <figcaption>Completed setup: the existing <code>n8n</code> stack and the <code>n8n-openai-oauth</code> sidecar are both running.</figcaption>
+  <img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/examples/telegram-model-results.png" alt="Telegram conversation receiving HTTP Request, Basic LLM Chain, and AI Agent outputs" width="682">
+  <figcaption>Telegram received the HTTP Request, Basic LLM Chain, and AI Agent outputs sent by that workflow.</figcaption>
 </figure>
 
-Relmio is a local browser wizard that installs a private
+Relmio is a local browser wizard with separate setup paths. Its existing
+VPS/n8n path installs a private
 [openai-oauth](https://github.com/EvanZhouDev/openai-oauth) Docker sidecar
-beside an existing self-hosted n8n instance. It guides you through local
-ChatGPT/Codex sign-in, SSH host verification, read-only n8n discovery, an
-exact change plan, and the final n8n credential settings.
+beside an existing self-hosted n8n instance. Its local Docker path can install
+either an OpenAI-compatible gateway backed by a Platform API key or the
+official Codex App Server backed by ChatGPT sign-in.
 
 The existing n8n image, Compose file, container, and workflows stay untouched.
 
@@ -52,7 +64,7 @@ adds the missing capability without changing n8n.
 Try the hosted browser demo at
 [relmio.vercel.app](https://relmio.vercel.app/). It is a separate
 request-bound ChatGPT experience; the npm package remains the local wizard for
-installing the private n8n sidecar.
+the private VPS/n8n sidecar and the separate local Docker endpoint paths.
 
 > **Warning — Hosted chat requires the browser extension.** Install the
 > open-source [Sign in with ChatGPT extension for
@@ -80,10 +92,57 @@ tailored to the current self-hosted n8n and Hostinger VPS setup path.
 The hosted site and local wizard keep the original Relmio relay layout while
 adding a compact **System / Light / Dark** appearance control. System follows
 the computer's preference; Light and Dark are remembered on that browser only.
-The local wizard keeps its horizontal five-step Signal Spine at the top of the
-flow, and the hosted site keeps the live GitHub star/version control visible.
-Both surfaces collapse their controls for narrow phone screens without
-turning the setup flow into a side rail or requiring a separate mobile app.
+On desktop, the local wizard keeps progress and sidecar-only safety notes in a
+persistent rail beside the active task; its compact fixed-screen shell avoids
+document scrolling on common laptop screens. On narrow phones, it switches to
+a horizontal progress strip and keeps task scrolling inside the active panel.
+The hosted site keeps the live GitHub star/version control visible.
+
+## Local Docker endpoints
+
+Choose **Local endpoints** in the browser wizard to install one of these
+Docker services on the same computer as your app:
+
+This local Docker path supports macOS, Linux, and Linux under WSL2. Native
+Windows is not supported in this release because its filesystem permissions do
+not provide the owner-only POSIX mode guarantees used for local credentials.
+The existing VPS/n8n wizard remains available from native Windows.
+
+| Option | Local endpoint | Provider credential | Client type |
+|---|---|---|---|
+| **OpenAI API: compatible clients** | `http://127.0.0.1:12435/v1` by default | Server-side OpenAI Platform API key only | Private local app, SDK, or same-owner development web app |
+| **Codex with ChatGPT: agent clients** | `ws://127.0.0.1:14500` by default | ChatGPT sign-in through Codex | Trusted native Codex/App Server client |
+
+The OpenAI-compatible `/v1` endpoint is powered only by a Platform API key,
+which the wizard seeds over stdin into a private, labeled Docker volume; it
+does not create a host key file. Your app uses a
+separate Relmio capability that the wizard displays once.
+The bearer remains valid until it is rotated. Browser requests
+must come from an exact origin entered during setup; wildcards are not allowed,
+and the capability must never be embedded in a public frontend bundle. Platform
+requests use that API project's billing, credits, limits, and permissions, not
+a ChatGPT subscription.
+
+ChatGPT sign-in powers only the official experimental Codex App Server JSON-RPC
+protocol. It does not expose `/v1`, and Relmio never translates a ChatGPT
+OAuth/session token into a general API credential. OpenAI documents the WebSocket transport as
+experimental and unsupported for production, and it rejects browser-origin
+connections. Use it only with a trusted native client owned by the same person.
+Its capability is high-trust because it can operate the signed-in
+Codex session and files inside the isolated container workspace.
+
+Both services bind exactly to `127.0.0.1`, require the generated capability,
+and mount no host directory or Docker socket. The Codex service gets private
+named credential and workspace volumes. This local path does not connect to a
+VPS or modify n8n.
+
+Read the complete [Local Docker endpoints
+guide](https://github.com/Demonbane18/relmio/blob/main/docs/local-endpoints.md)
+before installing. It includes the wizard steps, client settings, exact-origin
+rules, billing boundary, container isolation, and official OpenAI documentation
+links. The design is documentation-backed engineering guidance, not legal
+advice or an OpenAI approval. Codex for Open Source membership is not treated
+as permission to broaden credential scope or bypass another agreement.
 
 ## Quick start
 
@@ -149,6 +208,10 @@ a browser.
 
 ### Requirements
 
+These requirements are for the VPS/n8n path. For a local Docker endpoint, see
+the [local endpoint
+requirements](https://github.com/Demonbane18/relmio/blob/main/docs/local-endpoints.md#requirements).
+
 - On macOS/Linux/WSL/Git Bash: `curl`, `awk`, `tar`, and either `sha256sum` or
   `shasum`; Git Bash also needs `unzip`
 - On native Windows: Command Prompt uses its built-in `curl`, `certutil`, and
@@ -169,43 +232,68 @@ n8n AI node or HTTP Request
       -> upstream OpenAI service
 ```
 
-Relmio currently provides tested setup instructions for:
+Relmio's existing VPS/n8n path provides tested setup instructions for:
 
 - OpenAI Chat Model
 - AI Agent
 - Basic LLM Chain
 - HTTP Request
 
-The broader direction is to support local chatbots, custom applications,
-OpenAI-compatible clients, and provider adapters without tying the public
-product name to n8n. SuperGrok/xAI OAuth is a gated feasibility item on the
+The local endpoint path described above now supports compatible private apps
+through a Platform-backed gateway and trusted native clients through Codex App
+Server. The broader direction is to add providers and client adapters without
+weakening their authentication boundaries or tying the public product name to
+n8n. SuperGrok/xAI OAuth is a gated feasibility item on the
 [provider roadmap](https://github.com/Demonbane18/relmio/blob/main/docs/roadmap.md);
 it is not currently advertised as supported.
 
 ## Visual walkthrough
 
-All images below are sanitized previews with reserved addresses, fake server
-data, and no real credential or session information.
+These current product screenshots use sanitized sample values wherever a setup
+field might otherwise identify an environment. The VPS identity screen shows a
+reserved sample address and sample SSH fingerprint; none of the images includes
+an OAuth token, password, private key, or live wizard session URL.
+
+### 1. Choose a hosted installation method
+
+<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/00-install-methods.png" alt="Hosted Relmio installation page with macOS/Linux, Homebrew, PowerShell, Command Prompt, and NPX choices" width="720">
+
+The hosted page starts with the installation-method selector. Run the selected
+command locally, not on the VPS.
+
+### 2. Complete the local ChatGPT/Codex sign-in
+
+<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/01-local-sign-in-ready.png" alt="Sanitized preview-mode sample credential state, not a real saved-login confirmation" width="626">
+
+This image shows a sanitized preview-mode sample credential state; it does not
+confirm that a real local ChatGPT login was saved. During a real fresh login,
+the browser confirmation states that the credentials were saved locally.
+
+### 3. Verify the VPS identity
 
-### 1. Confirm the local ChatGPT/Codex sign-in
+<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/02-vps-identity-confirmed.png" alt="VPS identity confirmation with a sanitized sample address and SSH fingerprint" width="720">
 
-<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/01-local-sign-in-ready.png" alt="Sanitized local sign-in ready screen" width="720">
+Confirm the SSH host fingerprint before authentication. The screenshot uses the
+reserved sample host `vps.example.test`, a sample fingerprint, and a blank
+password field.
 
-### 2. Verify the VPS identity
+### 4. Choose the detected n8n container and network
 
-<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/02-vps-identity-confirmed.png" alt="Sanitized VPS fingerprint confirmation screen" width="720">
+<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/03-n8n-detected.png" alt="Detected n8n container and shared Docker network" width="720">
 
-### 3. Choose the detected n8n container and network
+Discovery is read-only; choose the existing n8n container and shared Docker
+network.
 
-<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/03-n8n-detected.png" alt="Sanitized n8n discovery screen" width="720">
+### 5. Review the exact sidecar-only plan
 
-### 4. Review the exact sidecar-only plan
+<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/04-install-plan.png" alt="Exact sidecar-only installation plan, including forbidden actions" width="720">
 
-<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/04-install-plan.png" alt="Sanitized installation plan screen" width="720">
+The plan names the allowed sidecar work and explicitly excludes edits or
+restarts of n8n, a published host port, and a Traefik route.
 
-### 5. Copy the verified n8n settings
+### 6. Copy the verified n8n settings
 
-<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/05-bridge-ready.png" alt="Sanitized verified bridge screen" width="720">
+<img src="https://cdn.jsdelivr.net/npm/relmio@latest/docs/images/setup/05-bridge-ready.png" alt="Private bridge ready screen with n8n OpenAI credential settings" width="720">
 
 Use these values in an n8n OpenAI credential:
 
@@ -265,7 +353,8 @@ has the importable cURL version.
 - Relmio never edits, rebuilds, recreates, stops, or restarts the existing n8n
   container.
 - This is an unofficial community project, not affiliated with or endorsed by
-  OpenAI, xAI, or n8n. Provider access, models, limits, and policies can change.
+  OpenAI, xAI, n8n, Hostinger, Telegram, or AppBuildersPH. Provider access,
+  models, limits, and policies can change.
 - Use it only where your account, subscription, provider terms, and applicable
   policies allow.
 
@@ -315,6 +404,7 @@ OpenAI may change or disable the underlying services at any time.
 ## Documentation
 
 - [Complete GitHub README and manual fallback](https://github.com/Demonbane18/relmio#readme)
+- [Local Docker endpoints](https://github.com/Demonbane18/relmio/blob/main/docs/local-endpoints.md)
 - [Configure n8n AI and HTTP nodes](https://github.com/Demonbane18/relmio/blob/main/docs/n8n-configuration.md)
 - [Troubleshooting](https://github.com/Demonbane18/relmio/blob/main/docs/troubleshooting.md)
 - [Security and limitations](https://github.com/Demonbane18/relmio/blob/main/docs/security.md)

package/docs/architecture.md

@@ -17,6 +17,52 @@ flowchart LR
   S --> C["OpenAI service used by<br>the upstream helper"]
 ```
 
+## Local endpoint architecture
+
+The local installer is a separate path in the same browser wizard. It uses the
+local Docker Engine and never opens SSH, writes to a VPS, or changes the
+existing n8n sidecar project.
+
+```mermaid
+flowchart LR
+  B["Local browser<br>127.0.0.1"] --> W["Local Node wizard"]
+  W --> D["Local Docker Engine"]
+  D --> G["OpenAI-compatible gateway<br>127.0.0.1:12435/v1"]
+  D --> A["Codex App Server<br>127.0.0.1:14500"]
+  G -->|"Platform API key"| P["OpenAI Platform API"]
+  A -->|"Official Codex sign-in"| C["ChatGPT/Codex service"]
+```
+
+The two services are intentionally not interchangeable:
+
+| Target | Wire protocol | Upstream credential |
+|---|---|---|
+| `openai-api` | OpenAI-compatible HTTP `/v1` | OpenAI Platform API key |
+| `codex-chatgpt` | Official Codex App Server JSON-RPC | ChatGPT sign-in managed by Codex |
+
+Relmio never adapts a ChatGPT/Codex credential into the local `/v1` gateway.
+The OpenAI gateway replaces the caller's Relmio capability with the
+protected Platform key only at the upstream boundary. The Codex service keeps
+the native initialization, thread, turn, approval, and event protocol.
+
+Both projects publish exactly one literal `127.0.0.1` binding and require a
+generated bearer capability. Their managed roots are
+`~/.relmio/local/openai-api` and `~/.relmio/local/codex-chatgpt`. The Codex
+credential and workspace use private named Docker volumes; no host directory
+or Docker socket is mounted. See [Local Docker endpoints](local-endpoints.md)
+for setup and trust limitations.
+
+Before installation, Relmio resolves the selected Docker context to a local
+Unix socket and pins that exact socket on every later Docker command. Remote
+Docker contexts and Docker environment overrides are rejected. Each endpoint
+gets a random installation ID, a unique Compose project name, and matching
+ownership labels; existing resources must attest to that identity before an
+update or recovery action can run.
+
+The local endpoint installer supports macOS, Linux, and Linux under WSL2.
+Native Windows is rejected before filesystem or Docker mutation because this
+release relies on owner-only POSIX modes for managed credentials.
+
 ## Why this integration is possible
 
 The design combines four existing interfaces rather than changing n8n:
@@ -114,6 +160,9 @@ sidecar authenticates upstream with the mounted OAuth file.
 - [Docker Compose networking](https://docs.docker.com/compose/how-tos/networking/)
 - [Docker Compose `expose`](https://docs.docker.com/reference/compose-file/services/#expose)
 - [Docker port publishing](https://docs.docker.com/engine/network/port-publishing/)
+- [OpenAI API authentication](https://developers.openai.com/api/reference/overview#authentication)
+- [Codex authentication](https://learn.chatgpt.com/docs/auth)
+- [Codex App Server](https://learn.chatgpt.com/docs/app-server)
 
 ## Failure behavior
 
@@ -125,3 +174,11 @@ sidecar authenticates upstream with the mounted OAuth file.
 - A failed build or start does not trigger an n8n action.
 - An unexpected host-port mapping causes verification to fail.
 - The SSH connection closes after installation or when the wizard stops.
+- A local port collision blocks a new local install or port change.
+- An existing unmanaged or symlinked local path is never overwritten.
+- A local service fails verification unless Docker reports the exact planned
+  `127.0.0.1` publication.
+- A remote Docker context, inherited Docker selector, foreign Compose resource,
+  or mismatched managed identity blocks local mutation.
+- A Codex login failure returns a sanitized status without returning App
+  Server output or ChatGPT tokens.