About the project
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.
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.
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
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.
- 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.
Screenshots, diagrams and source evidence retain their original language; captions and descriptions are translated.
Architecture and diagrams
- 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.
Code map: files and dependencies
This map is tied to version 5a8e7e332b81. The table lists the screen or API, related module and data.
| 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 |
Using the code map
- Before making a change, find the feature and trace its links to the API, state and storage.
- Check inputs, errors, repeated events and dependent workflows.
- After making a change, update the map and affected diagrams alongside the code.
- Run the related checks and link the new evidence to the source version.
Workflows and API
- Open the protected dashboard and inspect active configuration lifetime and refresh state.
- Compare a proxy user’s usage with 24-hour and 7-day aggregates.
- Inspect HTTP, SSE and WebSocket handling and Ruby proxy state.
- Open proxy documentation and review TLS-inspection boundaries.
Verification of the published version
- 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.
These checks apply to the listed version. Business metrics and model quality on an independent dataset were not measured.
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.
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.
Stack
| 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. |
Materials and source code
Development and operation: 2026. Captures prepared on 8 September 2026.
The evidence archive retains its original language.