Wire MCP servers into Codex runtime sessions

.gitignore

@@ -4,5 +4,6 @@
 /config.yaml
 src/ui/out/
 src/ui/.next/
+src/ui/test-results/
 src/ui/mcp-admin-flow.mjs
 src/ui/composio-nav.mjs

AGENTS.md

@@ -15,6 +15,25 @@ The pre-commit hook keeps `model_prices_backup.json` in sync with the
 upstream litellm JSON on every commit. It warns and skips silently if
 the network is unavailable — it never blocks a commit.
 
+## codexgui production deployment
+
+For the deployed topology, initial server setup, PostgreSQL integration,
+future-release procedure, acceptance tests, and rollback steps, follow
+[`docs/engineering/codexgui-deployment.mdx`](./docs/engineering/codexgui-deployment.mdx).
+
+Treat the environment files and persistent-state paths named in that runbook as
+production data. Never commit their contents or replace stable encryption keys
+during a routine release.
+
+## Future upstream releases
+
+Before adopting a newer upstream release or commit, follow
+[`docs/engineering/upstream-release-reconciliation.md`](./docs/engineering/upstream-release-reconciliation.md).
+It inventories the downstream fixes and behavioral invariants that must be
+preserved, defines how to classify upstream equivalents, and lists the required
+code, database, runtime, MCP, browser, orchestration, artifact, delivery,
+deployment, and rollback validation.
+
 ## MCP integration invariants
 
 `mcp_server_ids` (in `AgentDraft`) is the **sole source of truth** for which

Dockerfile

@@ -16,19 +16,23 @@ RUN cargo build --release --bin lite
 
 FROM debian:bookworm-slim AS runtime
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
+    && apt-get install -y --no-install-recommends ca-certificates curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd --gid 10001 app \
+    && useradd --uid 10001 --gid 10001 --no-create-home --shell /usr/sbin/nologin app
 
 WORKDIR /app
 COPY --from=rust-builder /build/target/release/lite /usr/local/bin/lite
 COPY --from=ui-builder /build/src/ui/out /app/ui
 COPY config.yaml.example /app/config.yaml.example
 COPY deploy/render.config.yaml /app/deploy.config.yaml
+RUN chmod -R a=rX /app
 
 ENV HOST=0.0.0.0
 ENV PORT=4000
 ENV LITELLM_CONFIG=/app/deploy.config.yaml
 ENV LITELLM_UI_DIR=/app/ui
 
 EXPOSE 4000
+USER 10001:10001
 CMD ["lite", "serve"]

compose.yaml

@@ -13,9 +13,16 @@ x-runtime-registration: &runtime-registration
       until curl -fsS "$$LAP_URL/health" >/dev/null; do
         sleep 1
       done
-      until curl -fsS "$$RUNTIME_API_BASE/health" >/dev/null; do
-        sleep 1
-      done
+      runtime_health_url="$${RUNTIME_HEALTH_URL:-$$RUNTIME_API_BASE/health}"
+      if [ -n "$${RUNTIME_HEALTH_API_KEY:-}" ]; then
+        until curl -fsS -H "X-API-Key: $$RUNTIME_HEALTH_API_KEY" "$$runtime_health_url" >/dev/null; do
+          sleep 1
+        done
+      else
+        until curl -fsS "$$runtime_health_url" >/dev/null; do
+          sleep 1
+        done
+      fi
 
       create_payload=$$(printf '{"alias":"%s","api_spec":"%s","api_base":"%s","api_key":"%s"}' "$$RUNTIME_ALIAS" "$$RUNTIME_API_SPEC" "$$RUNTIME_API_BASE" "$$RUNTIME_API_KEY")
       update_payload=$$(printf '{"api_base":"%s","api_key":"%s"}' "$$RUNTIME_API_BASE" "$$RUNTIME_API_KEY")
@@ -84,6 +91,35 @@ services:
       - lap
       - opencode
 
+  codex:
+    profiles: ["codex"]
+    build: ./templates/codex
+    environment:
+      MODEL_BASE_URL: ${CODEX_MODEL_BASE_URL:-https://api.openai.com/v1}
+      MODEL_API_KEY: ${CODEX_MODEL_API_KEY:-}
+      DEFAULT_MODEL: ${CODEX_MODEL:-gpt-5.6-sol-high}
+      MODEL_MODELS: ${CODEX_MODELS:-gpt-5.6-sol-high}
+      RUNTIME_API_KEY: ${CODEX_RUNTIME_API_KEY:-local-codex-key}
+    volumes:
+      - codex-data:/data
+      - codex-home:/codex-home
+
+  register-codex:
+    <<: *runtime-registration
+    profiles: ["codex"]
+    environment:
+      LAP_URL: http://lap:4000
+      LAP_MASTER_KEY: ${LITELLM_MASTER_KEY:-sk-local}
+      RUNTIME_ALIAS: local-codex
+      RUNTIME_API_SPEC: claude_managed_agents
+      RUNTIME_API_BASE: http://codex:8080
+      RUNTIME_API_KEY: ${CODEX_RUNTIME_API_KEY:-local-codex-key}
+      RUNTIME_HEALTH_URL: http://codex:8080/control/health
+      RUNTIME_HEALTH_API_KEY: ${CODEX_RUNTIME_API_KEY:-local-codex-key}
+    depends_on:
+      - lap
+      - codex
+
   deepagents:
     profiles: ["deepagents"]
     build: ./templates/deepagents
@@ -172,3 +208,5 @@ volumes:
   deepagents-data:
   hermes-data:
   openclaw-data:
+  codex-data:
+  codex-home:

deploy/codexgui-operations.md

@@ -0,0 +1,60 @@
+# codexgui production operations
+
+The complete deployment, upgrade, acceptance, and rollback runbook is
+[`docs/engineering/codexgui-deployment.mdx`](../docs/engineering/codexgui-deployment.mdx).
+This file remains a compact command reference for operators already familiar
+with that runbook.
+
+This deployment uses the host PostgreSQL service, the external Docker network
+`edge`, and the environment files below:
+
+- `/etc/litellm-agent-control-plane/deploy.env`
+- `/etc/litellm-agent-control-plane/runtime.env`
+- `/var/lib/litellm-agent-control-plane/`
+
+The environment files must remain owned by root with mode `0600`. The Compose
+stack does not publish host ports; Caddy reaches the `lap` service through the
+`edge` network as `litellm-agent-control-plane:4000`.
+
+## Start and verify
+
+```bash
+systemctl start litellm-agent-control-plane.service
+systemctl is-active litellm-agent-control-plane.service
+
+for service in lap codex opencode deepagents hermes openclaw; do
+  docker inspect "litellm-agent-control-plane-${service}-1" \
+    --format '{{.Name}} {{.State.Health.Status}}'
+done
+```
+
+Each registration container must finish with exit code zero. A private edge
+network check can be made without publishing a port:
+
+```bash
+docker run --rm --network edge curlimages/curl:8.11.1 \
+  --fail --silent --show-error \
+  http://litellm-agent-control-plane:4000/health
+```
+
+## Back up before changes
+
+Back up the database, both environment files, the state directory, the Caddy
+configuration, and the current DNS record before a release. Store database and
+environment backups with mode `0600`.
+
+## Roll back
+
+1. Restore the previous Cloudflare DNS record from the pre-change API response.
+2. Restore the previous Caddy configuration. When the Caddyfile is a read-only
+   file bind mount, replacing the host file changes its inode; recreate only
+   the Caddy service so the container mounts the restored inode.
+3. Stop this stack with `systemctl stop litellm-agent-control-plane.service`.
+4. Restore the previous database and state snapshot if the rollback stays on
+   this host, or start the preserved source deployment if the release was a
+   cross-host migration.
+5. Verify public health, the session list, an existing session with assistant
+   messages, and one new Codex ChatGPT session.
+
+Do not remove the previous deployment, its tunnel, or its database until the
+rollback retention window has elapsed.