Codex Carry-On 🧳

Give Codex a bigger suitcase: a friendly, fail-closed macOS CLI that moves its local state to an external APFS SSD — no symlinks, no surprises, no drive, no launch.

Tested a different Mac or SSD?
Share your setup · Compatibility lab · Community cabin

Codex can accumulate sessions, logs, skills, generated files, SQLite state, and other local data under CODEX_HOME. Codex Carry-On moves that state to an external SSD, verifies the copy, keeps a protected pre-migration recovery baseline on the Mac, and refuses to launch against the wrong or missing drive.

It builds on Codex’s documented public location variables: CODEX_HOME and CODEX_SQLITE_HOME.

This project is terminal-first, dependency-free, and intentionally scoped to Codex/ChatGPT desktop state only. It refuses to take over an existing custom CODEX_HOME policy; return to the standard ~/.codex layout before setup.

Help the suitcase earn its stickers

Our first public milestone is five independent installations across more than one Mac model and more than one SSD family. A successful report is useful data, not clutter.

• Share a working setup in Show and tell.
• Ask before migrating in Q&A.
• Use the Mac + SSD compatibility form when a result should be tracked.

Please include the Mac, macOS version, SSD or enclosure, connection, APFS status, Carry-On version, and a concise redacted result. See the compatibility lab for the reporting format.

Before boarding

Codex Carry-On moves important local state. Treat it like a storage migration, not a theme switch.

• Use a dedicated encrypted APFS SSD with ownership enabled.
• Keep another independent backup of anything irreplaceable.
• Quit ChatGPT/Codex before setup, rollback, repair, or intentional drive removal.
• Never hard-pull the SSD while the app is running.
• This is an independent community project, not an OpenAI product.

The internal recovery baseline is a pre-migration rollback point. It is not a live backup of newer SSD-only sessions.

Requirements

• macOS with Python 3.9 or newer
• a dedicated external USB or Thunderbolt SSD formatted as APFS
• encrypted APFS and ownership enabled (recommended and enforced by default)
• enough free space for the state copy plus a 10 GiB safety reserve
• ChatGPT/Codex fully quit during setup, repair, rollback, or rescue

Install

curl -fsSL https://raw.githubusercontent.com/jazzinglee/codex-carry-on/main/install.sh | zsh

Open a fresh Terminal, then plug in the SSD and run:

codex-carry-on doctor --volume /Volumes/MySSD
codex-carry-on setup  --volume /Volumes/MySSD

Setup explains the exact source, destination, recovery path, and drive identity, then requires this confirmation:

PACK CODEX INTO THE CARRY-ON

Administrator authentication may be requested only for the metadata-preserving copy.

What it does

1. Verifies macOS, APFS, external-media identity, encryption, ownership, write access, and free space.
2. Proves ChatGPT/Codex is offline for a stability window.
3. Copies state with macOS metadata, ACLs, flags, resource forks, and extended attributes.
4. Omits only the transient zero-byte ipc/ipc.sock endpoint when present.
5. Compares paths, bytes, symlinks, ownership, modes, flags, mtimes, ACLs, portable xattrs, and hardlink topology.
6. Accepts APFS-generated differences only for com.apple.provenance; com.apple.macl must remain exact.
7. Validates every discovered SQLite family from disposable copies using quick_check, integrity_check, and foreign_key_check.
8. Promotes verified staging with an exclusive same-volume rename.
9. Moves the original ~/.codex into a protected recovery baseline under ~/Library/Application Support/CodexCarryOn/.
10. Records a stable cryptographic recovery fingerprint while deliberately ignoring allocation and APFS provenance-only drift.
11. Places a zero-byte mode-000 guard at ~/.codex to prevent silent fallback recreation.
12. Pins the installed guard, verifier, and LaunchAgent hashes in the manifest.
13. Installs a LaunchAgent that sets CODEX_HOME and CODEX_SQLITE_HOME only when the recorded SSD identity passes.
14. Optionally wraps the interactive codex command in ~/.zshrc so each CLI launch revalidates the drive.

No .zshenv modifications. No symlinked state root. No other agent integrations.

Daily use

Normal Dock/Finder launches work once the recorded SSD is mounted and ready.

codex-carry-on status
codex-carry-on open
codex-carry-on run -- --version

The optional shell hook makes ordinary CLI calls safe too:

codex --version

The periodic guard validates while the healthy environment remains on the SSD. It switches to an unwritable sentinel only when validation fails, avoiding a recurring healthy-launch race.

Commands

Command	Purpose
doctor --volume /Volumes/MySSD	Check prerequisites without moving data
setup --volume /Volumes/MySSD	Copy, verify, and cut over
status [--json]	Show readiness and recorded paths
open [--app ChatGPT]	Revalidate and open the desktop app
run -- <args>	Revalidate and run the official Codex CLI
repair	Recreate the fallback guard after an app updater replaced ~/.codex
rollback	Restore the protected pre-migration internal state
rescue --status	Inspect a partial transaction
rescue --restore-internal	Restore the sole retained baseline when normal rollback cannot run
shell-hook --install/--remove	Manage the optional interactive zsh wrapper

Unplugging the drive

1. Quit ChatGPT/Codex completely.
2. Confirm no Codex process remains.
3. Eject the SSD normally.

When the drive is absent, new GUI and CLI launches fail closed. Reconnect the recorded SSD, wait a few seconds, then run:

codex-carry-on status

App updates

An updater may replace or remove the fallback object at ~/.codex. The protected baseline lives elsewhere, so this does not destroy the recovery copy. Keep the app closed and run:

codex-carry-on repair

The command preserves any unexpected ~/.codex object before creating a new guard and updating its recorded identity.

Rollback

codex-carry-on rollback

Rollback first re-hashes the protected recovery baseline and requires its stable fingerprint to match the setup record. It then restores only the retained pre-migration internal state. The external SSD state remains untouched; newer SSD-only sessions are not merged automatically.

Supported scope

Codex Carry-On relocates the state rooted at CODEX_HOME and points CODEX_SQLITE_HOME to the same external home. It does not move the application bundle, Homebrew, Xcode, Simulator state, or unrelated caches under ~/Library.

See Architecture, Recovery, Compatibility, Community, and Security for the detailed model.

Development

git clone https://github.com/jazzinglee/codex-carry-on.git
cd codex-carry-on
python3 -m unittest discover -s tests -v
./bin/codex-carry-on --version

The test suite runs pure logic and a mocked end-to-end cutover on Linux and macOS. Real migration tests require a disposable external APFS volume and are intentionally not run in shared CI.

License

MIT. Pack lightly, verify heavily.