# Codex Preflight

> On-demand general Codex runtime preflight for network/TLS/writable-roots/tool/provider readiness using `scripts/codex-preflight.sh`.

- Skill: `santiago-afonso/codex-preflight` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add santiago-afonso/codex-preflight`
- Raw SKILL.md: https://api.skillmd.com/api/skills/santiago-afonso/codex-preflight/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: santiago-afonso (https://skillmd.com/u/santiago-afonso)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/santiago-afonso/codex-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:
```bash
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:
```bash
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:
```bash
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.