relmio 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ checks the registry separately after publication.
 
 ## Unreleased
 
+## [0.6.0] - 2026-08-15
+
+### Added
+
+- Add an experimental loopback-only Codex Chat Adapter for trusted local
+  backends and development servers, with bearer authentication, multi-turn
+  conversation IDs, strict resource bounds, and a small Relmio-specific
+  `POST /chat` contract.
+
+### Changed
+
+- Make Codex device sign-in target-aware so the experimental Relmio `/chat`
+  adapter and native App Server retain isolated, persistent ChatGPT credentials;
+  a Platform API key powers neither target and remains reserved for the generic
+  OpenAI-compatible `/v1` endpoint.
+
+### Security
+
+- Reject browser-origin adapter requests, keep the adapter separate from
+  Platform-key-backed generic OpenAI-compatible `/v1` semantics, explicitly deny
+  model turns access to the private Codex credential store, run chat turns
+  read-only without network access, and preserve loopback-only publication plus
+  credential rotation.
+
+## [0.5.0] - 2026-08-15
+
+### Added
+
+- Add a **Rotate client credential** action for installed local endpoints that
+  shows the replacement capability before activation and preserves the upstream
+  Platform key or Codex credential/workspace volumes.
+
+### Changed
+
+- Keep System, Light, and Dark appearance controls plus Ko-fi, GitHub stars, and
+  the current package version available throughout the local install wizard.
+
+### Fixed
+
+- Install operating-system CA certificates in the isolated Codex image so the
+  official ChatGPT device-code sign-in can establish its trusted TLS connection.
+- Wrap local safety and error notifications instead of clipping longer text.
+
+### Security
+
+- Verify the generated Codex capability with a strict authenticated WebSocket
+  upgrade before reporting installation or rotation success.
+- Serialize installation, sign-in, restart, and credential rotation across
+  Relmio processes, with attested stale-lock recovery and fail-closed rollback
+  that restores the prior verifier and re-attests endpoint readiness.
+
 ## [0.4.1] - 2026-08-14
 
 ### Changed

package/README.md

@@ -47,8 +47,9 @@ 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. 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.
+an OpenAI-compatible gateway backed by a Platform API key, the official Codex
+App Server, or a small server-side Codex chat adapter backed by ChatGPT
+sign-in.
 
 The existing n8n image, Compose file, container, and workflows stay untouched.
 
@@ -101,7 +102,8 @@ 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.
+Both the hosted site and local wizard keep Ko-fi support, GitHub stars, and the
+current Relmio version visible beside the appearance control.
 
 ## Local Docker endpoints
 
@@ -117,29 +119,51 @@ The existing VPS/n8n wizard remains available from native Windows.
 |---|---|---|---|
 | **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 |
+| **Codex Chat Adapter: development backends** | `http://127.0.0.1:14501/chat` by default | ChatGPT sign-in through Codex | Trusted local backend or development server |
+
+The Chat Adapter starts each model turn with network access disabled and an
+explicit filesystem policy that permits only Codex's minimal runtime files and
+the empty private workspace. The model-accessible sandbox denies
+`/home/node/.codex`, where the official Codex client keeps its ChatGPT session.
+The adapter bearer must stay in your server-side development environment,
+never browser code.
 
 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
+The bearer remains valid until it is rotated. After installation, use
+**Rotate client credential** on the Ready screen to replace only that local
+capability. Relmio shows the new one-time credential before activation, verifies
+the replacement endpoint, and preserves the upstream Platform API key or Codex
+credential/workspace volumes. If replacement cannot be verified, Relmio attempts
+to restore the previous verifier and re-attest service readiness. It does not
+retain the previous raw client credential to replay it during rollback. If
+rollback cannot be confirmed, it targets only the exact managed service for
+shutdown and reports whether that stopped state could be verified. 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.
+ChatGPT sign-in powers Codex, not the OpenAI Platform API. The native target
+keeps the official experimental App Server JSON-RPC protocol. The separate
+adapter offers only Relmio's `POST /chat` request and returns a conversation ID
+plus final text; it is not `/v1/chat/completions`, `/v1/responses`, or an
+OpenAI SDK replacement. A local backend can keep its Relmio bearer secret while
+a browser calls that backend. Direct browser-origin requests to both Codex
+targets are rejected.
+
+OpenAI documents the underlying App Server WebSocket transport as experimental
+and unsupported for production. The raw App Server capability is especially
+high-trust because it can operate the signed-in Codex session and files inside
+the isolated container workspace. Keep either target loopback-only, same-owner,
+and limited to local development.
+
+All three services bind exactly to `127.0.0.1`, require the generated capability,
+and mount no host directory or Docker socket. Each Codex target gets its own
+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)

package/docs/architecture.md

@@ -29,28 +29,37 @@ flowchart LR
   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"]
+  D --> H["Codex Chat Adapter<br>127.0.0.1:14501/chat"]
   G -->|"Platform API key"| P["OpenAI Platform API"]
   A -->|"Official Codex sign-in"| C["ChatGPT/Codex service"]
+  H -->|"Official App Server lifecycle"| C
 ```
 
-The two services are intentionally not interchangeable:
+The three 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 |
+| `codex-chat` | Relmio-specific HTTP `POST /chat` | 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
+protected Platform key only at the upstream boundary. The native Codex service
+keeps the initialization, thread, turn, approval, and event protocol. The
+adapter invokes that same official lifecycle behind a bounded, read-only
+conversational contract without claiming OpenAI API compatibility. Its model
+sandbox denies network access and uses a root-deny filesystem policy with only
+minimal runtime paths plus `/workspace` readable; `/home/node/.codex` is
+explicitly denied so a model turn cannot read the persisted ChatGPT session.
+
+Each project publishes exactly one literal `127.0.0.1` binding and requires 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.
+`~/.relmio/local/openai-api`, `~/.relmio/local/codex-chatgpt`, and
+`~/.relmio/local/codex-chat`. The Codex credentials and workspaces use
+target-specific 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
@@ -182,3 +191,6 @@ sidecar authenticates upstream with the mounted OAuth file.
   or mismatched managed identity blocks local mutation.
 - A Codex login failure returns a sanitized status without returning App
   Server output or ChatGPT tokens.
+- A chat adapter request with a browser Origin, invalid bearer, malformed body,
+  protocol overflow, timeout, or failed turn is rejected with a sanitized
+  response and its App Server helper is terminated.

package/docs/local-endpoints-spec.md

@@ -2,7 +2,8 @@
 
 ## Status
 
-Approved for implementation on `codex/local-openai-endpoint` on 2026-08-13.
+Originally approved on 2026-08-13 and extended for the additive
+`codex/local-codex-chat-adapter` target on 2026-08-15.
 
 This spec is product and engineering guidance based on the current official
 OpenAI documentation. It is not a legal opinion. Relmio must not claim that
@@ -13,16 +14,19 @@ OpenAI has endorsed, certified, or pre-approved the project.
 Add a local Docker installation path to the Relmio browser wizard without
 weakening the existing VPS/n8n safety boundary.
 
-Relmio offers two intentionally different local providers:
+Relmio offers three intentionally different local client contracts:
 
 1. `openai-api` is an OpenAI-compatible HTTP gateway backed by the user's
    OpenAI Platform API key.
 2. `codex-chatgpt` is the official Codex App Server protocol backed by the
    user's ChatGPT/Codex sign-in.
+3. `codex-chat` is a small Relmio-specific HTTP chat adapter backed by the
+   same official App Server lifecycle and ChatGPT/Codex sign-in.
 
 Relmio must never exchange, translate, or present a ChatGPT/Codex credential as
-a general OpenAI API bearer credential. The Codex provider must not expose an
-OpenAI-shaped `/v1` compatibility surface.
+a general OpenAI API bearer credential. Neither Codex target may expose an
+OpenAI-shaped `/v1` compatibility surface. The adapter owns only its narrow
+`POST /chat` contract.
 
 ## Official-source boundary
 
@@ -53,7 +57,7 @@ The existing VPS/n8n wizard remains a separate legacy setup path. The wizard
 landing experience adds a prominent **Local endpoints** option which opens a
 dedicated local installer.
 
-The local installer starts with two provider cards:
+The local installer starts with three provider cards:
 
 ### OpenAI API
 
@@ -81,7 +85,21 @@ The local installer starts with two provider cards:
   - An explicit statement that this is Codex JSON-RPC, not OpenAI `/v1`
   - An explicit experimental/non-production notice
 
-Both flows show a review screen and require a final confirmation before any
+### Codex Chat Adapter
+
+- Label: **Codex Chat Adapter — development backends**
+- Default HTTP port: `14501`
+- Uses the same pinned official Codex CLI and official device-code sign-in.
+- Result:
+  - Endpoint: `http://127.0.0.1:<port>`
+  - A newly generated Relmio bearer token, displayed once
+  - A device-code sign-in action
+  - An explicit server-side-only statement
+  - An explicit statement that `POST /chat` is Relmio-specific, not OpenAI
+    `/v1`
+  - An explicit experimental/non-production notice
+
+All three flows show a review screen and require a final confirmation before any
 filesystem or Docker write.
 
 This release supports macOS, Linux, and Linux under WSL2. Native Windows is
@@ -143,7 +161,9 @@ is released in a `finally` path after both success and failure.
 ### `POST /api/local/codex/login`
 
 Starts an official Codex App Server device-code login through a one-shot stdio
-App Server process attached to the same persistent Codex home volume.
+App Server process attached to the selected Codex target's persistent home
+volume. The request identifies either `codex-chatgpt` or `codex-chat`;
+every other target is rejected before process construction.
 
 Every login attempt resolves the managed Codex directory and attests its
 schema-2 marker and matching Docker resources, even in a fresh wizard process.
@@ -249,12 +269,77 @@ The host mapping is exactly `127.0.0.1:<selected-port>:4500`.
   The capability is therefore password-equivalent and limited to a trusted,
   same-owner native client.
 
+## Codex Chat Adapter contract
+
+The adapter container starts a dependency-free Node HTTP service and launches
+the pinned official `codex app-server --strict-config --stdio` process only
+for a bounded chat operation. It uses the target's private Codex home and
+workspace volumes and never exposes the App Server transport on the host.
+
+### Listener and authentication
+
+- Container listener: `0.0.0.0:14501`
+- Host publication: `127.0.0.1:<selected-port>:14501`
+- `GET /health` is the only unauthenticated, non-forwarding route.
+- Every route except `GET /health` requires exactly one
+  `Authorization: Bearer <Relmio capability>` header.
+- Only the SHA-256 verifier is persisted and comparison is constant-time.
+- Requests with an `Origin` header are rejected and no CORS permission is
+  emitted.
+
+### Request and response
+
+The accepted JSON object contains only:
+
+```json
+{
+  "input": "Required nonempty conversational input",
+  "conversationId": "Optional App Server thread ID"
+}
+```
+
+The successful response contains only:
+
+```json
+{
+  "conversationId": "The started or resumed thread ID",
+  "output": "The authoritative final agent message"
+}
+```
+
+The adapter performs `initialize`, `initialized`, `thread/start` or
+`thread/resume`, and `turn/start`. The turn is constrained to the empty
+private workspace with a read-only sandbox. Its filesystem policy denies root
+by default, permits only Codex's minimal runtime paths and `/workspace`, and
+explicitly denies `/home/node/.codex`; turn network access is disabled. The
+instruction not to inspect or modify files, run commands, call tools, or access
+external resources remains defense in depth, not the credential boundary.
+`item/completed` agent-message text is authoritative; bounded deltas are kept
+separate by `itemId`, with only the most recent item's text used as a
+compatibility fallback. Success requires `turn/completed` with
+`status: completed`.
+
+### Resource and failure bounds
+
+- Header, body, input, conversation ID, stdout, stderr, line, and output sizes
+  are bounded.
+- Concurrent chats, turn duration, child-process termination grace, and the
+  final wait for an unreaped process are bounded. The concurrency slot remains
+  occupied until the helper closes or that final bound expires.
+- Client disconnect, timeout, malformed protocol, overflow, and failed turns
+  terminate the helper.
+- HTTP errors are generic and never include App Server output, process errors,
+  ChatGPT credentials, or stderr.
+- Installation and credential rotation verify readiness/authentication without
+  starting a model turn or requiring sign-in before the device-code step.
+
 ## Local filesystem and process boundary
 
 Managed roots:
 
 - `~/.relmio/local/openai-api`
 - `~/.relmio/local/codex-chatgpt`
+- `~/.relmio/local/codex-chat`
 
 `RELMIO_HOME` may replace `~/.relmio` for testing or advanced use, but it must
 be an absolute path whose final component is `.relmio`.
@@ -282,7 +367,7 @@ Controls:
 
 ## Container hardening
 
-Both long-running endpoint services:
+All three long-running endpoint services:
 
 - run as a non-root user;
 - set `no-new-privileges`;
@@ -326,26 +411,29 @@ gateway; it is removed immediately after seeding.
 | LAN/public exposure | literal `127.0.0.1` Compose binding plus template and runtime inspection tests |
 | Local cross-site request | bearer capability, exact Origin allowlist, strict preflight, Host validation |
 | Upstream key disclosure | separate local/upstream credentials, stdin-seeded private named volume, redacted errors, no body logging |
-| ChatGPT token repurposing | official App Server only; no `/v1` adapter for Codex |
+| ChatGPT token repurposing | official App Server lifecycle only; the adapter is Relmio-specific and exposes no `/v1` route |
 | Command injection | validated scalar values, spawn argument arrays, no shell |
 | Managed-path takeover | refuse unmanaged roots and every symlinked component |
 | Streaming resource exhaustion | header/body/concurrency/time bounds and backpressure |
 | Docker privilege compromise | document Docker control as a privileged local boundary; mount no Docker socket into services |
 | Secret recovery from UI | show capabilities once; never use browser storage; rotate on reinstall |
-| Codex capability compromise | explicit credential-equivalent warning; trusted same-owner native clients only; private container volumes and no host mounts |
+| Codex capability compromise | explicit trust warning; target-specific least-privilege interfaces, private container volumes, no host mounts, and server-side-only adapter use |
+| Model-induced credential read | root-deny model filesystem profile, minimal runtime read allowlist, explicit `/home/node/.codex` deny, empty private workspace, and no turn network access |
 
 ## Acceptance criteria
 
-- The browser wizard visibly offers both local providers and the legacy VPS
+- The browser wizard visibly offers all three local contracts and the legacy VPS
   path remains separate.
-- Platform keys are accepted only by `openai-api`; ChatGPT auth is accepted only
-  by official App Server.
+- Platform keys are accepted only by `openai-api`; both Codex targets use only
+  official App Server-backed ChatGPT authentication.
 - Generated Compose files publish only literal loopback bindings.
 - Every non-health gateway operation that can reach OpenAI and every App Server
   WebSocket handshake is capability-authenticated; exact-origin CORS preflight
   is a non-forwarding metadata exception.
 - Gateway unit/integration tests cover auth, origins, Host validation,
   streaming, cancellation, upstream errors, and secret redaction.
+- Adapter tests cover auth, Origin rejection, request/protocol validation,
+  process cleanup, bounds, concurrency, final-output selection, and redaction.
 - Local installer tests prove confirmation, unmanaged-root refusal, symlink
   refusal, port collision behavior, exact Docker arguments, file modes, and
   absence of n8n commands.

package/docs/local-endpoints.md

@@ -1,18 +1,20 @@
 # Local Docker endpoints
 
 Relmio can install a provider endpoint in Docker on the same computer as your
-app. The local installer is deliberately split into two protocols with two
-different authentication methods:
+app. The local installer keeps three explicit client contracts across two
+different provider authentication methods:
 
 | Wizard option | Local interface | Upstream sign-in | Intended client |
 |---|---|---|---|
 | **OpenAI API: compatible clients** | OpenAI-compatible HTTP under `/v1` | Server-side OpenAI Platform API key only | A private local app, SDK, or same-owner development web app |
 | **Codex with ChatGPT: agent clients** | Official Codex App Server JSON-RPC over WebSocket | ChatGPT sign-in through Codex | A trusted native Codex/App Server client owned by the same person |
+| **Codex Chat Adapter: development backends** | Relmio-specific HTTP `POST /chat` | ChatGPT sign-in through Codex | A trusted local backend or development server owned by the same person |
 
 Relmio does not exchange or translate a ChatGPT OAuth/session credential into
-an OpenAI-compatible `/v1` bearer credential. The Codex option keeps Codex's
-thread, turn, approval, and streamed-event semantics instead of pretending to
-be the OpenAI API.
+an OpenAI-compatible `/v1` bearer credential. The native Codex option keeps
+Codex's thread, turn, approval, and streamed-event semantics. The adapter
+translates only a small Relmio-owned `/chat` contract into that official
+protocol; it does not imitate the OpenAI API.
 
 This is a documentation-backed engineering boundary, not legal advice or a
 guarantee that a particular account or use case is permitted. Review the
@@ -24,10 +26,11 @@ agreements and policies that apply to your account.
   this release depends on POSIX owner-only directory and file permissions for
   local credentials.
 - Docker Engine or Docker Desktop with Docker Compose v2 on the local computer
-- A free loopback port (`12435` by default for OpenAI API or `14500` for Codex)
+- A free loopback port (`12435` for OpenAI API, `14500` for native Codex,
+  or `14501` for the Codex Chat Adapter by default)
 - One of these provider credentials:
   - an OpenAI Platform API key for the OpenAI-compatible endpoint; or
-  - a ChatGPT account eligible for Codex for the App Server endpoint
+  - a ChatGPT account eligible for Codex for either Codex target
 - A trusted local app that can keep the Relmio capability secret
 
 The local path does not need a VPS or SSH access and does not modify the
@@ -45,8 +48,8 @@ project on the local computer.
 
 2. Open the one-time local wizard URL printed in the terminal and choose
    **Local endpoints**.
-3. Choose **OpenAI API: compatible clients** or **Codex with ChatGPT: agent
-   clients**.
+3. Choose **OpenAI API: compatible clients**, **Codex with ChatGPT: agent
+   clients**, or **Codex Chat Adapter: development backends**.
 4. Keep the default port or select another unused local port. For the OpenAI
    API option, add any browser origins that must be allowed and enter your
    Platform API key.
@@ -64,6 +67,7 @@ inside its managed path. Its local files live under:
 ```text
 ~/.relmio/local/openai-api
 ~/.relmio/local/codex-chatgpt
+~/.relmio/local/codex-chat
 ```
 
 Advanced or test environments can set `RELMIO_HOME` before starting the
@@ -77,19 +81,29 @@ Engine.
 
 ## Safe updates and credential rotation
 
-Rerun the browser wizard, select the same target and port, and review the plan
-again. Relmio verifies the existing marker and Docker resource ownership,
-reuses that installation's unique Compose identity, replaces only that managed
-service, and generates a new local client capability. Copy the new capability
-from the one-time result and update the client; the previous capability no
-longer authenticates.
-
-For `openai-api`, every update requires the current Platform API key again. To
-rotate both credentials, supply the replacement Platform key during the update;
-Relmio atomically reseeds its private named volume and independently rotates the
-local client capability. For `codex-chatgpt`, an update retains the private
-Codex home and workspace volumes unless you explicitly delete them, but still
-rotates the local capability.
+To replace only the credential used by your local client, select **Rotate client
+credential** on the installed endpoint's Ready screen. Relmio first stages and
+shows the new one-time capability while the previous capability remains active.
+It then updates and validates the managed Compose configuration, recreates only
+the attested service, and verifies the new bearer against `/v1/models`, the
+authenticated Codex WebSocket handshake, or the adapter's authenticated probe
+before reporting success.
+
+This client-only rotation preserves the upstream Platform API key in its private
+named volume and preserves the Codex home and workspace volumes. If activation
+or verification fails, Relmio restores the previous verifier and re-attests its
+health and loopback publication. Relmio does not retain the previous raw client
+credential, so rollback does not replay an authenticated request with it. If
+that rollback cannot be confirmed, Relmio attempts to stop only the exact
+managed service and reports whether the stopped state could be verified.
+
+Rerun the browser wizard with the same target and port when you need a complete
+managed update. Relmio verifies the marker and Docker resource ownership and
+reuses the installation's unique Compose identity. For `openai-api`, provide the
+current or replacement Platform API key during that full update; Relmio reseeds
+its private named volume independently from the local client capability. A full
+`codex-chatgpt` or `codex-chat` update retains the private Codex home and
+workspace volumes unless you explicitly delete them.
 
 Do not hand-edit the marker, Compose file, credential volume, or verifier. If
 the marker or resource labels do not attest as one Relmio installation, the
@@ -196,9 +210,61 @@ workspace and credential volume. The service receives no host directory,
 Docker socket, SSH key, browser profile, or host home-directory mount. This
 reduces host exposure; it does not make an untrusted App Server client safe.
 
+## Codex Chat Adapter: development backends
+
+The adapter result screen provides:
+
+```text
+Endpoint: http://127.0.0.1:14501
+Authorization: Bearer <the Relmio capability shown once by the wizard>
+Protocol: Relmio Codex Chat HTTP
+```
+
+After completing the same official Codex device-code sign-in, a local backend
+can start a conversation with:
+
+```bash
+export RELMIO_CODEX_CHAT_KEY="<capability shown once by the wizard>"
+curl http://127.0.0.1:14501/chat \
+  -H "Authorization: Bearer $RELMIO_CODEX_CHAT_KEY" \
+  -H "Content-Type: application/json" \
+  --data '{"input":"Reply with a short hello."}'
+```
+
+The response contains only the App Server thread ID and final conversational
+text:
+
+```json
+{
+  "conversationId": "thread-id-from-the-first-response",
+  "output": "Hello!"
+}
+```
+
+Send that `conversationId` with the next `input` to continue the same
+conversation. The adapter initializes the official App Server, starts or
+resumes the thread, runs a read-only conversational turn, and returns the
+authoritative final agent message. The model sandbox has no network access and
+uses a root-deny filesystem policy that reads only Codex's minimal runtime
+paths and the empty private workspace. It explicitly denies
+`/home/node/.codex`, the private volume containing the ChatGPT session.
+
+This route is deliberately not `/v1/chat/completions` or `/v1/responses`.
+OpenAI SDKs and tools that require those schemas still need the Platform-backed
+OpenAI API target. The adapter rejects every request carrying an `Origin`
+header and sends no CORS permission, so browser JavaScript must not call it
+directly. Keep the bearer in a trusted local backend or development server and
+let the browser call that server's own session-aware route.
+
+The adapter is experimental because it depends on the experimental App Server
+interface. It is loopback-only, single-owner development tooling, not a hosted,
+LAN, multi-user, or production service. It enforces bounded request bodies,
+output, concurrency, process lifetime, and sanitized failures, but those
+controls do not create a general-purpose API entitlement.
+
 ## Network and container boundary
 
-Both local Compose projects publish exactly one host mapping:
+Every local Compose project publishes exactly one host mapping:
 
 ```text
 127.0.0.1:<selected-port>:<container-port>
@@ -207,12 +273,13 @@ Both local Compose projects publish exactly one host mapping:
 They are not available through the computer's LAN address. Each long-running
 service runs as a non-root user, drops Linux capabilities, sets
 `no-new-privileges`, uses a read-only root filesystem, and has bounded
-temporary storage and resource limits. Neither service mounts the Docker
+temporary storage and resource limits. None of the services mounts the Docker
 socket or a general host directory. The one-shot OpenAI seed helper has no
 network, port, or logs and retains only `CHOWN` while running as root long
 enough to atomically set ownership on the volume entry.
 The OpenAI gateway receives only its private API-key named volume, mounted
-read-only; Codex receives no host path and uses separate private named volumes.
+read-only; both Codex targets receive no host path and use target-specific
+private named volumes.
 
 The loopback binding and capability are complementary controls. Other
 processes running as the same local user may still be able to reach a loopback
@@ -235,7 +302,8 @@ literal values only after confirming all of these conditions:
 In every example, manually replace each angle-bracket placeholder with the
 already-validated literal. Do not use `eval`, source the JSON, or construct a
 Docker command from unvalidated marker text. The only valid service name is
-`gateway` for `openai-api` or `codex` for `codex-chatgpt`.
+`gateway` for `openai-api`, `codex` for `codex-chatgpt`, or `codex-chat`
+for `codex-chat`.
 
 ### Recover from a failed install
 
@@ -276,7 +344,7 @@ service:
 docker --host <dockerHost> compose \
   --project-name <projectName> \
   --file <absolute-managed-compose> \
-  rm --stop --force <gateway-or-codex>
+  rm --stop --force <gateway-or-codex-or-codex-chat>
 ```
 
 This recovery command does not target other services, remove the project
@@ -335,7 +403,8 @@ docker --host <dockerHost> compose \
 `--volumes` irreversibly deletes the managed Codex home and workspace volumes,
 including the container's ChatGPT credentials. After Docker confirms the
 matching resources are gone, you may remove only the exact
-`~/.relmio/local/codex-chatgpt` managed directory through your file manager.
+`~/.relmio/local/codex-chatgpt` or `~/.relmio/local/codex-chat` managed
+directory for the target you verified through your file manager.
 
 ## Troubleshooting
 
@@ -349,8 +418,9 @@ matching resources are gone, you may remove only the exact
 - **Browser request rejected:** enter the exact page origin, including scheme
   and port, then update the managed endpoint. Wildcards are intentionally not
   supported.
-- **Browser cannot connect to Codex:** this is expected. App Server's raw
-  WebSocket is for trusted native clients, not browser-origin connections.
+- **Browser cannot connect to Codex:** this is expected. Both Codex targets
+  reject browser-origin requests. Use the raw App Server from a trusted native
+  client or keep the Chat Adapter bearer in a local backend.
 - **Codex reports signed out:** repeat the device-code sign-in in the local
   wizard. Never copy a Codex credential file between users.
 - **Native Windows:** this local Docker feature is unsupported. Run Relmio in a
@@ -364,6 +434,7 @@ credentials and Codex/ChatGPT authentication:
 
 - [OpenAI API authentication](https://developers.openai.com/api/reference/overview#authentication)
 - [Codex authentication](https://learn.chatgpt.com/docs/auth)
+- [Codex permission profiles](https://learn.chatgpt.com/docs/permissions)
 - [Codex App Server protocol and WebSocket limitations](https://learn.chatgpt.com/docs/app-server)
 - [Codex for Open Source program terms](https://learn.chatgpt.com/docs/codex-for-oss-terms)