codex login Without a Browser: Device Auth Step by Step

codex login normally opens a browser for OpenAI’s sign-in page, which fails on a VPS, a container, or anything you only reach over SSH. The built-in fix is codex login --device-auth: the CLI prints a short code, you approve that code at chatgpt.com from any device that does have a browser, and the server receives its tokens without one. OpenAI documents the flow for exactly this case at developers.openai.com/codex/auth.

How device auth works

Device auth moves the browser step to a device you already have: the server prints a code, your phone or laptop approves it, and the CLI collects its tokens. It is the same pattern TVs and consoles use for sign-in, applied to a terminal.

The handshake runs directly between you and OpenAI. The server never sees your password, only the resulting session tokens, and nothing about the flow requires an API key. Sign in with the ChatGPT account you want the machine to bill against, and Codex usage runs on that plan’s included limits.

The walkthrough

Install the CLI if the box does not have it yet:

npm install -g @openai/codex   # or: brew install codex

Request device auth:

codex login --device-auth

The CLI prints a chatgpt.com URL and a one-time code. On any device with a browser: open the URL, sign in to the ChatGPT account this machine should use, and enter the code. Back in the terminal, the CLI confirms the login and exits.

Smoke-test the session with a non-interactive call:

codex exec --sandbox read-only "reply with exactly: auth works"

Three details worth knowing:

• The code expires after a few minutes. If you miss the window, run the command again for a fresh one.
• The account you approve with decides everything downstream: Codex is included in ChatGPT Free, Go, Plus, Pro, Business, Edu, and Enterprise plans, with limits that differ by tier. OpenAI’s pricing page has the current numbers.
• One sign-in covers the whole machine for that user. codex, codex exec, and scripts all reuse it.

Where the credentials land

A successful login writes ~/.codex/auth.json. That file is a signed-in session in a file: tokens rather than your password, but anyone who reads it can spend your plan. Treat it exactly like a password.

chmod 600 ~/.codex/auth.json

The hygiene rules that follow from that:

• Never commit it. If your home directory sits anywhere near a repo, add .codex/ to your global gitignore.
• Never paste its contents into issues, chat, or CI variables.
• Moving it between machines you personally own is fine: scp it, or mount it as a volume. The account is still yours, used by you. What OpenAI’s terms rule out is sharing the account with other people, and that includes sharing this file.

codex logout deletes the file when you retire a box, and you can revoke sessions from your account settings at chatgpt.com, which is good practice after decommissioning a server you no longer control.

The SSH port-forward alternative

If you would rather run the normal browser flow, forward the login helper’s port instead. codex login listens on localhost port 1455 to catch the sign-in redirect, and SSH can carry that port to your laptop:

ssh -L 1455:localhost:1455 user@your-server
# then, inside that SSH session:
codex login

Copy the URL the CLI prints into your local browser. The redirect lands on port 1455 on your laptop, the tunnel delivers it to the server, and the login completes as if the browser were local. Device auth is one step shorter; the tunnel earns its keep when policy pins sign-ins to your workstation browser.

Staying signed in

The CLI refreshes its tokens as it runs, so a machine that works regularly tends to stay signed in. Plan to re-run the login when the box sat idle long enough for the session to lapse, when you revoked sessions, or when you switch accounts.

For unattended machines that catch is operational: cron does not notice an expired session, your job just starts failing quietly. The fuller headless picture, TTY quirks included, is in our headless server guide, and if the box is a fresh VPS, the complete VPS setup goes from provisioning to scheduled jobs.

Why this flow exists at all

Device auth is one visible piece of a larger shift: ChatGPT subscriptions becoming credentials that tools authenticate against, not just a login for a chat app. We traced that shift in sign in with ChatGPT, explained.

It is also the exact flow used to connect Codex Hosted: the device-auth handshake runs between you and OpenAI, we never see the password, and the session lands in a container only your account uses.

Getting signed in is the easy five minutes. Keeping a box signed in, queued, and observed is the recurring work, and doing it yourself is free and entirely workable for personal scripts. When the jobs need to behave like infrastructure, Codex Hosted vs running Codex yourself lays out both sides honestly.