Share Codex setup while keeping local settings.
The problem
A machine may need its own settings while still sharing the same instructions and hooks. A blanket configuration copy can overwrite those differences or carry credentials with it.
An explanatory exhibit
Three layers make one local configuration
An explanatory layer model with no live settings, secrets or machine names.
- 01
Portable base
Shared instructions and defaults
- 02
Local overlays
Machine choices and secret values
- 03
Runtime config
Generated for this machine
Inspect the consequence
Update shared instructions
Change the portable base
A reusable instruction belongs in the versioned configuration that enrolled machines share.
Keep a machine-specific preference
Use the local overlay
A legitimate local choice can survive synchronization without becoming a global default.
What this makes possible
I brought the portable workbench to Codex with a base configuration, local overlays and a doctor command for checking the assembled setup.
Source information sheet
Evidence, implementation & history Implementation inspected
What I checked
Tracked configuration and documentation inspected through the v1.0.6 release line. This explains the source contract rather than every machine’s installed state.
Research cut: 14 October 2026. Source areas below are from metacodex. Private conversation references are retained in the research ledger and are not published here.
Implementation decisions
metacodex combines portable base configuration with machine and secret overlays. Selective links share managed resources, while generated runtime configuration remains local.
The documented workflow includes installation, synchronization, drift adoption, trust management and doctor checks. Adoption gives a legitimate local change somewhere to live rather than treating every difference as an error.
A path through the feature
- Assemble and inspect
Install the managed setup and run doctor to check its consistency.
- Adopt a legitimate local change
Place machine-specific settings in the local layer. Rebuild the runtime configuration and inspect it again.
Source areas
README.mdbin/metacodexconfig/config.base.tomlconfig/hooks.jsonconfig/AGENTS.md
The small explanatory exhibit uses invented records to describe the mechanism. Separate recordings and working examples carry their own evidence notes.
Recorded history
Dates describe the researched record, rather than today’s deployment.
Distributing the portable Codex setup
Fixing Codex configuration drift