Repository navigation
Description
User Story
I use a local, Docker-backed OpenShell gateway to run the Codex app server from examples/codex-app-server. I followed the example and directly encountered startup, credential-routing, and network-policy failures. I need the example to produce a working sandbox without embedding shared identity or plugin state in the image.
Problem Statement
The Codex app-server example does not complete a clean setup with current Codex behavior:
- Codex must initialize its SQLite schemas before the runtime Landlock boundary applies. Without that initialization, the app server does not become ready.
- Starting
codex app-serverduring the image build with default features creates/sandbox/.codex/installation_idand synchronizes plugins under.codex/.tmp/plugins. Every derived sandbox then inherits one installation identity, and the transient plugin data materially increases the image. - The example declares
CODEX_AUTH_ACCOUNT_IDas a provider credential. OpenShell injects provider credentials as opaque handles, but Codex needs the actual, non-secret account ID for account routing. - The provider profile does not authorize the WebSocket endpoint at
chatgpt.com/backend-api/codex/responses, so model traffic cannot complete.
A five-second default app-server bootstrap left about 80 MiB under /sandbox/.codex in the tested image. Disabling plugins and removing build-only artifacts reduced that state to about 1.3 MiB.
Impact / Why This Matters
Following the example does not yield a usable Codex remote session. A straightforward bootstrap workaround also creates two packaging problems: cloned sandboxes share a Codex installation identity, and each image carries a large plugin cache that Codex can recreate at runtime.
Users should not need to weaken sandbox policy, expose refresh material, or accept process-wide state baked into the image to run the example.
Acceptance Criteria
- A clean build and setup starts the Codex app server and reaches the OpenShell service readiness endpoint.
- A host Codex client can connect through the exposed WebSocket URL and complete a model request.
- The image initializes the SQLite state required before Landlock applies.
- The image contains no
.codex/installation_idand no synchronized plugin cache. - Each sandbox generates its own installation ID at runtime.
- The non-secret account ID reaches Codex as its actual value, while access and refresh tokens retain the documented OpenShell credential boundaries.
- The provider profile authorizes only the WebSocket path required for Codex responses.
- The documented commands match the verified workflow.
Reproduction Steps
- Start a local Docker-backed OpenShell gateway.
- From
examples/codex-app-server, build the image and importcodex.yaml. - Create the Codex provider from an existing host login and configure gateway-owned refresh.
- Create the sandbox with the example command and connect a host Codex client to the exposed URL.
- Observe that first-run database initialization and the provider/account/network configuration prevent a working model request.
- As a bootstrap workaround, run
codex app-serverfor five seconds during the image build. - Inspect
/sandbox/.codexin the resulting image. It contains a sharedinstallation_idand synchronized plugin data under.tmp/plugins.
Environment
- OpenShell: 0.1.9
- Codex CLI in the image: 0.171.0
- Image base: Ubuntu 24.04
- Gateway runtime: local Docker
- Host: macOS
- Repository base commit:
438e07b23
Suggested UX
Keep the documented provider boundary explicit:
openshell provider create \
--name codex \
--type codex \
--credential CODEX_AUTH_ACCESS_TOKEN
env "CODEX_AUTH_ACCOUNT_ID=..." \
openshell sandbox create \
--name codex-app-server \
--from openshell/codex-app-server:local \
--provider codex \
--env-from CODEX_AUTH_ACCOUNT_ID \
--expose 4500 \
--detach \
-- start-codex-app-serverThe image build may initialize required database schemas, but build-only identity and plugin synchronization artifacts must not remain in the final image.
Verification Notes
The corrected local image was rebuilt without cache. It contained neither installation_id nor .codex/.tmp, used about 1.3 MiB for initialized Codex state, and produced a fresh runtime installation ID. A newly created OpenShell sandbox reached /readyz with HTTP 200.
Activity