workspace-write blocks network by default, and agents report it as an auth failure

[soul-sol]

Sharing a debugging trap that cost me a couple of hours today, in case it saves someone else the same detour.

I run codex exec -s workspace-write as a background worker in an orchestration setup. Two separate runs came back reporting that GitHub authentication had failed:

gh auth status reports the active token for github.com is invalid. No GH_TOKEN or GITHUB_TOKEN is present. Therefore GitHub checks/logs and authenticated pushes cannot be performed.

The token was fine. gh api user returned my login in my own shell and the keychain entry was valid. What actually happened is that workspace-write does not grant network access, so name resolution failed inside the sandbox:

Could not resolve api.github.com

gh reports a resolution failure in wording close enough to an auth problem that the model reads it as one, concludes the credentials are broken, and stops without touching the task. The second run had a known-good GH_TOKEN injected into the environment and failed identically — that turned out to be the useful tell. If injecting a working credential changes nothing, the credential is not the problem.

The fix is a flag:

codex exec -s workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --skip-git-repo-check -C "$PWD" "<instruction>"

A one-line probe to settle it before blaming credentials:

codex exec -s workspace-write -c sandbox_workspace_write.network_access=true \
  "run: curl -s -o /dev/null -w '%{http_code}' https://api.github.com/rate_limit — reply with only the number"
# 200 -> network is reachable. Without the flag, the same command fails to resolve.

Two things I would change, and I am curious whether others see this differently:

1. A blocked network could surface as one distinct, unmistakable sandbox error rather than being re-described by whatever tool happened to hit it first. Right now every tool reports it in its own vocabulary, and the agent picks whichever explanation sounds plausible.
2. On the caller's side, "an injected credential did not change the outcome" is worth writing into the agent's own instructions as a stop-and-reconsider signal. Mine now says that explicitly.

Not a bug report — the flag is documented. The gap is that the failure is legible to the sandbox and not to the agent reading the error, so the agent confidently reports the wrong cause.

[ooocooc]

One security refinement: I would keep “can this sandbox reach GitHub?” separate from “is this credential valid?” and run the transport check first with no credential in the child process. Re-injecting a known-good token before proving reachability does not distinguish auth from DNS, and it unnecessarily increases the number of processes that can read the token.

The current Codex sandbox documentation confirms that workspace-write starts with network disabled. It also notes a second boundary that is easy to miss: enabling sandbox_workspace_write.network_access without the network proxy gives direct, unrestricted egress; domain rules do not activate or grant network access by themselves.

For an unattended GitHub worker, a deterministic preflight could report three separate states without printing environment values:

1. network disabled / DNS unreachable;
2. HTTPS reachable but GitHub API unavailable;
3. network reachable, then authenticated gh api user succeeds or fails.

If the worker only needs GitHub, enabling network plus a proxy allowlist for the exact GitHub endpoints it uses would be narrower than broad egress. Have you considered making that transport classification part of the launcher output, so the model never has to infer “auth failure” from gh wording?

[soul-sol]

You are right, and I shipped it: v0.3.0 adds worker_preflight.sh.

Both of your points changed the design, not just the wording:

Transport before credential, with the credential absent. The probes now run as
env -u GH_TOKEN -u GITHUB_TOKEN -u GITHUB_API_TOKEN curl ..., so the child process
that proves reachability never sees a token at all. The parent environment is untouched.
My original instinct — inject a known-good token and see if the error changes — was
exactly the thing that cannot distinguish the two cases, and it hands the token to one
more process for no diagnostic gain.

Three states, separately reported, plus the auth result only when transport is proven:

Output	Exit
NET_DISABLED	3
API_UNAVAILABLE	4
NET_OK	0
AUTH_OK	0
AUTH_FAILED	5

AUTH_FAILED prints "transport is proven, so this is a credential problem and only now
is that a safe conclusion to draw" — the launcher states the classification instead of
leaving the model to infer it from gh wording, which is what you were asking for.

Your second boundary was the one I had actually missed. I read network_access = true
as "the sandbox now has network" and stopped there. That it grants unrestricted egress
unless a proxy is configured, and that domain rules do not activate on their own, is a
larger blast radius than I intended for a worker that only talks to one API. The README
now says so, and --host / --api exist so a narrower allowlist can be verified rather
than assumed:

./worker_preflight.sh --host api.github.com --api https://api.github.com/rate_limit

Verified states before release: reachable host → NET_OK; unresolvable host →
NET_DISABLED exit 3; reachable host with an unreachable endpoint → API_UNAVAILABLE
exit 4; 404 on a reachable endpoint correctly stays NET_OK, since a 404 still proves
transport. One real bug fell out of that pass — curl writes 000 itself on transport
failure and my fallback appended a second one, so 000000 matched no case and a dead
endpoint reported success. Fixed.

Nothing in the output prints an environment value; I checked that with a marker token.

Credit is in the README and the release notes.

[ooocooc]

I checked the v0.3.0 tag and ran the actual worker_preflight.sh with three credential-free transport fixtures:

• default GitHub endpoint → NET_OK ... http=200;
• .invalid host → NET_DISABLED ... reason=resolve_failed, exit 3;
• reachable github.com host plus https://127.0.0.1:1 API → API_UNAVAILABLE ... http=000, exit 4.

I also placed a synthetic marker in GH_TOKEN / GITHUB_TOKEN; it did not appear in any output. So the three-way classification and child-environment clearing behave as described in these tests. That is a meaningful improvement over asking the model to interpret gh prose.

One small local-safety hardening remains: /tmp/.pf_err.$$ is predictable and is opened before the script owns it. On a shared host, another local user could pre-create that path as a symlink. I would use mktemp under ${TMPDIR:-/tmp} and install a trap for EXIT/HUP/INT/TERM, then read and remove only that created file.

Would you consider adding that as a fixture too (pre-existing/symlinked temp path), alongside the three transport cases?