UX: guide local dashboard pairing with hub identity and an origin-specific next action #4208

Area

Dashboard

What are you trying to accomplish?

After connecting a Windows machine to a hub, open its local dashboard and inspect this machine's usage or shared settings without having to reconstruct the authentication procedure from source code.

What prevents this today?

The CLI connection can succeed while the local browser still needs a separate hub session. In the observed relay-mode UI, the pairing form contains a one-time code input and a technical sentence about a fixed relay destination, but does not identify where to obtain the code or provide an origin-specific command.

The direct-mode help says to paste a code created on the hub; relay mode replaces that help with a relay implementation detail. A user can reasonably try the data-plane key or administrator token because the relationship between those credentials and a browser pairing code is not explained at this decision point.

This is distinct from #4055, which asks for persistent login/session lifetime. No authentication lifetime change is requested here.

What should OpenCodex do?

Make the first meaningful action discoverable:

• Name the already-configured hub and state that the model/client connection is established while this browser still needs authorization.
• Provide one primary action, such as “Get pairing instructions,” with a safe copyable command generated for the exact current browser origin. State clearly that it runs on the hub.
• Explain that the one-time browser code is different from the model API credential and administrator token.
• Keep the fixed-relay implementation explanation under optional connection details instead of making it the only help.
• For expired/refused codes, offer a clear way to obtain a new code and retry; do not persist the secret or relax origin binding.
• After success, reveal the existing usage view with its source and “This machine / Entire hub” scope control.

Example usage or interface

Suggested copy, not a request for these exact words:

This computer is connected to Hub A.
Authorize this browser to view hub data.

[Get pairing instructions]

Run on Hub A:
ocx gui pair --origin http://127.0.0.1:10100

Paste the returned one-time code here.

The origin must come from the active page, not a hardcoded localhost spelling. If the hub cannot be administered by this user, show the request-to-operator path instead of implying they have permission.

Alternatives or workarounds

SSH to the hub and look up ocx gui --help; separately open the remote administrator console. Both work for experts but require knowledge the pairing form could supply.

Additional context

Observed on client 2.50.0 with hub dev 2.51.0. Source: gui/src/connect-pairing.ts:33, especially the mutually exclusive explanatory text at line 35. Existing machine-scoped usage controls are at gui/src/pages/Usage.tsx:968; this proposal is about reaching them, not rebuilding their aggregation.

Design rationale: reduce decisions and repeated lookup work; expose the next safe action; retain authentication boundaries; use progressive disclosure for transport details. Acceptance should cover first visit, already paired, expired/refused code, hub unreachable, and keyboard-only completion.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.