Context
Issue #290 exposed a concrete failure in the current proxy runtime model: enabling a second app proxy worker can fail with Address in use when workers collide on the same local listener port.
PR #305 is a useful short-term fix: it separates default preferred ports and falls back to an ephemeral port if the configured port is already occupied. That should be treated as a hotfix for the current per-app worker model, not as the final proxy architecture.
Current model
The CLI currently runs daemon-managed proxy workers per app. Each app worker owns a local listener port, and live app configs are rewritten to point at the selected worker port.
This model supports existing app-scoped state such as:
- per-app takeover enablement
- per-app current provider / failover state
- per-app runtime status and active worker reporting
- app-specific live config backup and restore
Long-term direction to evaluate
Evaluate whether the proxy should move toward a single local proxy entry point shared by Claude, Codex, Gemini, and future supported apps.
A possible target model:
- one local listener address/port for all supported apps
- internal routing by request path, protocol shape, headers, or app-specific adapter
- app-scoped provider selection, failover, and takeover state remain separate
- live configs point at the same local proxy origin when possible
- status reporting still exposes app-level active targets and request statistics
Why this needs a separate follow-up
This is not a small bugfix. It may affect daemon lifecycle, runtime session persistence, TUI status display, live config restoration, failover snapshots, Codex/Gemini/Claude protocol transformations, and managed-worker cleanup.
PR #305 can reduce immediate user-facing failures, while this tracking issue records the deeper architectural question.
Open questions
- Can Claude, Codex, and Gemini safely share one local base URL without client-side assumptions breaking?
- Is request path/protocol-shape routing sufficient to distinguish app traffic reliably?
- How should per-app takeover state map onto a single listener?
- How should daemon status represent one process serving multiple app routes?
- Can migration preserve existing live backups and preferred port settings?
Suggested validation before implementation
- Enable Claude + Codex + Gemini proxy takeover concurrently.
- Switch providers while multiple app routes are active.
- Exercise failover for one app without affecting others.
- Restart daemon and verify runtime session recovery.
- Restore live configs after shutdown or worker crash.
- Confirm TUI and CLI status still show app-scoped state accurately.
Context
Issue #290 exposed a concrete failure in the current proxy runtime model: enabling a second app proxy worker can fail with
Address in usewhen workers collide on the same local listener port.PR #305 is a useful short-term fix: it separates default preferred ports and falls back to an ephemeral port if the configured port is already occupied. That should be treated as a hotfix for the current per-app worker model, not as the final proxy architecture.
Current model
The CLI currently runs daemon-managed proxy workers per app. Each app worker owns a local listener port, and live app configs are rewritten to point at the selected worker port.
This model supports existing app-scoped state such as:
Long-term direction to evaluate
Evaluate whether the proxy should move toward a single local proxy entry point shared by Claude, Codex, Gemini, and future supported apps.
A possible target model:
Why this needs a separate follow-up
This is not a small bugfix. It may affect daemon lifecycle, runtime session persistence, TUI status display, live config restoration, failover snapshots, Codex/Gemini/Claude protocol transformations, and managed-worker cleanup.
PR #305 can reduce immediate user-facing failures, while this tracking issue records the deeper architectural question.
Open questions
Suggested validation before implementation