This application manages the authentication state used by the official Codex runtime: local accounts on macOS/Windows and saved Linux server accounts through an SSH helper. Local and remote stores use different encryption mechanisms.
The headless Linux helper uses a separate passphrase-encrypted vault (scrypt and
AES-256-GCM), never a plaintext fallback for inactive accounts. Its live command
uses the owning daemon's private socket. Inactive refresh and switching refuse
running Codex processes and require supervised maintenance with automatic
reconnections disabled; process scanning alone cannot prevent an external client
from starting between checks. See Linux security and recovery.
The latest tagged release and the current main branch receive security fixes.
Older release lines are not maintained unless a release note says otherwise.
- Local saved account credentials are encrypted with Electron
safeStorage, which uses macOS Keychain-backed protection on macOS and Windows DPAPI-backed protection on Windows. Server saved credentials use a separate scrypt/AES-256-GCM vault. - The renderer has
nodeIntegration: false,contextIsolation: true,sandbox: true, andwebSecurity: true. - The renderer is denied all HTTP(S) and WebSocket requests.
- External navigation and popup windows are denied.
- Stored account tokens and vault keys never appear in UI responses. The UI receives account metadata and sanitized rate-limit data. Remote enrollment also displays the official verification URL and current one-time code. A user-entered existing vault passphrase briefly occupies a password input, which is cleared on submission.
- Credential files are written atomically with restrictive local file modes where supported by the platform.
- Before saving a live credential, both its account/workspace and email must match the saved profile. A different or unidentified login is rejected without replacing the snapshot. This also applies before and after active-account usage checks.
- Before switching away, the matching current
auth.jsonis written back into its encrypted profile so rotated refresh tokens are preserved. - Guarded handoff never closes a running Codex process. It queues until Codex is no longer running, then revalidates confirmed capacity and account eligibility before switching.
- Automatic destinations are restricted to accounts the user explicitly enables with the same continuity-group label. The destination identity is checked after reopening; verification failure attempts to restore the source account.
- The handoff journal contains account identifiers, phase, timestamps, trigger, and sanitized errors only. It does not contain prompts, thread history, command output, or credentials.
- An OS-encrypted rollback backup is made before replacing the active credential.
- Electron runtime features not required by the app are disabled using Electron Fuses during packaging.
Usage refreshes contact Codex services through the bundled Codex App Server. The renderer remains network-denied. An inactive account is decrypted only in the main process, copied into a unique temporary Codex home for the request, and removed after the App Server exits. If Codex rotates that account's credentials, the refreshed snapshot is accepted only after its account identity matches and is then encrypted back into the vault. Tokens and raw App Server output are not sent to the renderer or written to the usage cache. A failed usage request can still rotate tokens: the newest credentials are preserved before cleanup, and a private recovery home is retained when persistence or owned-process shutdown fails. Such homes are not automatically swept on startup.
The desktop main process runs OpenSSH with normal host-key verification and batch authentication. A fixed, bounded JSON-lines protocol over SSH stdin/stdout exposes helper operations and sanitized metadata. The renderer has no SSH or network access. Server installation runs without sudo and does not restart Codex, change the server config or expose a public listener.
For desktop-created vaults, the main process protects an installation-specific random vault key with OS encryption before sending it through SSH stdin. An existing CLI passphrase is verified against the server vault before local encrypted persistence. Aliases for one installation share the same protected key. There is no forgotten-key recovery.
Clipboard writes require an explicit action. Copy code writes only the current active device-login code. Terminal access… separately verifies and copies the full vault key for the helper's hidden prompt or a password manager; that key grants access to every saved account in the server vault. These operations do not read the clipboard or return the vault key to the renderer.
Live usage is read from an existing private daemon socket without starting a replacement daemon. Saved-account refresh and switching require a quiet server; the helper does not stop arbitrary client processes. Switching validates account and workspace identity, preserves outgoing credentials, journals the transaction inside the encrypted vault, rechecks the live file and replaces it atomically. The selected auth file does not prove every running session adopted that login. Reconnect clients and verify their actual identity after a supervised switch.
The implementation's review findings, fixes and verification boundaries are recorded in Remote desktop integration and verification.
Packaged macOS builds check this repository's GitHub Releases on startup and roughly every four hours through electron-updater in the main process. Those requests disclose normal connection metadata to GitHub (and its download infrastructure); account tokens, email addresses and conversation content are not included by the switcher. The renderer remains network-denied.
A check never downloads or installs an update. Download requires the user's explicit action, and installation requires Install and restart; quitting normally does not install a downloaded update. Downgrades are disabled. Update payload hashes are checked by the updater; macOS's native update mechanism requires a compatible code signature. This trust depends on the maintainer's GitHub account and Apple signing identity. Checksums alone are not independent proof of authorship. The repository does not embed a GitHub access token.
macOS release signing and notarization use the maintainer's local Keychain. GitHub builds Windows and checks both uploaded macOS architectures against the expected Apple team before automatic publication. Source/hash receipts bind the assets to the tagged commit and verification run. Apple private keys and notarization credentials are not installed on GitHub runners.
Existing v0.2.1 and earlier release assets are unsigned and cannot bootstrap a trusted auto-update chain. The first signed/notarized version must be installed manually, after verifying its published signing status. Windows updates remain manual and Windows installers remain unsigned.
This application does not:
- host an OpenAI login page;
- request or store an OpenAI password;
- request or store TOTP/2FA seeds;
- inspect browser cookies;
- read Codex conversation/session history;
- parse prompts, project files, or Codex logs;
- provide analytics, telemetry, crash reporting, automatic turn submission, automatic approvals, or guaranteed task restoration.
The application runs as the signed-in OS user. Malware or another process already executing with the same user's privileges may still be able to read the live plaintext Codex auth.json while Codex is using it. The encrypted profile vault primarily protects inactive saved profiles at rest and prevents accidental plaintext duplication.
For maximum separation between unrelated organizations, use separate OS user accounts instead of a credential switcher.
Do not attach real auth.json files, tokens, cookies, passwords, TOTP seeds, or screenshots containing secrets to GitHub issues or pull requests.
Please report suspected vulnerabilities privately through GitHub Security Advisories. Include the affected version or commit, operating system, reproduction steps, impact, and a suggested fix if you have one. Redact credentials and other personal data from all evidence. If private reporting is unavailable, contact the repository owner through their GitHub profile and do not publish the issue until a fix or mitigation has been coordinated.
The maintainer will acknowledge reports when practical, investigate privately, and publish a release note when a fix is available. Please allow reasonable time for triage before public disclosure.