Ahab

Posted on Aug 3 • Originally published at indieseek.co

Codex GPT-5.4 Retirement: Terra and Luna Migration Checklist

#ai #productivity #opensource #programming

Codex GPT-5.4 retirement: migrate signed-in workflows to Terra or Luna

Quick answer

OpenAI says GPT-5.4 and GPT-5.4 mini will retire from Codex on August 31, 2026 for users signed in with ChatGPT. The official Codex migration is deliberately specific:

Replace gpt-5.4 with gpt-5.6-terra.
Replace gpt-5.4-mini with gpt-5.6-luna.

Update active workspace defaults, saved model settings, managed configurations, custom agents, and scheduled tasks before the cutoff. Do not mechanically change OpenAI API integrations or Codex sessions authenticated with an API key: OpenAI explicitly says those two boundaries are not affected by this retirement.

The safest rollout is an inventory-first migration. Change one model class at a time, preserve reasoning effort and security settings, then replay representative interactive, custom-agent, and scheduled tasks. The original increment in this guide is a five-surface inventory, a boundary-aware decision tree, and eight acceptance canaries.

Who this is for

This checklist is for developers and workspace administrators who use Codex in the ChatGPT desktop app, CLI, or IDE extension with ChatGPT sign-in and have pinned GPT-5.4-family model IDs.

If you are choosing among the whole GPT-5.6 family for an API workload, use the separate Sol vs Terra vs Luna decision guide. This article handles a narrower product event: removing two models from ChatGPT-authenticated Codex without accidentally rewriting unaffected API routes.

What changes—and what does not

Model availability follows the product surface and authentication boundary. Treat those as part of the configuration, not as implementation detail.

Surface or authentication boundary	August 31 effect	Action
Codex desktop, CLI, or IDE with ChatGPT sign-in and `gpt-5.4` pinned	Model retires	Replace with `gpt-5.6-terra`
Same surfaces with `gpt-5.4-mini` pinned	Model retires	Replace with `gpt-5.6-luna`
Codex with an OpenAI API key	Not affected by this notice	Leave unchanged unless a separate API migration is approved
OpenAI API application code	Not affected by this notice	Keep its own model-selection and eval process
Codex workflow with no old model pinned	No literal migration target	Verify automatic selection; do not invent a change

This distinction prevents the most damaging mistake: turning a Codex entitlement change into an unplanned API migration. It also keeps the official Codex mapping intact. A general family comparison might lead a quality-first API workload toward Sol, but the retirement notice maps signed-in Codex GPT-5.4 directly to Terra and GPT-5.4 mini to Luna.

Build the five-surface inventory

Search only the repository and the explicit Codex configuration directory you intend to audit. Do not recursively scan an entire home directory or print environment files that may contain secrets.

codex_config_root="/absolute/path/to/your/codex-config"

rg -n --hidden \
  --glob '!.git/**' \
  --glob '!logs/**' \
  'gpt-5\.4(-mini)?' \
  ./.codex "$codex_config_root"

Classify every match before editing:

Inventory surface	Active evidence to find	Migration rule
Workspace default	`model` in project configuration	5.4 → Terra; 5.4 mini → Luna
Saved model setting	Current picker or persisted client setting	Update, then confirm the active model in a fresh task
Managed configuration	Admin-enforced model value or allowlist	Change scope deliberately and retain rollback
Custom agent	Agent TOML or UI model override	Preserve the agent's role and reasoning effort
Scheduled task	Automation model selection	Update before the next run and execute one manual canary

Historical articles, screenshots, migration notes, and eval fixtures are not active configuration. Leave them as history unless they are also copied into a live template.

A bounded migration workflow

1. Freeze the baseline

For each active reference, record the surface, authentication method, old model, reasoning effort, task type, latency, and whether the task uses tools. Save one successful representative result. This creates a comparison point without modifying prompts or permissions.

2. Apply the official one-to-one mapping

For an ordinary project or agent configuration, the change should be as small as:

model = "gpt-5.6-terra"
model_reasoning_effort = "high"

For a repeatable worker previously pinned to GPT-5.4 mini:

model = "gpt-5.6-luna"
model_reasoning_effort = "medium"

Keep the existing effective effort for the first comparison when the target supports it. Do not change the model, prompt, tool policy, sandbox, and approval mode in one commit; that makes failures impossible to attribute.

3. Migrate managed and scheduled surfaces separately

Workspace policy and scheduled tasks can affect people or runs that are not visible from a repository search. Update them through their documented admin or automation surface. Do not edit an internal database or opaque state file. Run a manual scheduled-task canary before trusting the next unattended trigger.

4. Replay representative work

Use the same prompt, files, tools, reasoning effort, and success criteria as the baseline. Compare task completion, required corrections, wall time, and permission requests. If Terra or Luna misses an important acceptance criterion, record the failed trace and evaluate the task separately; do not silently switch every workflow to Sol.

5. Prove no active old reference remains

Repeat the bounded search, inspect the product model picker, and review scheduled tasks. A zero-result repository search is necessary but insufficient because saved and managed settings may live outside the checkout.

Decision tree

Is the workflow using Codex with ChatGPT sign-in? If no, this retirement notice does not authorize a change.
Is gpt-5.4 or gpt-5.4-mini actively pinned? If no, verify automatic selection and stop.
For gpt-5.4, start with Terra. For gpt-5.4-mini, start with Luna.
Does the baseline replay pass with the same effort and permissions? If yes, keep the mapping.
If it fails, isolate the task and evaluate model, effort, or prompt changes one at a time. Keep that broader tuning outside the retirement-only patch.

Eight acceptance canaries

Canary	Pass condition
Authentication boundary	Every record says ChatGPT sign-in or API key explicitly
Workspace default	A fresh task starts on the mapped model
Saved setting	Restarting the client does not restore GPT-5.4
Managed configuration	Intended groups can select the replacement; unintended groups are unchanged
Custom agent	The agent loads and completes its representative task
Scheduled task	One manual run completes and records the replacement model
Security invariants	Sandbox, approval policy, network access, and tool permissions are unchanged
API isolation	No OpenAI API route changed solely because of the Codex retirement

Copyable migration record

codex_gpt_5_4_retirement:
  deadline: "2026-08-31"
  authentication: "ChatGPT sign-in"
  mappings:
    gpt-5.4: gpt-5.6-terra
    gpt-5.4-mini: gpt-5.6-luna
  surfaces:
    workspace_default: passed
    saved_setting: passed
    managed_configuration: not_applicable
    custom_agents: passed
    scheduled_tasks: passed
  reasoning_effort_preserved: true
  security_settings_unchanged: true
  api_routes_changed: false
  rollback_owner: "named person or team"

Common mistakes

Changing API model strings because the names match. The retirement applies to ChatGPT-authenticated Codex. API access is a separate boundary.

Replacing both old models with Sol. The official Codex mapping is Terra for GPT-5.4 and Luna for GPT-5.4 mini. A different target needs its own eval-backed decision.

Checking only one config file. Saved settings, managed policy, custom agents, and scheduled tasks can keep stale pins after the project default is clean.

Changing several variables at once. Preserve prompt, reasoning, permissions, and tools for the first replay so any regression has one likely cause.

FAQ

Will GPT-5.4 stop working in the OpenAI API on August 31?

Not because of this Codex notice. OpenAI says the API and API-key-authenticated Codex sessions are unaffected. Follow API deprecation notices separately.

Can I choose GPT-5.6 Sol instead of Terra or Luna?

You can evaluate another model for a specific workload, but that is broader model selection, not the one-to-one retirement migration. Start with the official mapping, then use representative evals before changing the workload's cost, latency, or quality tier.

Sources

Originally published at IndieSeek.

DEV Community