docs(codex): document secure integration for the managed app-server daemon #4751

User Story

I use OpenShell to run Codex with ChatGPT OAuth in a Linux sandbox. While qualifying npm-installed Codex 0.162.1 in a custom image, I encountered network denials for its managed app-server executable rather than the launcher/npm executable paths in the reference Codex provider profile.

I would like a documented, supported installation and policy workflow for this layout, or an explicit statement of its limitations. I have paused qualification rather than broadly authorize executable paths in writable CODEX_HOME.

Problem Statement

Codex can make model connections from a managed daemon under CODEX_HOME/packages/app-server-daemon/releases/.../bin/codex. The reference profile lists launcher/npm paths and correctly warns that operators must customize them for their image, but does not explain how to handle this managed component's installation, executable identity, or updates.

The observed denial is expected enforcement of the configured paths, not evidence of an OpenShell core enforcement bug. This is a request to close a concrete integration/documentation gap, not to automatically trust new executable paths.

Observed environment

• OpenShell CLI and gateway: 0.1.3.
• Linux amd64, rootless Podman.
• Custom OpenShell image with npm-installed Codex 0.162.1; a wrapper creates the sandbox with a Codex OAuth provider.
• An external supervisor middleware is attached; its direct Describe check succeeds and the complete sandbox policy attachment is loaded.

This has not been independently reproduced with an unmodified native Gator image. The custom image/wrapper context is relevant. OpenShell 0.1.4 has not been tested live; the observations below are from 0.1.3.

Evidence

Codex startup and account/workspace routing checks succeed. After a clean model prompt, the TUI reports Reconnecting... waiting for network.... Native supervisor/OCSF diagnostics identify this denied connection:

NET:OPEN DENIED
executable=/sandbox/.codex/packages/app-server-daemon/releases/0.162.1-x86_64-unknown-linux-musl/bin/codex
destination=chatgpt.com:443
reason=transparent_tcp_policy_denied

Both the provider-composed Codex rule and the base Codex network rule lack this canonical daemon executable. They contain the reference launcher/npm paths. The base rule additionally contains Node. No broad executable permission under /sandbox has been added.

The external middleware separately logs allowed POSTs to ab.chatgpt.com; those do not establish that the generation connection passed. The concrete denial above occurs at executable network authorization, not a content-middleware decision.

Impact / Why This Matters

Normal Codex model traffic remains blocked in this deployment, preventing completion of upgrade qualification. Merely listing more executable paths does not explain which managed package should be trusted, how it is selected, or what an operator should expect after a Codex/daemon update. We prefer a supported least-privilege workflow over a blanket writable-cache wildcard.

Proposed Documentation / User Workflow

Please document a workflow in the Codex provider/image guidance that lets an operator:

1. Select a supported, versioned Codex installation, including its managed daemon.
2. Identify the canonical executable that makes model connections and configure the corresponding provider/base-policy selectors for the intended hosts.
3. Understand package provenance and filesystem requirements, including whether an image-owned/read-only daemon layout is supported or recommended.
4. Verify clean model traffic without relaxing destination or middleware controls, and understand how daemon upgrades interact with policy and integrity checks.

This is a proposed documentation workflow, not a tested configuration or a request for a particular internal implementation. If this layout is unsupported, documenting that limitation and the supported alternative would also address the request.

Acceptance Criteria

• Codex integration guidance covers the managed app-server executable layout or explicitly identifies unsupported layouts/versions.
• A supported installation/policy example names the actual connecting executable and explains package trust and update handling without relying on a blanket writable-cache authorization.
• The example is verified on an identified OpenShell/Codex/image combination, with clean model traffic working and existing executable, destination, and applicable middleware restrictions preserved.

Alternatives Considered

• Image-specific provider/base-policy edits: this is the existing extension point and may be sufficient; the missing piece is a supported package/identity/update workflow, not necessarily new core functionality.
• Broad writable-cache selectors: not adopted because they expand which executable installations are eligible for network authorization.
• Image-owned/read-only managed package: potentially preferable, but not tested here; guidance is needed on whether Codex supports such a layout.
• Middleware/interceptors: retained where configured; they inspect otherwise authorized traffic and do not resolve the missing executable authorization shown here.
• Upgrade OpenShell alone: not established as a solution. The v0.1.3 and v0.1.4 reference Codex profiles are identical; no live 0.1.4 result is claimed.

Agent-Assisted Investigation

• The tagged Codex daemon README documents managed package copying and selection under CODEX_HOME/packages/app-server-daemon.
• Both the OpenShell v0.1.4 profile and current reference profile still show launcher/npm paths and explicitly require image-specific edits.
• The v0.1.3 and v0.1.4 profile contents are byte-for-byte identical. The v0.1.4 release notes do not identify a managed-daemon integration fix; this is source/document evidence, not a reproduced failure on 0.1.4.
• Collaborator guidance in #440 recommends a base-policy update for an older sign-in case. We are not assuming its port-forwarding advice applies to this already-working OAuth setup.
• #4214 / #4215 address a different account-routing identity issue, not this executable layout.
• The v0.1.3 binary-identity implementation implements a SHA-256 trust-on-first-use cache that rejects subsequent changed hashes at a pinned path. We are not claiming that OpenShell lacks replacement detection; the requested guidance concerns managed-package provenance, supported installation, and update handling alongside those existing checks.

Existing issues/PRs and published reference material were searched; no exact managed-daemon-path report was found. The first Codex release affected has not been established. No live policy workaround or additional runtime test was performed for this report.