Skip to content

bug(examples): make Codex app-server setup runnable and image-safe #5875

Open

Description

@charlie-openai

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:

  1. Codex must initialize its SQLite schemas before the runtime Landlock boundary applies. Without that initialization, the app server does not become ready.
  2. Starting codex app-server during the image build with default features creates /sandbox/.codex/installation_id and synchronizes plugins under .codex/.tmp/plugins. Every derived sandbox then inherits one installation identity, and the transient plugin data materially increases the image.
  3. The example declares CODEX_AUTH_ACCOUNT_ID as a provider credential. OpenShell injects provider credentials as opaque handles, but Codex needs the actual, non-secret account ID for account routing.
  4. 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_id and 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

  1. Start a local Docker-backed OpenShell gateway.
  2. From examples/codex-app-server, build the image and import codex.yaml.
  3. Create the Codex provider from an existing host login and configure gateway-owned refresh.
  4. Create the sandbox with the example command and connect a host Codex client to the exposed URL.
  5. Observe that first-run database initialization and the provider/account/network configuration prevent a working model request.
  6. As a bootstrap workaround, run codex app-server for five seconds during the image build.
  7. Inspect /sandbox/.codex in the resulting image. It contains a shared installation_id and 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-server

The 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:triage-neededOpened without agent diagnostics and needs triage

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions