Update the marketplace plugin
Use the Codex-verified marketplace update flow:
codex plugin marketplace upgrade astral-orchestrator
codex plugin add astral-orchestrator@astral-orchestratorStart a new Codex task after updating so Codex discovers the new plugin version. Updating the plugin does not publish, deploy, or change optional native profiles.
Refresh optional native profiles
After replacing a downloaded checkout with the newer complete repository, refresh only the optional profiles:
sh scripts/setup.sh --refreshThe refresh migrates only byte-exact shipped v3.4.0 Luna XHigh and Sol XHigh profiles to Luna Max and Sol High. A customized or conflicting profile remains untouched. Current MultiAgentsV2 hosts do not need those profiles for explicit native delegation.
Version 3 identity migration
Version 3.0.0 changed the former Project Pilot identity. Plugin and marketplace IDs are now astral-orchestrator; profile filenames begin with astral-orchestrator-; TOML names begin with astral_orchestrator_; route evidence begins with ASTRAL_ORCHESTRATOR_ROUTE; and persistent settings live under ~/.codex/astral-orchestrator/.
Install Astral as a new package. Remove Project Pilot separately only when you no longer use it. Old effort settings are intentionally not copied, so set desired values again.
Uninstall
Remove the plugin
codex plugin remove astral-orchestrator@astral-orchestratorRemove unchanged companion profiles
sh plugins/astral-orchestrator/scripts/install-agents.sh --removeOptionally remove the local marketplace entry
codex plugin marketplace remove astral-orchestratorProfile removal deletes only shipped files that still match exactly. These commands do not delete the downloaded repository, project files, or unrelated custom profiles.
Troubleshooting
| Problem | What to do |
|---|---|
| The plugin does not appear | Start a new Codex task, then run codex plugin list --marketplace astral-orchestrator. |
| Setup reports a profile conflict | Keep the custom profile. Native workers and the built-in default reviewer can use explicit values without it. Run sh scripts/setup.sh --refresh only when you deliberately want an unchanged shipped role restored. |
| A route cannot be proven | Check all five native controls: agent_type, task_name, model, reasoning_effort, and fork_turns. Never accept a different route as proof. |
| A Morph worker fails | Check the separately configured provider/model and requested effort with its owner. Astral does not configure OpenCodex, credentials, services, or provider compatibility. |
| Constellation will not fan out | Make cards independent with non-overlapping ownership, or use its documented serial Orbit-style route. The primary consumes one advertised slot. |
| Hypernova cannot launch | Verify observed Sol, Luna, or Astra primary evidence, all five native controls, safe capacity after the primary slot, an exact built-in Sol Max or configured Astra worker and reviewer route, and unique lowercase task names. Hypernova has no alternate route or downgrade. |
| An effort value is rejected | Choose a supported value available to the account. Max and Ultra are not available everywhere. |
| Setup cannot find Codex or Python | Install or update Codex and use Python 3.11 or newer, then rerun the dry run. |
Common questions
Does Astral make Codex faster?
Not automatically. It makes non-trivial work deliberate and evidence-qualified. Hypernova explicitly chooses throughput over token efficiency, but actual speed depends on safe independent work, observed capacity, and exact route availability.
Do updates erase effort settings?
No. They live outside the plugin cache. The former Project Pilot path remains deliberately separate.
Can a team share the install?
Share the public repository or a complete archive. Each person runs the two marketplace commands in their own Codex environment and needs their own model access. Do not share an installed profile directory by itself.