Skip to Content

Multiplexing

A multiplexed relay has several subscriptions from one provider realm. Each request still belongs to one link/project/product, and one subscription serves an active upstream attempt.

Order and primary

In a relay project’s Subscriptions tab, add or remove members and move them up or down. The first member is primary. It supplies essential native-client identity and metadata. If it signs out, the whole link appears signed out even when another member could generate a response. Reconnect it or deliberately promote a signed-in replacement.

The primary is not a permanent pin for generation. Selected account order, chat affinity, model compatibility, quotas and credit permissions determine which account serves a turn. Changing the primary preserves the relay ID and URL.

The selected default uses a separate priority order for each link. Two links using the same underlying subscription still share its provider quota and account concurrency capacity; a second link does not create another capacity allocation. Alternative shared-order policy exists in server configuration, not as a promise of an app control.

How a turn selects an account

  1. Prefer the chat’s current member while it remains eligible.
  2. Otherwise inspect members in priority order for compatible models/features and included allowance.
  3. Reserve unverifiable quotas until known eligible included allowances have been considered.
  4. Use permitted paid credits according to each membership’s timing and the selected funding policy.

An active stream stays on the account that started it. If an earlier account regains quota while a chat is using a later member, the next turn retains its current eligible member under the selected default. It does not automatically move back just because the earlier account recovered.

The model catalog is a union, not an intersection. A model appears when at least one observed member can serve it. That model may have no compatible fallback. Catalog reads report complete or partial coverage; unavailable primary catalog data prevents a successful complete catalog read. Do not interpret a partial list as proof that omitted models are unavailable everywhere.

Fallback and compatibility

The selected policy permits at most three account/fallback attempts, including the first, after qualifying pre-generation refusals. Grok/Claude also have a separate authentication-recovery budget: by default, one additional send using a changed credential for the same identity after a definitive pre-generation HTTP 401. That recovery send is recorded as an upstream attempt but does not consume another account/fallback slot. The three-attempt setting is therefore not a universal cap on actual network sends. The current Codex dispatcher does not implement this same-identity 401 recovery path.

Neither path blindly replays a network timeout, an uncertain accepted request, or a stream already delivered to the client.

A model or tool-setting mismatch stops the turn when there is no compatible member. The default does not silently change the requested feature. A server-configurable compatible-downgrade alternative can adapt supported controls, while preserving opaque history; it is not an exposed setting in the membership editor. See provider compatibility.

The gateway applies the link’s usage/rate admission once per logical request, records the separate upstream attempts, and attributes serving usage to the account that actually ran the request. A fallback does not create a second allowance reservation for the same logical request.

Update membership

First configure an admin API key with workspace subscription-sign-ins:read and subscription-sign-ins:write permissions. This example explicitly targets production. Read the latest membership before replacing its ordered list:

import { createAdminClient, readAdminApiKeyFromEnv } from '@preternatural-js/admin-sdk' const apiKey = readAdminApiKeyFromEnv() if (!apiKey) throw new Error('Set PRETERNATURAL_MODEM_ADMIN_API_KEY') const admin = createAdminClient({ environment: 'production', apiKey }) const relayId = '<relay-id>' const current = await admin.subscriptionRelays.getMembership(relayId) const updated = await admin.subscriptionRelays.updateMembership(relayId, { expectedRevision: current.revision, signInIds: ['<new-primary-id>', '<second-id>'], }) console.log(updated.primarySignInId, updated.revision)

expectedRevision rejects a stale edit rather than overwriting someone else’s order. On a conflict, read again and review the new membership before resubmitting. Include every member you want to retain; this operation replaces the ordered list. Members cannot mix realms or duplicate the same underlying provider account.

The CLI reads the revision and submits the replacement for you:

modem-cli subscription-relays members --relay-id '<relay-id>' modem-cli subscription-relays set-members \ --relay-id '<relay-id>' \ --sign-in-id '<new-primary-id>' '<second-id>'

A link appears in the Credentials details of every participating subscription, not only its primary. Removing a subscription from one group does not remove its other relay memberships.

API reference

Last updated on