# Codex Gateway

**Owner service · sanitized interface captures**

Codex Gateway is a Ruby proxy in front of the model API. It manages multiple access configurations, selectively inspects only Codex traffic, proxies HTTP, SSE and WebSocket and accounts for usage per user. Sanitized event copies go to a bounded outbox and NATS without blocking the main Codex request.

Source version: `5a8e7e332b818df4482e4554fa724f76853741d0`

Development and operation: 2026. Captures prepared on 8 September 2026.

[Project notes](https://komaroff-dev.ru/projects/codex/) · [Online documentation](https://komaroff-dev.ru/projects/codex/docs/)

[Demo](https://codex.komaroff-dev.ru/) — owner access required.

The source repository is private.

## Task

The task was to provide several Codex clients with controlled access through one gateway, expose configuration lifetime, errors and token usage, and keep monitoring from becoming a new failure point.

The owner manages access and statistics in a closed UI; Codex clients use separate proxy credentials; Synadia receives only sanitized event copies.

## Work done

- Implemented the Ruby proxy and CONNECT routing with selective TLS inspection for Codex domains.
- Added HTTP, SSE and WebSocket transports, streaming usage parsing and connection recovery.
- Connected access configurations, proxy users, limits, statistics and the admin UI.
- Added a non-blocking outbox and sanitized NATS events for Synadia Live Monitor.

## What sets the implementation apart

The Gateway combines access management, streaming transport and observability in one Ruby process while keeping monitoring off the critical path. Selective TLS inspection is limited to Codex domains and event copies are sanitized before NATS, so Synadia receives live data without making NATS a dependency of Codex traffic.

## Application-code composition

- Ruby MITM / HTTP / SSE / WebSocket: 86.1%
- Ruby event observer / outbox: 13.9%

Shares use Git blob bytes of the two tracked Ruby proxy and observer modules at the pinned revision. Base-image libraries are excluded. Files are assigned to one subsystem and rounded to 0.1%; this is code composition, not proficiency.

## Stack

| Technology | Role |
| --- | --- |
| Ruby | MITM proxy, CONNECT routing and administration server. |
| OpenSSL | Local certificates and selective inspection of allowed traffic. |
| HTTP / SSE / WebSocket | Regular and streaming Codex requests, reconnect and usage. |
| NATS / outbox | Non-blocking delivery of sanitized monitoring events. |

## Architecture and decisions

- TLS inspection is enabled only for allowed Codex hostnames; other CONNECT traffic remains a regular tunnel.
- Client responses do not wait for NATS: unavailable monitoring uses a bounded outbox while Codex keeps working.
- SSE and WebSocket are parsed incrementally with split-message, UTF-8 and reconnect handling.
- Secret headers and tokens are removed before monitoring events are created.

### Codex traffic and sanitized event flow

![Codex traffic and sanitized event flow](https://komaroff-dev.ru/evidence/codex/diagrams/flow.svg)

[Mermaid source](https://komaroff-dev.ru/evidence/codex/diagrams/flow.mmd)

### Owner interface and storage deployment

![Owner interface and storage deployment](https://komaroff-dev.ru/evidence/codex/diagrams/deployment.svg)

[Mermaid source](https://komaroff-dev.ru/evidence/codex/diagrams/deployment.mmd)

## Code map

| Feature | Screen / API | Module | Data / verification |
| --- | --- | --- | --- |
| CONNECT / TLS | Proxy CONNECT endpoint | proxy.rb: handle_connect; codex_interception_required? | OpenSSL; permitted hostnames and relay checks |
| HTTP / SSE / WebSocket | Forwarded model requests | proxy.rb: forward_request; forward_websocket_request | Response streams, usage and observer tests |
| Configurations / usage | Owner dashboard / control API | proxy.rb: handle_control_request; AssetStore | JSON files; active configuration and usage aggregates |
| Monitoring events | Bounded outbox → NATS | docker/monitor/observer.rb | Sanitized events; fragmented secrets and overflow tests |

Before changing a feature, trace its interface, API, state and storage dependencies. Check inputs, errors, retries and related workflows. Update the map and affected diagrams alongside the code, rerun the related checks and attach evidence for the source version.

## Workflows and API

1. Open the protected dashboard and inspect active configuration lifetime and refresh state.
2. Compare a proxy user’s usage with 24-hour and 7-day aggregates.
3. Inspect HTTP, SSE and WebSocket handling and Ruby proxy state.
4. Open proxy documentation and review TLS-inspection boundaries.

## Verification

- Health, HTTP and streaming transport checks preserving the client response.
- Secret-header sanitization and bounded-outbox overflow checks.
- Browser QA for dashboard, sessions, stats and mobile layout after DOM-only masking.

## Results and measurements

- The live Gateway serves Codex clients and reports aggregate usage per proxy user.
- Eight captures came from the live instance; server data was unchanged and no page errors were found.

These checks apply to the listed version. Business metrics and model quality on an independent dataset were not measured.

## Limitations

- The administration UI is protected by Basic Auth; the public case contains sanitized captures only.
- Screenshots show real aggregates, while accounts and configuration values are replaced in the DOM before capture.
- Gateway tracing is not the source of the public broadcast; live events are sent to the separate Synadia flow.

## Running and operating

Gateway runs as a separate loopback container, while Nginx publishes only the protected administration UI.

NATS downtime does not stop the main proxy flow. Disabling capture through MONITOR_ENABLED=false requires recreating the proxy and briefly reconnecting active connections.

## Screenshot index

1. [Gateway dashboard with active configuration, token lifetime and per-user aggregate usage. Visible accounts were replaced only in the DOM before capture.](https://komaroff-dev.ru/evidence/codex/full/01-dashboard.png) — 2026-09-08T06:40:00Z, source `5a8e7e332b818df4482e4554fa724f76853741d0`.

2. [Sessions separates request tracing from aggregate statistics and explicitly shows that no trace records are stored.](https://komaroff-dev.ru/evidence/codex/full/02-sessions.png) — 2026-09-08T06:40:00Z, source `5a8e7e332b818df4482e4554fa724f76853741d0`.

3. [Service statistics expose Ruby proxy state, transport counters and errors without revealing secret headers.](https://komaroff-dev.ru/evidence/codex/full/03-service-stats.png) — 2026-09-08T06:40:00Z, source `5a8e7e332b818df4482e4554fa724f76853741d0`.

4. [Built-in documentation describes selective TLS inspection and the HTTP, SSE and WebSocket paths.](https://komaroff-dev.ru/evidence/codex/full/04-proxy-docs.png) — 2026-09-08T06:40:00Z, source `5a8e7e332b818df4482e4554fa724f76853741d0`.

5. [Configuration detail shows access lifecycle and diagnostic states; account and configuration values are replaced in the screenshot.](https://komaroff-dev.ru/evidence/codex/full/05-config.png) — 2026-09-08T06:40:00Z, source `5a8e7e332b818df4482e4554fa724f76853741d0`.

6. [Proxy-user detail links requests, token usage and access state without exposing the user key.](https://komaroff-dev.ru/evidence/codex/full/06-user-usage.png) — 2026-09-08T06:40:00Z, source `5a8e7e332b818df4482e4554fa724f76853741d0`.

7. [The mobile dashboard keeps charts, configuration statuses and token composition controls in one vertical flow.](https://komaroff-dev.ru/evidence/codex/full/07-dashboard-mobile.png) — 2026-09-08T06:40:00Z, source `5a8e7e332b818df4482e4554fa724f76853741d0`.

8. [The mobile sessions view preserves navigation and an explicit empty tracing state.](https://komaroff-dev.ru/evidence/codex/full/08-sessions-mobile.png) — 2026-09-08T06:40:00Z, source `5a8e7e332b818df4482e4554fa724f76853741d0`.

Screenshots, diagrams and the original evidence package retain their source language. Captions and this document are translated into English.

[Original evidence package](https://komaroff-dev.ru/downloads/codex-materials.zip)