Using Your ChatGPT / Codex Subscription as the Model

Instead of an API key, Codumentor can run on your existing **ChatGPT or Codex
subscription** (Plus, Pro, Business, Edu, Enterprise) — the same login the
Codex CLI uses. This page is for people who use it: what it is, how it behaves,
and the limits you should know about before you rely on it.

Experimental. This is an opt-in, bring-your-own-subscription route. In a
personal (community) install it is ready to use: open Settings → Models
and choose Sign in with ChatGPT. In a shared installation, your
administrator must enable the relevant extensions for it to appear.

What it is

A normal Codumentor deployment pays for the model with an API key. With this
route, the model is answered by the backend behind your ChatGPT/Codex
subscription, using the token from a subscription you connected. You are using
your own account, so the usage counts against your subscription.

Two ways the credential can come in:

• Connect your subscription (per user) — you sign in with your ChatGPT/Codex account from Settings → Extensions, and Codumentor stores and refreshes the token for you. Each person connects their own account.
• Operator import (single user) — an operator signs in with the Codex CLI (codex login) once, and Codumentor imports ~/.codex/auth.json and owns the credential from then on. Cheapest for a personal, single-user setup.

Either way, from your point of view the difference is only where the login came
from: the assistant, the tools, and the streaming all behave as usual.

What it is not

This route is chat only. It does not provide:

• Embeddings — vector search and memory indexing keep using their own (API-key or local) embedding model.
• Text-to-speech / read-aloud — the audio route keeps its own API-key or local config.
• Realtime voice — not offered on this route at all.

If you use any of those, they are unaffected and keep working as before.

Limits you should know about

These are the important caveats. Read them once; they explain most of the
behaviour you will see.

It can break without notice

The subscription model talks to a private, internal OpenAI endpoint that is
not a documented public API. OpenAI has already changed this kind of endpoint
without telling third parties, and a change can take the route down with no
advance warning. Treat it as best-effort: if it suddenly stops working, that is
the most likely cause, and there is nothing to configure on your side.

Your usage caps are shared with your own ChatGPT/Codex use

Your subscription has a rolling 5-hour usage window and a weekly cap, and
they are shared with everything else that uses the same account — the ChatGPT
app, the Codex CLI, cloud tasks, and Codumentor. So a heavy session in Codumentor
can eat into the allowance you use in the app, and vice versa.

When you hit a limit, the backend returns a rate-limit (429). Codumentor will:

• Ride out a short throttle — when the backend only asks you to slow down for a few seconds, Codumentor waits and retries the same model; you just see a short pause.
• Rotate to a fallback profile on a cap — if your administrator configured a fallback model profile (often a local model, which does not count against your subscription), Codumentor pauses this subscription profile until the reset and switches to the fallback so the turn keeps going. When the reset passes, the subscription profile comes back.
• Tell you when the limit resets — without a fallback, the error names the advertised reset time (for example "usage resets in about 40 minutes") and says that no fallback is configured, rather than failing opaquely.

A reply that had already started streaming when the limit hit ends with the
error; your next message goes to the fallback.

The model list is yours to name, and it can change

The models available on a subscription are gated by your account and plan,
and OpenAI deprecates and retires models on its own schedule. There is no
guaranteed public list, so:

• Once you connect your account, its models appear in the model picker under Yours (as ChatGPT), read from the plan's own listing — the one the Codex app reads. The newest model of each line (Sol, Luna…) is shown; older ones are listed in Settings but hidden until you tick them. Until the listing has been read, a built-in list stands in.
• Connected two accounts? Each is its own connection — ChatGPT and ChatGPT 2 — with its own plan's models, and a conversation stays on the account you picked. If you disconnect the account a conversation uses, its next turn moves to your organization's default model and says so in the transcript.
• A model profile an admin writes by hand names its slug (for example model: gpt-5.5). If a model is retired or your account loses access, requests for it fail with a "model not found" error — you (or your admin) update the slug.
• An operator can run codumentor codex models to print the models the account can currently call. The listing endpoint is private and not guaranteed to answer, like the rest of this route.

Smaller context than the API-key route

On subscription routes the usable input context is smaller than on the same
model via an API key (roughly a few hundred thousand tokens rather than the
full window). Very long contexts may compact sooner than you would expect from
the model's headline size.

One account is one person's subscription

The subscription belongs to one human. Sharing one ChatGPT/Codex login across
multiple end-users is not what this is for and is likely to cross even OpenAI's
permissive line. Each person should use their own account (the per-user connect
flow exists for exactly this).

The terms are informal, not contractual

OpenAI is publicly permissive about using your Codex/ChatGPT subscription in
third-party tools, and has said so informally. But there is **no written
policy** guaranteeing it for a commercial app like this — the endorsement rests
on a public statement, not a contract, and OpenAI does actively gate access by
client. A comparable pattern at another provider was banned and later
reinstated behind metered credits. Net: it is tolerated today and labelled
experimental, but it is not something you can hold anyone to in writing.

Setting it up

You normally do not set this up yourself — your administrator enables the
extensions and defines the model profile. What you do is:

1. Connect your ChatGPT/Codex subscription (Settings → Extensions), if your admin uses the per-user flow.
2. Pick the subscription model where your admin exposed it (a thinking-mode / model-profile assignment, or the default).
3. Use it as you would any model.

If you are the operator doing the single-user import, the commands are
codumentor codex import (one-time) and codumentor codex status (health).

For the full technical design, the wire constraints, and the reasoning behind
each limitation, see
codex-subscription-backend.md.