Can I log in to Codex on a server without opening a browser there?

Yes. Run `codex marathon login --device-code` on the server, open the displayed verification URL on your own machine, and enter the one-time code.

Where does the completed account go?

After native Codex login completes, CodexMarathon imports the identity under the alias you supplied. Verify it with `codex marathon accounts` before switching.

Should I copy auth.json from my laptop to the server?

No. Use the native device-code flow and the managed profile commands. Direct credential-file copying can expose secrets and bypass the transition contract.

Device-Code Login for Codex Accounts on a Server

Sign in to a managed Codex account on a headless server with a device code, then verify the alias and account state without copying credentials.

Yes. A headless server can sign in to a managed Codex account without running a browser on the server. Run codex marathon login <alias> --device-code, open the verification URL on a trusted machine, enter the one-time code, and finish the native ChatGPT sign-in. When Codex reports completion, the identity is stored under the alias you requested. Verify the account before enabling management or switching to it.

This flow is for supported managed ChatGPT authentication profiles. It does not move a browser cookie, copy auth.json, or turn a server into a credential relay. The CodexMarathon home page covers installation, while using multiple Codex accounts safely covers the broader profile workflow.

Prepare the server and install the native package

CodexMarathon is distributed as one package: the modified codex CLI, the private codexmarathon-accountd metadata service, and its user units. The installer starts the service and verifies its API, so a separate plugin or controller command is not required.

After installation, check the native state:

codex marathon status
codex marathon accounts

If you intentionally use a non-default state root, set an absolute path during installation or use the supported environment resolution. The installed CLI and account service must agree on the state directory. The local metadata socket remains under $XDG_RUNTIME_DIR; it does not move with the Codex state root.

Keep the server account private. Use your normal owner account, restrict shell access, and avoid pasting one-time codes into tickets, transcripts, or shared terminal recordings. The code is temporary, but the resulting managed identity is not something to publish.

Choose a meaningful alias that identifies the context, such as work or personal:

codex marathon login work --device-code

The native flow prints a verification URL and a one-time code. Copy only the URL and code to a browser on a machine you control. Open the displayed URL exactly, enter the code, and complete the ChatGPT sign-in for the account you intend to manage. Keep the server terminal open while native Codex waits for completion.

The alias is a local label, not a new provider account and not a plan selector. work should point to the work identity you are authorized to use. If the alias is already present, inspect the current accounts and follow the CLI’s conflict behavior rather than silently replacing a profile.

For an already active identity, import is different:

codex marathon import personal

import saves the identity already active in native Codex. login starts a native sign-in and imports the completed account automatically under the requested alias. Keeping those operations distinct helps you know whether you are recording an existing session or creating a new login flow.

Complete the verification on another machine

The device-code sequence is intentionally split across the server and browser:

The server starts native login and displays the URL and one-time code.
You open the URL on your own workstation or another trusted device.
You enter the code and sign in to the intended ChatGPT account.
The provider completes the native authorization flow.
The server receives native login completion and stores the managed identity under the alias.

Do not infer completion merely because the browser page accepted the code. Wait for the server command to report that native login finished. If it times out or reports failure, inspect codex marathon status and start a new device-code flow rather than reusing an old code.

The one-time code is not a replacement for account verification. Check which account the browser session represents before approving it, especially if the browser has more than one signed-in identity. A descriptive alias and a deliberate account check prevent a surprisingly common mistake: saving a personal account under a work label.

Verify the saved profile without exposing secrets

Once the command completes, list the managed metadata:

codex marathon accounts
codex marathon status

The list shows aliases, IDs, enabled state, and transition state without printing credential snapshots. If you need quota context, ask accountd for the bounded metadata view:

codex marathon accounts --daemon --format table

The accountd view can include credential health, five-hour and weekly quota observations, reset times, and freshness. It does not expose tokens, cookies, authorization headers, or raw credential files. If the alias is missing or health is not usable, do not guess that the login succeeded. Resolve the native result first.

When two aliases point to different identities, use status and the stable ID to confirm which one you mean. A label is convenient, but the ID and health state make an audit clearer. Save any logs you need without including terminal output that contains the one-time code.

Enable management and switch at a safe boundary

After verifying the profile, enable Marathon if it is currently off:

codex marathon on
codex marathon switch work
codex marathon status

The switch does not replace native Codex’s authority. Marathon waits until account-bound work is idle, checks the source identity again, validates and persists the target, and asks Codex to reload native authentication. Codex verifies the target before committing. An active model response, tool call, or subagent turn is not changed halfway through.

If the transition is rejected or uncertain, leave it visible in status and reconcile it before starting more account-bound work. Do not “fix” an uncertain result by copying a credential file into place. The auth.json mid-turn safety guide explains why direct replacement can leave the native thread and durable account state disagreeing.

Inside an interactive Codex session, the same login choices are available:

/marathon login work device-code
/marathon accounts
/marathon switch work

The panel also offers Browser link for a machine with a local browser. On a server, choose Device / auth code explicitly.

Common mistakes to avoid

Do not use an API key, external bearer credential, workload identity, or another unsupported provider mode with Marathon switching. Do not place a device code in a shell script, environment variable, command history committed to a repository, or shared log. Do not copy browser cookies or auth.json from a laptop to “save time.” Those shortcuts widen the trust boundary and bypass the native flow that performs identity verification.

Do not enable automatic switching before you have at least one verified managed profile and understand its alias. If you later add a second account, verify both rows before relying on an automatic recovery decision. The automatic switching guide explains how a usage-limit recovery waits for a fresh eligible identity.

The secure server workflow is therefore simple: start device-code login on the server, finish it on a trusted browser, wait for native completion, inspect metadata, and use the normal safe-boundary switch. No browser needs to run on the server, and no credential file needs to be copied between machines.