Feature: add Nous Portal (Nous Research) as a first-class provider — free + paid tiers, OAuth/bearer

[Cheurteenyt]

Area

Provider adapters (new provider registration in src/providers/registry.ts), Authentication and account pool (OAuth/bearer token minting), Catalog / models (free + paid tiers).

What are you trying to accomplish?

Use Nous Portal (Nous Research's unified subscription gateway, the same backend Hermes Agent uses) as a provider inside OpenCodex — so Codex / Claude Code / Claude Desktop / Grok Build can route to its 300+ frontier and free models through the proxy, the same way OpenCodex already supports OpenRouter, OpenCode Zen/Go, xAI OAuth, etc.

Nous Portal exposes both a paid tier (billed against the subscription) and a set of free models (the :free slugs such as tencent/hy3:free, poolside/laguna-xs-2.1:free, inclusionai/ling-3.0-flash:free, stepfun/step-3.7-flash:free, nvidia/nemotron-3-super-120b-a12b:free, etc.). Adding it to OpenCodex would give a second free-tier surface alongside OpenCode Zen (useful for the multi-model free review swarms).

What prevents this today?

OpenCodex has no nous / nous-portal provider in src/providers/registry.ts — verified on both the published 2.10.2 bundle and the current dev branch (only qwen-portal, azure ... portal, google-antigravity, xai, command-code, cursor OAuth providers exist). So there is no provider entry, no baseUrl, no OAuth/bearer wiring, and no model catalog for Nous Portal.

What should OpenCodex do?

Register a nous (or nous-portal) provider that:

• uses adapter: "openai-chat" (the upstream is OpenAI-compatible chat completions at https://inference-api.nousresearch.com/v1),
• authenticates with a bearer token minted from the Portal OAuth refresh token (Hermes stores the refresh token at ~/.hermes/auth.json and mints a short-lived JWT per request; OpenCodex should support either (a) pasting a Portal API/OAuth token, or (b) an ocx login nous PKCE flow that captures the refresh token and mints per-request JWTs the way the Hermes client does),
• sets liveModels: true against https://inference-api.nousresearch.com/v1/models so the catalog (free + paid) is discovered live,
• marks :free models appropriately so the dashboard can surface the free tier distinctly from paid.

Concrete registry shape (mirrors the existing OAuth providers like xai/command-code):

{
  id: "nous-portal",
  label: "Nous Portal",
  adapter: "openai-chat",
  baseUrl: "https://inference-api.nousresearch.com/v1",
  authKind: "oauth",          // or "key" if a Portal API key/token is supplied
  oauthId: "nous",
  liveModels: true,
  defaultModel: "tencent/hy3:free",
  dashboardUrl: "https://portal.nousresearch.com/manage-subscription",
  note: "Nous Research subscription gateway. Mix of paid (billed to subscription) and :free models. Per-request JWT minted from the Portal refresh token, like the Hermes client.",
}

Example usage or interface

# desired flow
ocx login nous            # PKCE browser login -> capture Portal refresh token
ocx provider add nous-portal
codex -m "nous-portal/tencent/hy3:free" "review this diff"

Or, with a token already available:

ocx provider add nous-portal --token "$NOUS_PORTAL_TOKEN"

Dashboard: a new "Nous Portal" card under Providers → Add provider → (Paid or Accounts tab), showing live model count and a free/paid split like the OpenCode Zen card does.

Alternatives or workarounds

• Manual custom OpenAI-compatible endpoint: a user can already add a custom openai-chat provider pointing at https://inference-api.nousresearch.com/v1 with a pasted bearer token — but (a) the token is long-lived (no per-request JWT refresh), (b) there is no live free/paid catalog split, (c) there is no ocx login nous OAuth flow, and (d) it is not a first-class, documented provider. A native entry removes all four gaps.
• Route through Hermes Agent instead of OpenCodex — works, but defeats the purpose of using OpenCodex as the universal proxy for Codex/Claude Code.

Additional context

• Upstream (Hermes docs): https://hermes-agent.nousresearch.com/docs/integrations/nous-portal — confirms base_url: https://inference-api.nousresearch.com/v1, OAuth (hermes auth add nous --type oauth), per-request JWT minting from ~/.hermes/auth.json, and the free+paid model mix.
• Endpoint confirmed from the Hermes config snippet in the same docs: base_url: https://inference-api.nousresearch.com/v1.
• Related to the free-tier orchestration work in opencode-zen rate limit (~15-20 RPM) is silent: no header, no doc, no client warning #1145 / [Feature]: provider/key cooldown recovery notifications #1146 (silent Zen 429 + quota watchdog): a second free-tier surface (Nous :free) helps dilute rate-limit pressure across providers.

Checks

• I searched existing issues and documentation. (No nous provider exists in registry.ts on 2.10.2 or dev; no prior Nous Portal request found.)
• This request describes a concrete OpenCodex workflow (register Nous Portal as a first-class provider with OAuth/bearer auth + live free/paid catalog) rather than merely naming a desired technology.
• I removed secrets and personal data. (No tokens pasted; only public doc URLs and the public base URL.)

[github-actions]

_{Automated translation bookkeeping — detected language: unknown.}

[Ingwannu]

The provider gap is real, and PR #1397 is the current implementation candidate. It should remain open rather than merge on the proposed registry shape alone because this is a new OAuth credential destination and account-scoped live catalog.

Before it can become a canonical preset, the PR needs:

• primary-source documentation for the authorization, token/JWT minting, refresh, revocation, and authenticated /v1/models contracts;
• a legitimate OpenCodex client-registration story rather than copying Hermes credentials or silently reading ~/.hermes/auth.json;
• Nous Research terms/legal-entity evidence and confirmation that this third-party client/routing use is permitted;
• a named maintenance owner and a dated real-account test covering login, refresh, expiry, logout/revocation, paid and free catalog rows, and an actual chat request;
• security review showing refresh/access tokens never enter config DTOs, logs, model metadata, or arbitrary destinations, with fail-closed issuer/audience/state/PKCE checks;
• evidence for the meaning and stability of :free rather than inferring billing policy from a slug.

The existing custom openai-chat provider remains the safe manual path for a user-supplied token while that evidence is incomplete. Keeping this issue linked to #1397 and open.

[Wibias]

Fixed by #1397