Codex preflight

When to use

• You see sandbox-ish errors like PermissionError: [Errno 1] Operation not permitted, seccomp, or unexpected “Permission denied” when paths look writable.
• You need to know if network is disabled in the tool sandbox before attempting auth, installs, git push, etc.
• You want an explicit environment readiness snapshot for helper CLIs like

read-pdf, pdf-to-markdown, llm, or wbg-auth.

• You want a compact provider/auth readiness view for CLIs like gh,

gcloud, gws, llm, aws, az, or oci.

Workflow

1) Run the preflight helper:

scripts/codex-preflight.sh

Compatibility note: scripts/codex-sandbox-preflight.sh still exists as a shim, but scripts/codex-preflight.sh is the canonical script name.

2) If you’re in a normal shell and want structured output:

scripts/codex-preflight.sh --json

3) If you’re in a normal shell and want to see what happens when network is enabled inside the sandbox:

scripts/codex-preflight.sh --with-network

4) Summarize results (don’t paste the full output unless asked):

• Tool sandbox network: socket() allowed vs blocked (and DNS if allowed).
• TLS / CA trust: whether Python HTTPS can complete a TLS handshake, and whether

CA-related env vars, Node CA env vars, proxy env vars, or local WBG CA bundle preparation look relevant.

• Runtime environment: Python interpreter path/version and venv status,

uv version, Node toolchain versions, and whether the session appears to be in WSL, Windows, or a container.

• Repo state: current git branch and a concise staged/unstaged/untracked summary

when inside a git worktree.

• Workflow tools: whether tk, read-pdf, pdf-to-markdown, llm, and

wbg-auth are available, plus a concise tk queue summary when applicable.

• Provider auth readiness: whether codex, gh, gcloud, gws, llm,

aws, az, and oci look ready, missing, partial, or unsupported.

• Writable roots: whether ~/.config/wbg-auth is writable inside the sandbox.
• Config drift: whether ~/.codex/config.toml is symlinked to dotfiles or has diverged.

Interpretation cheatsheet

• INFO- socket() syscall blocked:
• Tool sandbox has network disabled (expected in many sandboxed sessions).
• Avoid network-dependent commands/tools inside the sandbox.
• To allow sandbox network, start Codex with -c sandbox_workspace_write.network_access=true (still sandboxed, but with egress).
• WARN missing_writable_root=$HOME/.config/wbg-auth (or similar) / sandbox write fails for ~/.config/wbg-auth:
• wbg-auth will crash on startup due to log file creation.
• Fix by adding ~/.config/wbg-auth to sandbox_workspace_write.writable_roots in ~/.codex/config.toml.
• WARN- python TLS handshake ... failed certificate verification:
• Network reachability exists, but Python HTTPS trust is broken.
• On the WBG MITM network, refresh the local CA install with

bin/wbg-ca-helper install-wsl-trust.

• For Python tools that use requests / certifi, exporting

REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt and SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt can be necessary even when basic socket and DNS checks pass.

Notes / pitfalls

• Running this from inside an already-restricted tool sandbox cannot “prove” that enabling network would work; outer seccomp will still block socket(). Use --with-network from a normal shell for that.
• On corporate MITM networks, basic socket and DNS success does not guarantee

Python HTTPS success; read the TLS / CA section before assuming “network is OK”.

• This helper must never print secrets; it only checks tool presence, config linkage, writability, DNS, and certificate-trust readiness.
• Prefer the stable command codex-preflight when it is on PATH; the old

sandbox-named entrypoint is compatibility-only.