SuperGPT local mirror installation

SuperGPT local mirror

SuperGPT is a source-only, OpenAI-signed local mirror.

The target installer makes a byte-identical copy of the user's current official ChatGPT app, then launches it with an external Luma Cloud model provider. The dashboard DMG is not public-ready yet.

Installation support

Target customer journey

These are the intended release steps. While the DMG remains source-only, customers should not use repository builds or unpublished artifact URLs.

1Install or update the official ChatGPT desktop app. It may remain open, and SuperGPT does not require an OpenAI sign-in.

2When the release gate opens, download the generic SuperGPT helper DMG from the dashboard and verify its published checksum.

3Run the ad-hoc external installer. On first launch, explicitly approve that exact app through System Settings > Privacy & Security if macOS asks; never disable Gatekeeper or remove quarantine.

4Launch SuperGPT and choose the built-in Sign in action on its unchanged stock sign-in screen. The external Luma launcher redirects that action to Luma Cloud instead of OpenAI OAuth; the signed renderer itself is not patched or rebranded.

5In the Luma Cloud browser page, sign in with Google or an email code and approve this Mac. Pairing completes automatically: no activation JSON or API key is copied or pasted.

6The launcher reports readiness only after the signed mirror and its local Luma runtime survive the bounded first-launch health check. Recovery Key remains an explicit developer or recovery workflow, never normal setup.

Before install

Local mirror prerequisites

The official app, shared Codex state and Luma device credential each retain a separate authority.

The helper DMG is source-only. Public download remains unavailable until Gateway compatibility and the complete user-approved clean-Mac release receipt pass; customer payment is checked only when Gateway serves a request.

The current official ChatGPT desktop app installed at /Applications/ChatGPT.app. No OpenAI sign-in is required for SuperGPT's Luma inference or Usage; Dictation remains a separate blocked release gate.

macOS 14 or newer on Apple Silicon (M1 or better); the official ChatGPT source does not support Intel Macs.

A Luma Cloud account you can sign in to with Google or an email code. Installation and pairing do not require an active plan; the Luma Gateway checks subscription or API access only when a cloud request is made. Normal installation starts from the unchanged stock renderer, never reveals a raw Luma product key or activation JSON, and does not use OpenAI OAuth.

Enough local disk space to stage and verify the mirror plus one bounded rollback copy.

Delivery model

One helper DMG, one untouched official source, one changed model provider.

The DMG carries only Luma-owned external helpers. The signed application is always copied locally from the user's verified official installation.

Source-only

Helper DMG

Public download unavailable

The target generic macOS DMG is honestly ad-hoc signed and requires explicit approval of the exact helper. It contains only the installer, external launcher and Doctor—no ChatGPT app copy, customer credential or user state.

OpenAI-signed

Local signed mirror

/Applications/ChatGPT.app → ~/Applications/SuperGPT.app

The installer makes a byte-identical local copy of the current official app. It does not patch, rename internally or re-sign the bundle.

Luma inference only

External provider

https://api.lumaos.cloud/v1

An external launcher applies a command-scoped Luma Cloud provider to the copied stock Codex. The official app keeps its official route.

Boundary

What the local mirror owns and what stays stock.

All Luma-owned behavior stays outside the signed bundle. Shared Codex state remains shared, Electron state remains separate, and the official app stays on OpenAI's route.

OpenAI-signed mirror

~/Applications/SuperGPT.app is a verified byte-identical copy of /Applications/ChatGPT.app. The official source and its OpenAI route remain untouched.

External launcher

Luma-owned helpers stay outside the app under ~/.supercodex and launch the exact mirror with a command-scoped provider pointed at https://api.lumaos.cloud/v1.

Shared Codex Home

Both apps use the existing ~/.codex for threads, workspaces, MCP, plugins, skills, connectors, approvals and native Codex account state.

Separate Electron state

SuperGPT uses ~/Library/Application Support/SuperGPT for cookies, local storage, cache and crash state; it does not copy the official Electron profile.

Device credential

The private P-256 value is stored as an owner-scoped macOS Keychain generic password. ~/.codex/supergpt/device-auth.json is a regular owner-only 0600 public profile and contains no product key.

Hash-verified helpers

Doctor and every launch verify an owner-only receipt for the external wrapper, core helpers and packaged Node runtime before the signed mirror starts.

Redacted local evidence

Installer, Doctor and launch receipts live outside the app. API tokens, OpenAI auth, cookies, user content and provider internals must never appear in logs or support bundles.

macOS safety

Doctor keeps the mirror current without mutating either signed app.

Source acceptance is signature- and identity-based rather than version-based. Every copy and swap is staged, verified and recoverable.

Source

Doctor accepts the current installed /Applications/ChatGPT.app by bundle identity, OpenAI Team identity, strict signature and Gatekeeper checks—not by an exact version allowlist.

Copy

The installer stages a byte-identical owner-owned mirror, verifies every file and symlink, then atomically promotes only ~/Applications/SuperGPT.app.

Official app

The official app is never stopped, moved, modified, signed or rerouted. Both apps share ~/.codex without forcing another OpenAI authentication.

OS trust

The helper is intentionally ad-hoc and uses explicit per-app user approval. The locally mirrored app must retain the OpenAI Developer ID signature and notarization. Never clear quarantine, disable Gatekeeper or request sudo.

Doctor

After an official app update, Doctor automatically stages and verifies a fresh mirror when replacement is safe.

Rollback

If copy, signature, byte identity, provider health or first-launch verification fails, Doctor preserves or restores the last-known-good user-owned mirror with a crash-recoverable rename-only swap.

Uninstall

Run the dashboard's safe uninstall command. It attempts exact device revocation, deletes the matching Keychain item and removes only verified SuperGPT-owned paths while preserving official ChatGPT and shared ~/.codex state.

Acceptance boundary

Verify the signed mirror, shared state, bounded Luma features and automatic recovery.

A clean-Mac run must prove every boundary below. Opening a local window or passing source-only tests does not make the dashboard DMG public-ready.

Byte-identical signature

The mirror matches the official bundle tree and retains the intact OpenAI signature; the official app remains unchanged.

External Luma provider

Only stock Codex model discovery, Responses/SSE and Compact use the command-scoped Luma provider and short-lived device bearer.

Shared and separate state

Threads and native Codex state stay shared in ~/.codex while SuperGPT keeps a separate Electron profile.

Remote Control blocked

Remote Control is unavailable in SuperGPT until its exact stock routes receive an explicit reviewed Luma desktop contract. The official ChatGPT app may remain open.

Luma Usage; Dictation gated

The unmodified stock UI reaches only the allowlisted SuperGPT-local facade. Usage is projected from Luma Cloud; batch Dictation remains blocked pending the Gateway subscription-entitlement canary and exact user-approved helper-DMG E2E.

Automatic Doctor

Doctor detects official app changes, safely recopies and verifies the mirror, then preserves one bounded rollback copy.

Troubleshooting

Stop safely, collect evidence, then escalate.

Treat source verification, OS trust, provider, shared-state, Remote and Doctor failures as release findings. Preserve the official app, shared ~/.codex and last-known-good mirror.

DMG is unavailable

This is expected while the release is source-only. Do not construct, reuse or share an unpublished artifact URL.

Browser sign-in expires or is rejected

Return to SuperGPT and choose its built-in Sign in action again, then complete Google or email-code sign-in on the Luma Cloud page. Never put activation JSON, device tokens or recovery keys in a support message or command line.

Official source is rejected

Install the current official ChatGPT app from OpenAI and retry. Do not modify, re-sign or bypass verification of either app.

Luma inference fails

Capture the visible request id and sanitized launch receipt. Do not substitute a localhost or private upstream URL, and do not alter the official app route.

Remote Control is unavailable

This source-only SuperGPT contour closes Remote Control routes until they receive an explicit reviewed Luma desktop contract. The official ChatGPT app may remain open.

Dictation is unavailable

This is expected until the Gateway subscription-entitlement admission is deployed, a bounded included-key device canary passes, transcription traffic is enabled and the exact user-approved helper DMG passes clean-Mac E2E. Only the current canonical included SuperGPT key of an active subscription qualifies, through its device bearer or the explicitly selected Recovery Key path. API Wallet, portable, legacy, and other-product keys cannot qualify; do not add desktop billing logic or redirect audio to official OpenAI services.

Doctor reports blocked

Keep using the last-known-good mirror while the current official app or provider seam is unsafe. A failed recopy must roll back without touching the official app or shared ~/.codex.

Remove SuperGPT

Close SuperGPT and copy the safe uninstall command from the dashboard. It revokes the paired device when reachable and deletes its local Keychain/profile state. Never delete shared ~/.codex; it belongs to both official ChatGPT and SuperGPT.

Wrong endpoint in a client

Use https://api.lumaos.cloud/v1. Do not paste localhost, shard, VPS, or OmniRoute URLs into customer tools.

Support request

Send OS, architecture, ChatGPT source version, mirror receipt, Doctor state, visible request id and sanitized logs. Do not send API tokens, cookies or auth files.

Truth gate

The current helper DMG is source-only and must not be presented as working public software.

Do not publish repository builds, helper commands, packages, ZIPs or executables merely because a route or file exists.

Public readiness requires an immutable helper candidate, checksum and dashboard metadata plus clean-Mac proof of byte identity, OpenAI signature, device pairing/revocation, Product DB subscription-only Luma Dictation, truthful Usage, Doctor recopy and rollback. Remote Control remains explicitly unavailable behind a separate future feature gate.

Related setup docs

Use these when a user needs an external CLI or IDE key instead of the source-only SuperGPT desktop path.

API setup Client matrix Support

Reviewing the source-only local mirror?

Preserve the official app and shared ~/.codex, use only the immutable candidate under review, and include sanitized mirror and Doctor receipts with any finding.

Installation support