Codex sandbox preflight

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.