Will Codex State Survive Your Docker Image Upgrade?
Give the project and Codex state distinct Docker mounts, then compare the effective mounts and synthetic state probes across container replacement. With local Docker Sandboxes, select the Codex session mixin if conversations must survive sandbox removal.
Review mount identity before switching image tags
A Docker bind mount ties the project to a specific host directory. During an image upgrade, compare the effective mount type, source, destination, and write mode before opening Codex in the replacement. A container can start successfully while pointing at a different checkout. A mount at an ancestor of the project directory can also obscure expected image contents, and a nested mount can redirect part of the tree. Use a disposable project with a harmless marker, then check that the expected marker is visible and a scratch edit appears in the intended host checkout. Record the destination reported by Docker alongside the directory used by the Codex process. When a rebuild appears to lose changes, those observations distinguish a wrong checkout from a project permission problem.
Bind mounts | Docker DocsCheck write access and roll back by state version
Docker volumes outlive individual containers. Give Codex state a dedicated named volume and record its identity with the image tag and the container user's numeric UID and GID. Before changing image or user, test the upgrade against a disposable copy containing a synthetic state marker. Verify the replacement can read that marker and write a second one using the same identity that runs Codex. A readable marker with a failed write points toward ownership or permissions. A successful write with the first marker missing warrants checking the volume name and the state path used by the process. For an actual upgrade, retain a protected pre-upgrade backup so rollback can pair the old image with its earlier state if the new version changes the state format.
Volumes | Docker DocsPut each file in the right place
Build the image with your chosen Codex CLI release and project tools, then set the runtime user to a non-root account. Start with a disposable project checkout. Bind-mount only that checkout at the workspace path and make it the working directory. Use a writable mount if you want Codex edits to appear on the host. Leave your broader home directory and Docker socket out of the container.
Mount a dedicated named volume at the Codex state directory for the runtime user, and confirm that the configuration uses that directory before signing in. Keep credentials out of the image and build context. Before the first agent run, check the effective user and test writes to both mounts. If the project write fails, inspect host ownership and container user mapping before broadening permissions.
Bind mounts | Docker DocsProve persistence with two containers
In an illustrative test, name the volume codex-pilot-state and use a scratch checkout with no production credentials. Start one container, create review-marker.txt in the workspace, and save a harmless preference in the configured Codex state directory. Check the workspace file from the host. Remove the container while retaining its named volume, then start a fresh container with the same two mounts.
The workspace marker should still be visible on the host, and the preference should be present in the replacement container. If the marker is missing, check the bind mount source and destination. If the preference is missing, check the volume name and the state path used by the runtime user. After the harmless test passes, repeat the replacement with your intended sign-in method and verify that Codex can complete a basic request.
Volumes | Docker DocsUse Docker Sandboxes for host-side sign-in
Choose local Docker Sandboxes when you want the packaged Codex workflow with authentication prompted on the host for the default OpenAI models. Use the documented sbx run codex ~/my-project with the path to a disposable checkout for your pilot. Confirm that the sandbox can open the intended project and complete a benign edit. Review the edit from the host before using a checkout that contains valuable work.
Conversation continuity is a separate acceptance test. Docker documents adding a session mixin at creation if you want to preserve Codex conversations after removal and recreation. Set it up before the pilot and try resuming a scratch conversation after replacement. If the project files survive but the conversation is unavailable, check the session mixin configuration and the documented resume procedure.
Codex | Docker DocsUse the reference image to debug dependencies
Try OpenAI's codex-universal image when a build behaves differently in your custom container and the Codex cloud environment. Pull the documented image with docker pull ghcr.io/openai/codex-universal:latest and record the resolved digest. Run the same narrow build or test in a scratch checkout in both environments. Record the relevant tool versions, the first failing step, and the error output.
For an illustrative case, suppose a fixture passes in the reference image and fails in your custom image because a compiler is missing. Add the compiler to your image definition and rebuild to see whether the same fixture passes. Treat agreement as evidence about that dependency. OpenAI describes codex-universal as a reference environment, so use the actual cloud job to verify behavior that depends on cloud setup or configuration.
GitHub - openai/codex-universal: Base docker image used in Codex environments · GitHub