Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
How to: use a ChatGPT (Codex) or Grok subscription instead of an API key
evenfire has two LLM providers that sign in with a subscription account rather than an API key:
| Provider id | Control UI label | Sign-in |
|---|---|---|
codex-subscription |
"ChatGPT Subscription" | ChatGPT account (Codex) |
grok-subscription |
"xAI Grok Subscription" | xAI account (SuperGrok) |
An admin signs in once from Control UI. Agents (Hosts) and workflow recipes
then pick that sign-in, and the account's subscription entitlement pays for the
calls instead of metered API billing. Both providers are off in
deploy/base and switched on in the minikube overlay.
This page covers the operator workflow. For the wire format, limits and error taxonomy, see the Codex transport contract and the Grok transport contract.
How it works
- control-api holds the credential. The OAuth tokens are stored
encrypted in control-api's database. There is no Kubernetes Secret and no
secretRefslot for these providers. - A Host or recipe names a connection. Each sign-in is a named
connection (also called a grant). A Host picks one with
spec.model.connectionRef. - Traffic goes through a broker in
control-plane. For every model call,mcp-hostasks control-api to authorize the attempt and gets a single-use ticket. It then streams tocodex-llm-proxyorgrok-llm-proxy, which redeems the ticket, holds the access token only for that operation, and calls the vendor's subscription endpoint. The model stream never passes through control-api. - Models come from the account. Each connection has its own model catalog, read from the vendor at sign-in. There is no built-in default model, and nothing falls back to an API key.
Enable on your cluster
Every switch below defaults to off. Set them in this order: proxies and control-api first, then the Host and recipe switches.
| Key | Where it lives | Codex | Grok |
|---|---|---|---|
CONTROL_API_CODEX_SUBSCRIPTION_ENABLED |
ConfigMap control-api-config (ns control-plane) |
"true" |
— |
CONTROL_API_GROK_SUBSCRIPTION_ENABLED |
ConfigMap control-api-config (ns control-plane) |
— | "true" |
CODEX_LLM_PROXY_EXECUTION_ENABLED |
ConfigMap codex-llm-proxy-config (ns control-plane) |
"true" |
— |
GROK_LLM_PROXY_EXECUTION_ENABLED |
ConfigMap grok-llm-proxy-config (ns control-plane) |
— | "true" |
MCP_HOST_CODEX_SUBSCRIPTION_ENABLED |
ConfigMap mcp-host-config (ns mcp-host) |
"true" |
— |
WRC_GROK_SUBSCRIPTION_ENABLED |
env on the workflow-recipes Deployment (not a ConfigMap key) |
— | "true" for Grok recipes |
MCP_HOST_GROK_SUBSCRIPTION_ENABLED |
Do not set. HCC injects it per Host | — | automatic |
Notes:
- The control-api, proxy and mcp-host flags accept only the exact string
true;WRC_GROK_SUBSCRIPTION_ENABLEDalso accepts1and any case oftrue. Any other value keeps the feature off. deploy/basedoes not ship anmcp-host-configConfigMap. The Host controller (HCC) loads it into every Host'smcp-hostcontainer withenvFrom, so your overlay must provide it. The minikube overlay does (deploy/overlays/minikube/configmaps/mcp-host-config.yaml).MCP_HOST_GROK_SUBSCRIPTION_ENABLEDis added by HCC only to Hosts that are actually configured for Grok, once control-api has Grok on. Do not put it inmcp-host-config.- Each proxy needs its inter-service token in
codex-llm-proxy-secretsorgrok-llm-proxy-secrets.deploy/scripts/apply-inter-service-tokens.shcreates both. - Optional:
SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLEDincontrol-api-configturns on periodic catalog refresh (see Models and catalog sync). - The minikube overlay sets every row except
MCP_HOST_GROK_SUBSCRIPTION_ENABLED(which HCC injects) underdeploy/overlays/minikube/(configmaps/*andpatches/workflow-recipes-grok.yaml).
Restart the affected Deployments after you change a ConfigMap. For upgrade order on a live cluster, see the Grok contract's Rollout order.
To check what control-api thinks is on, call
GET /api/v1/admin/llm/providers/capabilities. It returns
{ "providers": { "codex-subscription": { "enabled": … }, "grok-subscription": { "enabled": … } } }.
Connect a subscription
- In Control UI, open Secrets → LLM Subscriptions
(
/secrets/llm/subscriptions). - Create a subscription. Pick the Provider (ChatGPT or Grok; only enabled providers are offered) and give it a Name of up to 64 characters. Agents see this name when they pick a subscription.
- Click Sign in with ChatGPT or Sign in with Grok. Control UI opens the vendor's verification page in a new tab and shows a one-time code. Sign in there with the subscription account and enter the code.
- When the sign-in completes, control-api reads the account's model catalog. You see "Connected — catalog synced".
- Under Enabled models, turn models on or off. Under Primary model, choose the default model. It must be one of the enabled models.
For Grok, the sign-in panel shows a notice about how evenfire authenticates to xAI. Read it before you connect.
Device code vs browser sign-in
Control UI always uses the device-code flow for both providers. It works with the public CLI client ids that control-api ships as defaults.
control-api also has a browser OAuth flow for Codex only
(POST /api/v1/admin/llm/providers/codex-subscription/connections/:key/browser/start).
Control UI does not call it. It is refused with browser_oauth_unregistered
unless CONTROL_API_CODEX_OAUTH_CLIENT_ID is set to an OpenAI client that you
registered for this callback URL:
<control-ui origin>/control-api/api/v1/auth/codex-subscription/callback
The origin comes from CONTROL_API_CONTROL_UI_BASE_URL. Grok has no browser
flow.
Multiple named connections
You can create as many connections as you need, for example one per team account. Each one has its own tokens, catalog and enabled models.
- Keys are generated as
codex-<hex>orgrok-<hex>. Through the API you can supply your own key instead: lowercase letters, digits and-, up to 63 characters. - One vendor account can back only one live connection per provider. A second
sign-in with the same account fails with
fingerprint_in_use. unassignedis reserved for both providers.
The deployment-default connection
deployment-default is a reserved Codex key from the original single-grant
design. The un-keyed Codex admin routes (for example
GET …/codex-subscription/connection) act on it. If it exists, a Host uses it
only when its connectionRef names it explicitly. An empty connectionRef is
never treated as deployment-default.
Grok does not accept deployment-default at all. Every Grok connection uses
a named key.
Assign a subscription to an agent
In Control UI
- Open the agent, then the Models & creds tab (
/agents/<name>/model). - Edit the model configuration and choose provider ChatGPT Subscription or xAI Grok Subscription. The new-agent wizard offers the same options.
- In Credential, choose one of the subscriptions created under Secrets. Agents only choose a subscription. Creating one happens under Secrets.
- Pick a model from that connection's enabled models and save.
Saving without a subscription fails with "Choose a ChatGPT subscription before saving." (or the Grok version).
In the Host CRD
apiVersion: clerum.io/v1alpha1
kind: Host
metadata:
name: chatllm
namespace: mcp-host
spec:
host: chatLLM
contextRef: context1
model:
provider: codex-subscription # or grok-subscription
name: <a model enabled on this connection>
connectionRef: codex-0123456789abcdef
The CRD enforces these rules:
spec.secretRefmay be omitted only when the primary and everyllmPolicy.fallbacks[]entry use the same subscription provider. With an API-key fallback you still needsecretRef.credentialSlotis not allowed on a subscription fallback.- A Host may use at most one subscription provider across
model,llmPolicy.fallbacksandallowedModels. You cannot mix Codex and Grok.
See Host CRD for the full schema.
What "unassigned" means
A subscription Host with no connectionRef is unassigned. It is never
given the execute permission, so it makes no model calls. It does not fall
back to deployment-default or to an API key. Model calls fail with
unassigned_connection ("Host has no coding-plan subscription assigned").
Admin API
The admin API can also list Hosts and assign them without the agent page.
Every route is under /api/v1/admin/llm/providers/<provider-id>/:
| Route | Purpose |
|---|---|
GET connections |
Connections with their assigned Hosts, plus assignableHosts |
GET assignable-hosts |
Every Host with its provider, model and current connectionRef |
POST connections/:key/hosts/:hostRef/bind |
Point a Host at this connection and seed a model |
POST connections/:key/hosts/:hostRef/unbind |
Set the Host back to unassigned |
Models and catalog sync
A connection's catalog is read at sign-in and is not refreshed on its own. A model the vendor publishes later does not appear until you sync:
- In Control UI, open the subscription and click Sync catalog.
- Or call
POST /api/v1/admin/llm/providers/<provider-id>/connections/:key/catalog/sync. GET …/connections/:key/modelslists the catalog, andPATCH …/connections/:key/models/:modelwith{ "enabled": true|false }turns one model on or off.
For periodic sync, set SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED: "true" in
control-api-config. The interval is SUBSCRIPTION_CATALOG_SYNC_INTERVAL_MS:
6 hours by default, and control-api refuses to start below 15 minutes. It is
off by default on purpose. Each tick calls the vendor once per connection,
and a Grok token refresh during a tick rotates the refresh token.
Use a subscription in a workflow recipe
Both providers are valid for spec.agent.provider and step agents in a
WorkflowRecipe, with these rules:
- A recipe may use at most one subscription provider.
spec.agent.secretRefis not allowed for a subscription provider.- The recipe picks a connection with an annotation, not a spec field. In the
recipe editor's confirm step, choose a ChatGPT grant or Grok grant.
Codex recipes store it in
clerum.io/codex-connection-refandclerum.io/subscription-connection-ref. Grok recipes store it inclerum.io/subscription-connection-refonly. - Grok recipes also need
WRC_GROK_SUBSCRIPTION_ENABLED=trueonworkflow-recipes. That switch controls the recipe's Grok permission, egress policy and pod environment.
Refresh, reconnect and revoke
- Access-token refresh is automatic. control-api refreshes the access
token when it authorizes a call.
POST …/connections/:key/refreshforces a refresh. - Reconnect. If the vendor rejects the saved refresh token, the
connection moves to
reauth_requiredand Control UI shows Reconnect ChatGPT / Reconnect Grok. This runs the same device-code sign-in. - Delete (revoke). Delete in the subscription list revokes the connection. control-api marks it revoked, cancels pending sign-ins, and asks the vendor to revoke the refresh token. Agents assigned to it keep the reference but can no longer authorize. Reassign them to another subscription.
- Grok revoke is permanent per key. A revoked Grok key cannot be reconnected. Create a new subscription instead. Access tokens issued before the revoke stay valid until they expire.
Limits to know
- Output ceiling on Codex SDK grants. A Plugin Workload SDK grant's
per-grant output ceiling (
maxOutputTokens) becomesmax_tokenson API-key providers. The ChatGPT subscription endpoint cannot take that field, so forcodex-subscriptiononly the transport contract's fixed limit applies. - Image input. Both providers accept PNG and JPEG image parts. The Grok image limits are based on xAI's public API documentation. They have not been measured against the Grok subscription endpoint. See Visual requests.
- One subscription provider per Host or recipe (see above).
- Requests are capped. Message, tool and body-size caps are listed under Limits in each transport contract.
Troubleshooting
| Symptom / error | Cause | Fix |
|---|---|---|
No LLM Subscriptions content, or API 404 {"error":"disabled"} |
CONTROL_API_*_SUBSCRIPTION_ENABLED is not true |
Set the flag in control-api-config and restart control-api |
Calls fail although sign-in worked; proxy answers 404 disabled |
*_LLM_PROXY_EXECUTION_ENABLED is off |
Set it in the proxy's ConfigMap and restart the proxy |
| Codex Host cannot build its provider | MCP_HOST_CODEX_SUBSCRIPTION_ENABLED missing from mcp-host-config |
Add it, then let HCC roll the Host |
| Grok recipe is refused or cannot reach the proxy | WRC_GROK_SUBSCRIPTION_ENABLED is off |
Set it on the workflow-recipes Deployment |
browser_oauth_unregistered |
Browser OAuth with the default public client | Use device code, or register an OpenAI client and set CONTROL_API_CODEX_OAUTH_CLIENT_ID |
| "… sign-in expired / denied / timed out" | Device code was not confirmed in time | Click Sign in again |
fingerprint_in_use |
That account already backs a live connection | Use the existing connection |
connection_key_taken |
Key already exists (for Grok, possibly a revoked key) | Choose another key |
reauth_required / "Reconnect" shown |
Vendor rejected the refresh token | Click Reconnect, then Sync catalog |
| New vendor model missing | Catalog is only read at sign-in | Sync catalog, or enable the cron |
default_model_not_offered |
Default model is not an enabled model on that connection | Enable the model first |
unassigned_connection |
Host has no connectionRef |
Assign a subscription on Models & creds |
spec.secretRef is required unless every LLM target is the same oauth-broker provider |
Mixed subscription + API-key chain without a Secret | Add secretRef for the API-key targets |
a Host may declare at most one oauth-broker provider |
Codex and Grok on one Host | Use one subscription provider per Host |
hosts_unavailable (503) |
control-api cannot read Host objects | Check control-api's Kubernetes access |