> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullfrog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex subscription

> Run OpenAI models on the Codex access in your ChatGPT plan instead of paying for API tokens.

Run Pullfrog on the Codex access included in every ChatGPT plan, with no OpenAI API bill on top. One command signs you in and stores the credential.

<Note>
  A Codex subscription covers the OpenAI models in the picker, including GPT Astra, GPT Sol, GPT Terra and GPT Luna. For other providers, see [Model access](/model-access).
</Note>

## Setup

Run this inside a clone of the repository. The CLI uses the [GitHub CLI](https://cli.github.com) to sign you in, and the [Codex CLI](https://developers.openai.com/codex/cli) must be on your `PATH`.

```bash theme={null}
npx pullfrog auth codex
```

The CLI:

1. Runs `codex login` in a temporary Codex home, so your own `~/.codex/auth.json` is untouched.
2. Codex opens the ChatGPT sign-in in your browser. Sign in and approve it.
3. Refreshes the new credential once, then saves it to Pullfrog's encrypted store.

The next run on an OpenAI model uses the subscription. Run the command again to add another ChatGPT account or replace one. With several connections, or an `OPENAI_API_KEY` beside them, Pullfrog moves to the next credential when one is rejected or out of quota; see [multiple subscriptions and fallback](/keys#multiple-subscriptions-and-fallback).

### Remote machines

The browser sign-in finishes on `localhost`, so the browser must be on the machine that runs the CLI. Over SSH, or on Linux with no display, the CLI signs in with a one-time code instead: it prints a URL and a code to enter in a browser on any device. Pass `--device-auth` to choose the code yourself:

```bash theme={null}
npx pullfrog auth codex --device-auth
```

ChatGPT keeps device-code sign-in behind a setting. Turn it on in [ChatGPT security settings](https://chatgpt.com/#settings/Security) for a personal account. On a Team, Business or Enterprise plan, a workspace owner turns it on in [workspace permissions](https://chatgpt.com/admin/permissions), under **Codex Local**.

<Frame>
  <img src="https://mintcdn.com/pullfrog/klps40MoSQ5FJkiz/images/subscription-cards.png?fit=max&auto=format&n=klps40MoSQ5FJkiz&q=85&s=c888cdc3e19f077e18222aeec019c367" alt="The Subscriptions row of the Providers section: Claude Pro/Max, ChatGPT (Codex) and Grok" width="1680" height="532" data-path="images/subscription-cards.png" />
</Frame>

## Scope

On an organization repository, the CLI asks where to store the credential:

| Option | Scope | Who can save it |
| - | - | - |
| **`<owner>` organization** | Every repository in the organization | Organization owner |
| **`<owner>/<repo>` only** | This repository | Repository admin |

A personal account has only the account scope, so the CLI does not ask. To skip the prompt or run outside a checkout, pass the scope as a flag:

```bash theme={null}
npx pullfrog auth codex --org my-org          # organization scope
npx pullfrog auth codex --repo my-org/my-repo # one repository
```

## Credential refresh

ChatGPT access tokens last about ten days, and every refresh replaces the refresh token. Pullfrog keeps the stored copy current on its own:

* Before a run, Pullfrog refreshes the stored credential when less than a day is left on it.
* After a run, Pullfrog saves any token the run refreshed back to its store.

The credential must stay in Pullfrog for this to work. A copy in a GitHub Actions secret cannot be updated after a refresh and stops working.

## Troubleshooting

| Symptom | Fix |
| - | - |
| The browser ends on a `localhost:1455` page that does not load | The browser is on a different machine from the CLI. Run `npx pullfrog auth codex --device-auth`. |
| The ChatGPT page refuses the one-time code, or asks you to contact your workspace admin | Device-code sign-in is off. Turn it on in [ChatGPT security settings](https://chatgpt.com/#settings/Security), or have a workspace owner turn it on in [workspace permissions](https://chatgpt.com/admin/permissions), then run the command again. |
| CLI: "was already connected here, so no subscription was added" | The browser signed in as a ChatGPT account you had already connected. Sign out of ChatGPT in that browser, or open the sign-in link in a private window, then run the command again. |
| CLI error: "codex CLI not found on PATH" | Install the [Codex CLI](https://developers.openai.com/codex/cli). The error message includes the install command for your platform. |
| Run comment: "Your ChatGPT subscription was rejected by its provider", or `CODEX_AUTH_JSON was rejected by OpenAI` / `Token refresh failed: 401` in the job log | ChatGPT ended the session behind the credential, for example after a sign-out or an expiry. Run `npx pullfrog auth codex` and replace the old connection. |
| Job log: "subscription auth skipped: could not create /var/lib/pullfrog" | Pullfrog keeps the credential in a directory the agent cannot read, and creating it needs passwordless `sudo`. Allow passwordless `sudo` for the runner user, use a GitHub-hosted runner, or add an `OPENAI_API_KEY`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.