OpenShell Harness providers and exposure

How the OpenShell SandboxDriver attaches credential sources and each Agent revision's runtime provider to a Sandbox, and how dedicated Codex exposes its app-server.

Credential attachments

For an Agent revision that uses a credential source, the paired Credential Gateway issues one attachment per source. Compute passes them to the OpenShell Sandbox Driver in credentialAttachments. The Driver appends each attachment's provider name to the static providers list in SandboxSpec, rejecting a name outside the OCC oce-cs- provider shape or one that repeats a static provider. Startup rejects static providers entries that use the OCC shape, so operator-configured providers cannot impersonate a credential source. After the Harness is ready, Compute requires every attachment to report ready before activation.

For external ChatGPT authentication, the Sandbox stores account metadata but omits static CODEX_ACCESS_TOKEN. Only the attached OpenShell provider supplies its bound alias. Withdrawal therefore leaves no placeholder on restart, and the Harness holds its authentication failure without starting Codex or using cached state.

Dedicated runtime providers

Each Agent revision's runtime providers use oce-codex-runtime or oce-openclaw-runtime profiles. Both expose node-enrollment and Gateway CA files after the Agent Gateway issues setup. Codex requires nonsecret runtime.json and config.toml, each at most 65,536 UTF-8 bytes, addressed through OPENCLAW_PLUGIN_RUNTIME_MANIFEST and OPENCLAW_PLUGIN_CODEX_CONFIG_TOML; native OpenClaw rejects them. Ordinary Secret-backed environment projections remain unsupported.

The expiring setup token is visible inside the Sandbox, without a production credential guarantee. Policy limits node egress to the Gateway and executable. Codex waits for its provider route; native OpenClaw connects outbound. Renewal updates node_setup_json only if the provider's resource version still matches; endpoint, TLS fingerprint, runtime files, CA, and identity labels must also match. Native startup reads the envelope; the Codex supervisor rereads it before node retries and retains valid setup during projection gaps. The raw app-server token stays outside the provider. Repository broker configuration fails before creation.

Agent revision cleanup deletes the Sandbox before its Git and runtime providers; Namespace cleanup removes leftover Git providers and unused profiles. Adoption requires matching Namespace, Agent, and Agent revision IDs and nonsecret configuration, except when renewing an expired setup envelope. Failed or timed-out Sandbox creation may complete remotely. The provider remains for normal Agent revision cleanup with the Sandbox.

Codex plugin installation

For a dedicated Codex Agent, the Harness installs selected plugins with a temporary native app-server over stdio after login and protected-egress setup. Both native processes use the same private CODEX_HOME. Preparation must finish within 60 seconds; its process must exit within eight seconds before the final authenticated WebSocket app-server starts. Installation failure prevents startup. The existing supervisor cleans the process group before retrying a failed wrapper.

The final process receives the transport verifier. The Gateway keeps the raw transport token and uses the admitted plugin configuration without the ordinary Compute peer-status exchange. Restart repeats preparation; unchanged reconciliation does not reinstall. Managed configuration disables removed selections even when package files remain cached.

Installation requires a Codex-backed account with access to the selected plugin and any required app connection. Permit the catalog's package origins through the selected egress policy, separately from credential-bearing API endpoints. Ordinary Sandbox configuration supports exact-host, binary-scoped read-only REST access with enforced inspection. Omit tls for automatic TLS inspection; the pinned gateway rejects explicit terminate. A protected egress plan is authoritative; Sandbox defaults do not extend it. Review new download or redirect destinations before allowing them. Installation success and basic readiness do not attest effective tool policy or prove an authenticated app operation. See the installation proof.

Create-time app-server exposure

For dedicated Codex, CreateSandbox includes one unnamed exposure for Compute's literal APP_SERVER_PORT. The UUID from the Agent revision ID is the first request_id. With no Sandbox, create retries after unresolved refusals use at most 16 request IDs. Adoption requires an exact Sandbox and, before enrollment, exposure. The client keeps a normalized control URL and the advertised workload URL, which harnessEndpoint returns as a WebSocket origin.

Compute supplies only APP_TOKEN_SHA, never the raw token; bearer passthrough forwards the header Codex, or a native held failure, authenticates. Other exposures keep OpenShell's authorization-stripping default. A Sandbox without a replayable Create receipt must be removed, not mutated by ExposeService.

Compute replaces the fail-closed Gateway target and omits its direct Agent Service and Harness route. Drivers without provider transport retain Kubernetes transport.

Compute reports native OpenClaw ready only after its Gateway carries the enrolled node identity and completes rollout. A native worker's node opens its Gateway connection. Its exposure serves only Compute's held-failure read before enrollment; OpenShell routes it unauthenticated, so once the node enrolls the Driver deletes it (DeleteService, fail closed); adoption or recreation has none. A missing service, Sandbox or credential attachment is gone only if GetWorkspace answers and a second read still misses it (OpenShell hides unauthorized Sandboxes as missing); a refusal fails with SANDBOX_GATEWAY_UNAUTHORIZED. The worker's sweep covers Agent revisions without a current reconciliation pass and failed candidates.

Harness observation

Dedicated Codex revisions using a credential_source with login mode codex_pat require authentication in the serving app-server before harnessStatus reports serving. The Driver initializes the exact bearer-authenticated WebSocket service, then calls getAuthStatus with includeToken: false and refreshToken: false. It requires authMethod: personalAccessToken, authToken: null and requiresOpenaiAuth: true. Missing, mismatched or malformed authentication stays starting under the existing readiness deadline. The earlier codex login status check alone does not establish authentication in this fresh process.

The check neither logs in nor refreshes credentials, and successful authentication is not model-inference proof. Other login modes retain their existing transport handshake. TLS verification, cancellation and held-startup-failure reporting remain in force; an unavailable WebSocket still permits the held-failure document read.

OpenShell reads the phase from GetSandbox. A completed phase maps to lost with HARNESS_EXITED. An error phase, including a deleted or evicted Pod, maps to lost with SANDBOX_FAILED. An unreadable record is unknown.

OpenShell normally sets restart_policy: ALWAYS. The repository Git path sets NEVER, and older Sandboxes can also retain NEVER. When the gateway reports a starting process with an exit code and a positive restart count, the Driver returns starting with HARNESS_RESTARTING. It maps the GetSandbox fields exit_code and restart_count to exitCode and restarts. On first startup the Driver returns plain starting. OCC diagnostics mark a restarting Harness as a failed sandbox check while the gateway attempts the restart.