Desktop install, QR handoff, and first health checks.
Architecture
Architecture map for the FlyDex control plane
The FlyDex architecture is intentionally split so the remote browser never has to talk directly to the local Codex app server. That separation is what keeps the runtime local while still making it reachable for operational control.
Reference map
Public docs sections
Account auth, QR claims, local-connect tokens, and machine continuity.
Thread access, send/resume turns, and remote approvals.
Bridge lifecycle, documented endpoints, and status model.
Threat model, data boundaries, and transport safeguards.
Control plane, connector, and local Codex runtime topology.
Component map
Primary system surfaces
| Component | Responsibility |
|---|---|
| apps/web | Public landing page, auth continuity, QR handoff, machine detection, thread views, and approval UI. |
| apps/api | Cloudflare worker control plane for pairing, routing, machine registry, local-connect lifecycle, and privacy-scrubbed audit export. |
| packages/local-connector-core | Shared helper runtime for the desktop connector and localhost API. |
| Local Codex runtime | The coding agent stays on the operator's own Mac or Windows PC. |
Lifecycle
Why readiness matters more than login
A signed-in browser session is not enough to open the workspace. The machine is considered ready only once the browser handoff, connector session, and local Codex runtime all converge on codex_ready.
Desktop page open
-> localhost health probe
-> phone completes auth
-> local-connect starts
-> connector reports status
-> codex_ready
-> workspace unlocks