[codex] Document macOS automation sandbox launch#3747
Conversation
There was a problem hiding this comment.
Pull request overview
Documents a macOS-specific constraint for launching the in-process automation bridge under “Codex-style” sandboxed command execution, clarifying the supported headless invocation so agents can reliably bring up the QLocalServer-based control channel.
Changes:
- Adds macOS guidance warning that sandboxed Cocoa startup can abort before the bridge initializes.
- Notes that
QT_QPA_PLATFORM=offscreendoes not overcome sandbox restrictions on the bridge’sQLocalServersocket. - Provides the supported headless macOS launch command to run outside the command sandbox.
There was a problem hiding this comment.
Reviewed — docs-only change to docs/automation-bridge.md, and it looks good.
Accuracy & placement:
- The new paragraph sits naturally right after the existing headless/CI
QT_QPA_PLATFORM=offscreennote, which is exactly where a reader hits the sandbox question. - The launch command matches the Quickstart's macOS form (
./build/AetherSDR.app/Contents/MacOS/AetherSDR) and the sameAETHER_AUTOMATION=1/QT_QPA_PLATFORM=offscreenenv vars used elsewhere in the doc — no drift. - The
QLocalServersocket reference is consistent with the transport section ("Transport: aQLocalServer… AF_UNIX socket on macOS"), so the explanation of why the sandbox blocks the bridge is correct.
Scope: single file, additive (+10/-0), no flat-key AppSettings, no code paths touched — nothing outside the stated scope.
One small nit (non-blocking): the guidance is specific and useful, but if there's a known minimum macOS/Codex sandbox config where it does work, a one-line "if you must sandbox, grant X" would round it out. Not required — documenting the supported path is the right call.
Thanks for capturing this, @rfoust — sandbox-launch failures are exactly the kind of thing that's frustrating to rediscover, and the reproduction notes in the PR body are a nice touch.
🤖 aethersdr-agent · cost: $2.8502 · model: claude-opus-4-8
ten9876
left a comment
There was a problem hiding this comment.
Approving — accurate, well-placed docs-only addition. The macOS sandbox caveat is consistent with the doc's Transport section (QLocalServer AF_UNIX socket) and reuses the established env vars + launch-command form, no drift. Documents the supported headless path, which is the right call. CI green. Thanks @rfoust — exactly the kind of gotcha worth capturing.
Summary
Documents the macOS automation-bridge launch constraint observed under Codex-style sandboxed execution. The sandboxed Cocoa launch can abort during
QApplicationstartup before AetherSDR reaches the automation bridge, and forcingQT_QPA_PLATFORM=offscreeninside the same sandbox still prevents the bridge from binding itsQLocalServersocket. The doc now gives the supported headless automation launch command: run outside the command sandbox withQT_QPA_PLATFORM=offscreen AETHER_AUTOMATION=1.Constitution principle honored
Principle XII - this treats the sandbox boundary as infrastructure behavior, not something AetherSDR can reliably recover from after Qt aborts before app code runs.
Test plan
cmake --build build)cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfocmake --build build --target AetherSDR --parallelAETHER_AUTOMATION=1.QT_QPA_PLATFORM=offscreen AETHER_AUTOMATION=1launch answerstools/automation_probe.py ping.Additional checks:
git diff --checkChecklist
docs/COMMIT-SIGNING.md)AppSettingscalls - use nested-JSON-under-one-key(Principle V)
reverse-engineered from a proprietary binary (Principle IV)
MeterSmoother(AGENTS.md convention)