safe-codex

What it does

Rootless Podman is preferred when available. Docker works, but a user in the docker group should be treated as effectively root-capable on the host.

Repository files

The launcher parses .env as plain KEY=VALUE. It does not source shell code, and it accepts only SAFE_CODEX_* keys plus OPENAI_API_KEY.

Build

Check what the launcher sees before building or running:

./bin/safe-codex-podman doctor

Build with Podman:

./bin/safe-codex-podman build

Build with Docker:

./bin/safe-codex-docker build

The build uses npm once inside the build container with --ignore-scripts, then removes npm, npx, and corepack from the runtime image.

Host npm guard

The container image removes package-manager entrypoints from the Codex runtime. If the host should also keep node and node-based tools available while avoiding accidental npm, npx, or corepack use, install the optional per-user deny stubs:

./bin/install-node-package-tool-deny-stubs --dry-run
./bin/install-node-package-tool-deny-stubs

This writes managed stubs and helper commands under ~/.local/bin:

~/.local/bin/npm
~/.local/bin/npx
~/.local/bin/corepack
~/.local/bin/strip-node-package-tools
~/.local/bin/check-node-package-tools-disabled

The helper also updates ~/.bashrc by default so ~/.local/bin stays first in PATH. If nvm has already been loaded by that startup file, the installed wrapper strips npm, npx, and corepack again after common nvm commands that can reintroduce them.

Existing ~/.local/bin entries with those names are moved under ~/.quarantine before replacement. Existing nvm package-manager files are also moved there by strip-node-package-tools. The script does not run npm, npx, corepack, or package install scripts.

Verify the host state at any time:

check-node-package-tools-disabled

Use --no-rc if you do not want the script to edit a shell startup file. Use --rc-file PATH to point it at a different Bash startup file.

To undo the guard, remove the marked safe-codex disable host npm/npx/corepack block from the shell startup file, remove the managed commands from ~/.local/bin, and restore files from ~/.quarantine only if you intentionally want those tools back.

Native Codex install

To restore or install host Codex without restoring host package-manager entrypoints, use the native installer:

./bin/install-native-codex-cli --dry-run --version 0.130.0
./bin/install-native-codex-cli --version 0.130.0

The installer downloads the platform-specific @openai/codex native tarball directly from the npm registry, requires an explicit version, verifies the registry-published sha512 integrity value, extracts only the native vendor payload, and writes a ~/.local/bin/codex launcher.

The default payload path is:

~/.local/share/codex-cli/VERSION

The script does not invoke npm, npx, corepack, nvm, or node. The generated launcher blocks codex update by default, so upgrades remain an explicit reinstall with a pinned version.

Run Codex

From the project you want Codex to work on:

/path/to/safe-codex/bin/safe-codex-podman run

Docker equivalent:

/path/to/safe-codex/bin/safe-codex-docker run

Default behavior

• Profile: default.
• Workspace: current directory mounted at /workspace read/write.
• Persistent state: safe-codex-state-default mounted at /home/codex/.codex.
• Nonpersistent home: /home/codex tmpfs with noexec.
• Network: proxy, using safe-codex-proxy-nonlocal.
• GPU devices: none.
• Lifecycle: Codex containers are removed on exit; state persists in the named volume.

Common options

For a read-only-by-default workflow, set SAFE_CODEX_WORKSPACE_MODE=ro in .env, then pass --workspace-rw only when a run should edit the workspace.

Detach and resume

Detach from a live container without stopping Codex:

Ctrl-p Ctrl-q

Attach again:

/path/to/safe-codex/bin/safe-codex-podman attach

If the machine restarted or Codex exited, run the same run command again. The process is gone, but Codex auth/session files persist in the profile volume.

Ask Codex to resume from the persistent volume:

/path/to/safe-codex/bin/safe-codex-podman run -- resume

Storage model

The container home is split deliberately.

For the default Podman profile, the persistent volume is stored on the host at:

~/.local/share/containers/storage/volumes/safe-codex-state-default/_data

Inspect through Podman so rootless user-namespace ownership is displayed correctly:

podman volume inspect safe-codex-state-default
podman unshare ls -la ~/.local/share/containers/storage/volumes/safe-codex-state-default/_data

Profiles

Use separate profiles for separate trust zones:

/path/to/safe-codex/bin/safe-codex-podman run \
  --profile id-overlay \
  --workspace /path/to/id-overlay

This creates container name safe-codex-id-overlay and state volume safe-codex-state-id-overlay. Profile names may contain only letters, numbers, dot, underscore, and dash.

List existing persistent profiles and any live Codex containers:

/path/to/safe-codex/bin/safe-codex-podman profiles

Multiple sessions

A profile controls Codex's persistent state. A workspace controls which host files are mounted at /workspace. Changing the profile while keeping the same workspace gives you a separate Codex state volume looking at the same host files.

/path/to/safe-codex/bin/safe-codex-podman run \
  --profile edit-1 \
  --workspace /path/to/project \
  --workspace-rw

/path/to/safe-codex/bin/safe-codex-podman run \
  --profile edit-2 \
  --workspace /path/to/project \
  --workspace-rw

A safer pattern is one writable editor plus one or more read-only reviewers:

/path/to/safe-codex/bin/safe-codex-podman run \
  --profile edit \
  --workspace /path/to/project \
  --workspace-rw

/path/to/safe-codex/bin/safe-codex-podman run \
  --profile review \
  --workspace /path/to/project \
  --workspace-ro

If two sessions should edit independently, use separate git worktrees or clones and give each one its own profile.

Read-only and extra mounts

Inspect a repo read-only:

/path/to/safe-codex/bin/safe-codex-podman run \
  --workspace /path/to/suspicious \
  --workspace-ro

Override a read-only .env default for a normal editing session:

/path/to/safe-codex/bin/safe-codex-podman run \
  --workspace /path/to/project \
  --workspace-rw

Add one writable output folder:

/path/to/safe-codex/bin/safe-codex-podman run \
  --workspace /path/to/project \
  --rw /tmp/codex-output:/output

Add a read-only reference folder:

/path/to/safe-codex/bin/safe-codex-podman run \
  --workspace /path/to/project \
  --ro /path/to/docs:/mnt/docs

The launcher refuses risky mounts by default, including /run, /var/run, /dev, /proc, /sys, ~/.ssh, ~/.codex, and mount trees containing Unix sockets. Symlinks are resolved before this check. Paths containing commas or newlines are rejected because Docker and Podman --mount cannot represent them unambiguously.

Extra mount destinations are constrained to:

/mnt/rw...
/mnt/ro...
/workspace/...
/input...
/output...

Override these checks only with a concrete reason:

--allow-risky-mounts

GPU devices

GPU access is opt-in. The default run exposes no NVIDIA devices, no DRI render nodes, and no broad /dev mount.

Expose all NVIDIA GPUs:

/path/to/safe-codex/bin/safe-codex-podman run \
  --gpu nvidia

Expose one or more NVIDIA GPUs by index or UUID:

/path/to/safe-codex/bin/safe-codex-podman run \
  --gpu nvidia:0

/path/to/safe-codex/bin/safe-codex-podman run \
  --gpu nvidia:0,1

/path/to/safe-codex/bin/safe-codex-podman run \
  --gpu nvidia:GPU-01234567-89ab-cdef-0123-456789abcdef

With Podman, NVIDIA mode uses CDI devices such as nvidia.com/gpu=all. With Docker, it uses Docker's --gpus flag. The host still needs working NVIDIA container support.

Expose one explicit DRI render node for an AMD or Intel iGPU:

/path/to/safe-codex/bin/safe-codex-podman run \
  --gpu dri:/dev/dri/renderD128

/path/to/safe-codex/bin/safe-codex-podman run \
  --gpu dri:/dev/dri/by-path/pci-0000:00:02.0-render

Find stable render-node names on the host:

ls -l /dev/dri/by-path/*-render

Use the actual path from that listing for --gpu dri:... or SAFE_CODEX_AMD_IGPU_RENDER.

The DRI mode resolves symlinks and accepts only /dev/dri/renderD* character devices. The launcher also requires the current host user to be able to read and write the render node before starting the container. On many systems that means adding the user to the render group and starting a new login session.

If you want a named iGPU default in .env, set:

SAFE_CODEX_GPU=amd-igpu
SAFE_CODEX_AMD_IGPU_RENDER=/dev/dri/by-path/pci-0000:00:02.0-render

Network modes

The proxy uses a dedicated egress network named safe-codex-egress-nonlocal unless SAFE_CODEX_EXTERNAL_NETWORK is set.

Authentication

Preferred: pass an API key from the environment.

export OPENAI_API_KEY=...
/path/to/safe-codex/bin/safe-codex-podman run

Do not mount host ~/.codex. That directory contains live auth/session material. If you use browser/login auth inside the container, it is stored in the profile's named Codex-state volume.

Environment variables passed with -e or --env-file are visible through container inspection while the container is running. The launcher removes the Codex container on exit so those values are not left in stopped container metadata.

Shell

Open a shell with the same containment settings:

/path/to/safe-codex/bin/safe-codex-podman shell \
  --workspace /path/to/project

Maintenance

Show readiness:

./bin/safe-codex-podman doctor

Show containers, volumes, and networks:

./bin/safe-codex-podman status

List persistent Codex profiles:

./bin/safe-codex-podman profiles

Inspect a specific proxy profile:

./bin/safe-codex-podman proxy status --mode openai

Stop a live Codex container:

./bin/safe-codex-podman stop --profile default

Remove a running container but keep persistent Codex state:

./bin/safe-codex-podman rm --profile default

Delete a profile's persistent Codex state only when intended:

podman volume rm safe-codex-state-default

Checks

Run local syntax checks without building images:

./bin/check

This validates the launcher scripts, the native Codex installer, the optional host npm guard, and Dockerfile syntax. If safe-codex-proxy:latest already exists, it also runs Squid's parser against both proxy profiles. If shellcheck is installed, it is used too.