[Feature]: Add first-class Docker / Docker Compose deployment support #3449

Area

Installation or packaging

What are you trying to accomplish?

Run OpenCodex as a self-contained containerized proxy/dashboard without installing OpenCodex globally on the host.

The intended deployment shape is:

Codex CLI / Codex App / Claude Code on host or remote clients
                    ↓
              localhost / LAN
                    ↓
        OpenCodex container (:10100)
                    ↓
       configured providers / account pools

OpenCodex already contains meaningful Docker-aware runtime behavior, and users are already running it under Docker, Docker Compose, k3s, and other external supervisors. However, there is no official Dockerfile, Compose example, published container image, or container-specific deployment guide.

Why this is worth making first-class

Existing issues show that Docker is already an intended/real deployment shape rather than an unsupported experiment:

• [Bug] Docker foreground start blocks native requests when systemd ownership is unprovable #1612 — Docker foreground startup was explicitly accepted and fixed; maintainers stated Docker users should run ocx start directly rather than use the service manager.
• [Bug][Linux] native-main 503 when systemctl exists but the user bus is unreachable (#1612 regression gap) #2114 — follow-up container/systemd regression handling for Docker/tini foreground environments.
• [Feature]: ChatGPT/Codex login via OpenAI deviceauth (device code) for headless/remote hubs #3366 — current headless/k3s deployment where OAuth onboarding is the remaining friction.
• [Roadmap] Centrally hosted multi-user OpenCodex with tenant isolation #95 — centralized/remote OpenCodex deployment roadmap, including non-loopback binding, authenticated data plane, reverse proxy/TLS, and remote clients.

Today operators have to reconstruct the container contract themselves: which process to run, which directories to persist, which ports to expose, how to handle non-loopback authentication, and which commands must not be used inside a container.

What should OpenCodex do?

Provide a small, supported container deployment surface.

At minimum:

1. Official Dockerfile or published image

   • Node 22 base (or another maintainer-selected supported base).
   • Run OpenCodex in foreground with ocx start.
   • Do not rely on systemd, launchd, Windows Task Scheduler, or ocx service inside the container.
   • Prefer a non-root runtime user.
   • Pin/package the same released OpenCodex version as the image tag.

2. Official compose.yaml example

   • Persistent OPENCODEX_HOME volume.
   • Port 10100 exposed to the host.
   • Example of host-only publication such as 127.0.0.1:10100:10100.
   • Clear example for hostname: "0.0.0.0" inside the container.
   • OPENCODEX_API_AUTH_TOKEN handling for non-loopback binds.
   • Restart policy managed by Docker/Compose instead of ocx service.

3. Health/readiness contract

   • Docker HEALTHCHECK example using /healthz or /readyz.
   • Document when /readyz should be used instead of liveness.

4. Persistent data contract

   • Document which state belongs under OPENCODEX_HOME and should be persisted.
   • Document optional CODEX_HOME / auth mounts when native ChatGPT/Codex credentials are used.
   • Prefer read-only credential mounts where possible.

5. OAuth/headless guidance

   • Document callback ports required by current OAuth flows.
   • Explain host port forwarding where needed.
   • Cross-reference [Feature]: ChatGPT/Codex login via OpenAI deviceauth (device code) for headless/remote hubs #3366 for device-code login / headless OpenAI auth when that lands.

6. Container lifecycle guidance

   • Explicitly document that ocx service is not used in Docker.
   • Explicitly document whether ocx codex-shim install is meaningful only when Codex itself runs in the same container.
   • Document how upgrades should work: pull/rebuild image + restart, rather than invoking an in-container self-update that mutates the running image.

Example interface

A minimal supported Compose deployment could look approximately like this (exact image/name/config are illustrative):

services:
  opencodex:
    image: ghcr.io/lidge-jun/opencodex:2.42.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:10100:10100"
    environment:
      OPENCODEX_HOME: /data
      OPENCODEX_API_AUTH_TOKEN: ${OPENCODEX_API_AUTH_TOKEN}
    volumes:
      - opencodex-data:/data

volumes:
  opencodex-data:

With container-side config:

{
  "port": 10100,
  "hostname": "0.0.0.0"
}

And a healthcheck along the lines of:

healthcheck:
  test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:10100/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
  interval: 30s
  timeout: 5s
  retries: 3

Alternatives or workarounds

Operators can already build a custom image by installing the npm package into a Node image and running ocx start, or clone the repository and run the Bun entrypoint directly. That works, but every operator has to rediscover the same details:

• foreground-only lifecycle;
• service manager is unsupported/unnecessary in Docker;
• persistent OPENCODEX_HOME;
• 0.0.0.0 bind + admission token;
• OAuth callback routing;
• native Codex auth mounts;
• container-safe upgrade behavior.

The runtime already contains Docker-specific handling, so documenting and packaging that contract would reduce duplicated deployment work and make existing Docker support easier to test continuously.

Scope / non-goals

This request does not require:

• Kubernetes operators or Helm charts;
• multi-tenant isolation ([Roadmap] Centrally hosted multi-user OpenCodex with tenant isolation #95 owns that larger architecture);
• weakening authentication for non-loopback binds;
• running systemd inside the container;
• bundling Codex CLI unless maintainers explicitly want a separate all-in-one image;
• solving every OAuth flow in this issue.

A minimal official image + Compose example + container deployment documentation would already close the main packaging gap.

Acceptance criteria

• An official Dockerfile or published container image exists.
• A documented Compose example persists OpenCodex state.
• The container runs ocx start directly and does not depend on a service manager.
• Non-loopback bind/auth requirements are documented and tested.
• /healthz and/or /readyz are wired into a documented container healthcheck.
• Upgrade guidance does not require mutating the running image in place.
• OAuth/headless callback considerations are documented.
• The supported container path has at least one CI smoke test.

Checks

• I searched existing issues and documentation.
• This request builds on existing Docker/runtime support rather than duplicating [Bug] Docker foreground start blocks native requests when systemd ownership is unprovable #1612 or [Bug][Linux] native-main 503 when systemctl exists but the user bus is unreachable (#1612 regression gap) #2114.
• I removed secrets and personal data.