@nchappell/codex-web-ui 1.0.6 → 1.0.8

package/README.md

@@ -23,17 +23,18 @@ The app is a Next.js App Router application with Tailwind, shadcn/ui, and AI Ele
 ```bash
 npm install -g @nchappell/codex-web-ui
 codex-web-ui init
+codex-web-ui app-server start
 codex-web-ui doctor
 codex-web-ui
 ```
 
 Open `http://127.0.0.1:4545`.
 
-The normal startup command starts the Next.js server and starts or recovers a
-detached `codex app-server` sidecar on a Unix socket. Run `codex-web-ui doctor`
-after install or upgrade to check the production build, Codex CLI availability,
-login status, auth setup, writable data directories, permission settings, and
-app-server socket.
+The normal startup command starts only the Next.js server. The detached
+`codex app-server` sidecar must already be running and websocket-ready on the
+configured Unix socket. Run `codex-web-ui doctor` after install or upgrade to
+check the production build, Codex CLI availability, login status, auth setup,
+writable data directories, permission settings, and app-server socket.
 
 For source or git installs, run `codex-web-ui --build` once if the package does
 not include a `.next` production build.
@@ -81,8 +82,9 @@ npm run test:docker
 ```
 
 The Docker smoke builds `codex-web-ui:smoke`, starts it on port `4555` with a
-temporary data directory and `--external-app-server`, verifies `/threads`,
-`/api/auth`, and password login, then removes the container and temp volumes.
+temporary data directory, verifies `/threads`, `/api/auth`, and password login,
+then removes the container and temp volumes. The container entrypoint starts the
+sidecar before launching the web process.
 By default it builds with `@nchappell/codex-web-ui@<package.json version>` from
 npm. Set `CODEX_WEB_UI_DOCKER_NPM_SPEC=@nchappell/codex-web-ui@latest` or
 another npm package spec to test a different published package,
@@ -152,10 +154,10 @@ codex-web-ui \
   --data-dir "$PWD/data"
 ```
 
-The main command manages the app-server sidecar by default. If you already run
-the official app-server yourself, pass `--external-app-server` with
-`--app-server-socket`; in that mode startup only connects to the socket and does
-not attempt recovery.
+The main command does not manage the app-server sidecar. Start it explicitly
+with `codex-web-ui app-server start`, or run the official app-server yourself
+and point `--app-server-socket` at that Unix socket. Startup fails fast if the
+socket is not websocket-ready.
 
 Default permissions are intentionally conservative: `on-request` approval and
 `workspace-write` sandbox. `danger-full-access`, `on-failure`, and `never`
@@ -345,9 +347,10 @@ npm run app-server:recover
 npm run app-server:status
 ```
 
-`app-server:recover` treats a live PID without a connectable socket as
-degraded, restarts the sidecar, and waits until the Unix socket accepts
-connections. Use it when the UI reports `connect ENOENT ...codex-app-server.sock`.
+`app-server:recover` treats a live PID without a websocket-ready socket as
+degraded, restarts the sidecar, and waits until the Unix socket accepts the
+app-server WebSocket upgrade. Use it when the UI reports `connect ENOENT
+...codex-app-server.sock` or `Unix socket closed before WebSocket upgrade`.
 
 For MCP OAuth from a phone or another machine, Codex Web UI relays OAuth
 callbacks through the currently used Web UI origin. When an MCP OAuth login

package/bin/codex-web-ui.js

@@ -2,7 +2,7 @@
 
 import { spawn } from "node:child_process";
 import { accessSync, chmodSync, closeSync, constants as fsConstants, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -123,15 +123,21 @@ if (!existsSync(join(packageRoot, ".next", "BUILD_ID"))) {
 mkdirSync(dataDir, { recursive: true });
 mkdirSync(uploadDir, { recursive: true });
 
-if (!externalAppServer) {
-  await recoverAppServer(appServerControlOptions({ command: codexCommand, socket: appServerSocket }));
+if (!await isSocketWebSocketReady(appServerSocket, 1_000)) {
+  fail([
+    `Codex app-server socket is not ready: ${appServerSocket}`,
+    "Start it before launching the Web UI:",
+    `  codex-web-ui app-server start --socket ${appServerSocket}`,
+    "",
+    "If you run the official app-server yourself, make sure it listens on that Unix socket."
+  ].join("\n"));
 }
 
 console.log(`codex-web-ui listening on http://${host}:${port}`);
 console.log(`codex-web-ui app cwd: ${packageRoot}`);
 console.log(`codex default cwd: ${env.CODEX_CWD}`);
 console.log(`runtime data dir: ${env.CODEX_WEB_UI_DATA_DIR}`);
-console.log(`codex app-server socket: ${env.CODEX_APP_SERVER_SOCKET}${externalAppServer ? " (external)" : " (managed)"}`);
+console.log(`codex app-server socket: ${env.CODEX_APP_SERVER_SOCKET}`);
 console.log(`permissions: approval=${env.CODEX_WEB_UI_APPROVAL_POLICY}, sandbox=${env.CODEX_WEB_UI_SANDBOX}${env.CODEX_WEB_UI_LOCK_PERMISSIONS === "1" ? ", locked" : ""}${unsafePermissions ? ", unsafe enabled" : ""}`);
 if (configPath) {
   console.log(`config file: ${configPath}`);
@@ -373,11 +379,11 @@ async function runDoctorCommand(options) {
   }
 
   const socketPresent = existsSync(options.appServerSocket);
-  const socketConnectable = socketPresent ? await isSocketConnectable(options.appServerSocket, 500) : false;
+  const socketReady = socketPresent ? await isSocketWebSocketReady(options.appServerSocket, 500) : false;
   checks.push([
     "app-server socket",
-    `${options.appServerSocket}${socketConnectable ? " (connectable)" : socketPresent ? " (present, not connectable)" : " (missing)"}`,
-    options.externalAppServer ? socketConnectable : true
+    `${options.appServerSocket}${socketReady ? " (websocket ready)" : socketPresent ? " (present, not websocket-ready)" : " (missing)"}`,
+    socketReady
   ]);
 
   console.log("Codex Web UI doctor");
@@ -385,8 +391,8 @@ async function runDoctorCommand(options) {
     console.log(`${ok ? "ok  " : "fail"} ${name}: ${detail}`);
   }
   console.log("");
-  if (!socketConnectable && !options.externalAppServer) {
-    console.log("The main `codex-web-ui` command will try to start or recover the managed app-server sidecar.");
+  if (!socketReady) {
+    console.log("Start the sidecar first with `codex-web-ui app-server start`, then run `codex-web-ui`.");
   }
   if (!options.password && isLoopbackHost(options.host)) {
     console.log("No password is configured; `codex-web-ui` will print a temporary local password on each start.");
@@ -410,12 +416,12 @@ function appServerControlOptions({ command, logFile, pidFile, socket }) {
 async function startAppServer(options) {
   const existingPid = readPid(options.pidFile);
   if (existingPid && isPidRunning(existingPid)) {
-    if (await isSocketConnectable(options.socket, 750)) {
+    if (await isSocketWebSocketReady(options.socket, 750)) {
       console.log(`codex app-server already running: pid=${existingPid}`);
-      console.log(`socket: ${options.socket} (connectable)`);
+      console.log(`socket: ${options.socket} (websocket ready)`);
       return;
     }
-    console.warn(`codex app-server pid ${existingPid} is present, but the socket is not connectable; restarting`);
+    console.warn(`codex app-server pid ${existingPid} is present, but the socket is not websocket-ready; restarting`);
     await stopAppServer(options, { quiet: true });
   }
   mkdirSync(dirname(options.socket), { recursive: true });
@@ -442,7 +448,7 @@ async function startAppServer(options) {
     fail(`Timed out waiting for codex app-server socket: ${options.socket}. Check ${options.logFile}`);
   }
   console.log(`codex app-server started: pid=${child.pid}`);
-  console.log(`socket: ${options.socket} (connectable)`);
+  console.log(`socket: ${options.socket} (websocket ready)`);
   console.log(`log: ${options.logFile}`);
 }
 
@@ -473,9 +479,9 @@ async function stopAppServer(options, { quiet = false } = {}) {
 
 async function recoverAppServer(options) {
   const pid = readPid(options.pidFile);
-  if (pid && isPidRunning(pid) && await isSocketConnectable(options.socket, 750)) {
+  if (pid && isPidRunning(pid) && await isSocketWebSocketReady(options.socket, 750)) {
     console.log(`codex app-server healthy: pid=${pid}`);
-    console.log(`socket: ${options.socket} (connectable)`);
+    console.log(`socket: ${options.socket} (websocket ready)`);
     return;
   }
   await stopAppServer(options, { quiet: true });
@@ -487,8 +493,8 @@ async function printAppServerStatus(options) {
   const pid = readPid(options.pidFile);
   const running = Boolean(pid && isPidRunning(pid));
   const socketPresent = existsSync(options.socket);
-  const socketConnectable = socketPresent ? await isSocketConnectable(options.socket, 500) : false;
-  const state = running && socketConnectable
+  const socketReady = socketPresent ? await isSocketWebSocketReady(options.socket, 500) : false;
+  const state = running && socketReady
     ? "running"
     : running
       ? "degraded"
@@ -496,7 +502,7 @@ async function printAppServerStatus(options) {
         ? "stopped with stale socket"
         : "stopped";
   console.log(`codex app-server ${state}${pid ? `: pid=${pid}` : ""}`);
-  console.log(`socket: ${options.socket}${socketConnectable ? " (connectable)" : socketPresent ? " (present, not connectable)" : " (missing)"}`);
+  console.log(`socket: ${options.socket}${socketReady ? " (websocket ready)" : socketPresent ? " (present, not websocket-ready)" : " (missing)"}`);
   console.log(`pid file: ${options.pidFile}`);
   console.log(`log: ${options.logFile}`);
 }
@@ -546,7 +552,7 @@ function waitForSocket(socket, timeoutMs) {
   const startedAt = Date.now();
   return new Promise((resolve) => {
     const tick = async () => {
-      if (await isSocketConnectable(socket, 250)) {
+      if (await isSocketWebSocketReady(socket, 250)) {
         resolve(true);
         return;
       }
@@ -560,25 +566,56 @@ function waitForSocket(socket, timeoutMs) {
   });
 }
 
-function isSocketConnectable(socket, timeoutMs) {
+function isSocketWebSocketReady(socket, timeoutMs) {
   if (!existsSync(socket)) {
     return Promise.resolve(false);
   }
   return new Promise((resolve) => {
     const client = createConnection(socket);
-    const timer = setTimeout(() => {
+    const key = randomBytes(16).toString("base64");
+    const expectedAccept = createHash("sha1")
+      .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+      .digest("base64");
+    let buffer = Buffer.alloc(0);
+    let settled = false;
+    const settle = (ready) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
       client.destroy();
-      resolve(false);
-    }, timeoutMs);
+      resolve(ready);
+    };
+    const timer = setTimeout(() => settle(false), timeoutMs);
     client.once("connect", () => {
-      clearTimeout(timer);
-      client.end();
-      resolve(true);
+      client.write([
+        "GET / HTTP/1.1",
+        "Host: localhost",
+        "Upgrade: websocket",
+        "Connection: Upgrade",
+        `Sec-WebSocket-Key: ${key}`,
+        "Sec-WebSocket-Version: 13",
+        "",
+        ""
+      ].join("\r\n"));
     });
-    client.once("error", () => {
-      clearTimeout(timer);
-      resolve(false);
+    client.on("data", (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      const headerEnd = buffer.indexOf("\r\n\r\n");
+      if (headerEnd === -1) {
+        return;
+      }
+      const headerText = buffer.subarray(0, headerEnd).toString("utf8");
+      const lines = headerText.split("\r\n");
+      const headers = Object.fromEntries(lines.slice(1).map((line) => {
+        const index = line.indexOf(":");
+        return index === -1 ? ["", ""] : [line.slice(0, index).trim().toLowerCase(), line.slice(index + 1).trim()];
+      }).filter(([name]) => name));
+      settle(lines[0]?.startsWith("HTTP/1.1 101") && headers["sec-websocket-accept"] === expectedAccept);
     });
+    client.once("error", () => settle(false));
+    client.once("close", () => settle(false));
   });
 }
 
@@ -803,8 +840,8 @@ function printHelp() {
        codex-web-ui doctor [options]
        codex-web-ui app-server <start|stop|restart|recover|status> [options]
 
-Starts the Codex Web UI using Next.js production mode. By default this also
-starts or recovers a detached codex app-server sidecar.
+Starts the Codex Web UI using Next.js production mode. The codex app-server
+sidecar must already be running.
 
 Options:
   -c, --config <path>           JSON config file. Default search:
@@ -818,8 +855,8 @@ Options:
   --allowed-origins <csv>       Set CODEX_WEB_UI_ALLOWED_ORIGINS
   --app-server-socket <path>    Codex app-server Unix socket. Default:
                                 ~/.codex-webgui/codex-app-server.sock
-  --external-app-server         Use the socket but do not start/recover the
-                                app-server sidecar
+  --external-app-server         Deprecated no-op; app-server is always external
+                                to the web process
   --codex-command <command>     Codex command. Default: codex
   --cwd <path>                  Default Codex working directory
   --model <model>               Default Codex model. Default: gpt-5.5

package/bin/docker-entrypoint.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+
+codex-web-ui app-server start --socket "${CODEX_APP_SERVER_SOCKET:-/home/node/.codex-webgui/codex-app-server.sock}"
+exec codex-web-ui "$@"

package/client/src/App.tsx

@@ -85,7 +85,6 @@ import {
   logout,
   openEventStream,
   readReferencedFile,
-  recoverAppServer,
   reloadMcpServers,
   respondClientRequest,
   restartServer,
@@ -896,7 +895,6 @@ export default function App({ initialThreadId = null }: AppProps) {
           rateLimits={rateLimits}
           status={serverStatus}
           onClose={() => setStatusOpen(false)}
-          onRecover={recoverAppServerFromUi}
           onRefreshMcp={reloadMcpServerStatus}
           onLoginMcpServer={handleLoginMcpServer}
           statusRefreshing={statusRefreshing}
@@ -1002,17 +1000,6 @@ export default function App({ initialThreadId = null }: AppProps) {
     }
   }
 
-  async function recoverAppServerFromUi() {
-    try {
-      const result = await recoverAppServer();
-      setServerStatus(result.status);
-      showToast(result.output || "App server recovered");
-      await loadSessions();
-    } catch (error) {
-      showToast(error);
-    }
-  }
-
   async function refreshStatus() {
     setStatusRefreshing(true);
     try {
@@ -2563,7 +2550,6 @@ function StatusModal({
   statusRefreshing,
   onClose,
   onLoginMcpServer,
-  onRecover,
   onRefresh,
   onRefreshMcp,
   onSaveMcpServer
@@ -2576,7 +2562,6 @@ function StatusModal({
   statusRefreshing: boolean;
   onClose: () => void;
   onLoginMcpServer: (name: string) => Promise<string>;
-  onRecover: () => Promise<void>;
   onRefresh: () => Promise<void>;
   onRefreshMcp: () => Promise<void>;
   onSaveMcpServer: (input: { name: string; url: string }) => Promise<void>;
@@ -2703,11 +2688,8 @@ function StatusModal({
             </div>
           </section>
         )}
-        <p className="muted">Rate limits use the app-server account quota snapshot. Recover checks the sidecar PID and socket, then reconnects this UI.</p>
+        <p className="muted">Rate limits use the app-server account quota snapshot. Start or recover the sidecar from the CLI, then reconnect this UI.</p>
         <footer className="modal-actions">
-          <button className="secondary-button" type="button" onClick={() => void onRecover()}>
-            <RefreshCw size={16} /> Recover app-server
-          </button>
           <button className="primary-button" type="button" onClick={() => void onRefresh()} disabled={statusRefreshing}>
             <RefreshCw size={16} className={statusRefreshing ? "spin-icon" : ""} /> Refresh
           </button>

package/client/src/api.ts

@@ -29,11 +29,6 @@ export async function restartServer(): Promise<ServerStatus> {
   return body.status;
 }
 
-export async function recoverAppServer(): Promise<{ output: string; status: ServerStatus }> {
-  const body = await postJson<{ output: string; status: ServerStatus }>("/api/app-server/recover", {});
-  return body;
-}
-
 export async function rpc<T = unknown>(method: string, params: JsonValue = {}): Promise<T> {
   const body = await postJson<{ result: T }>("/api/rpc", { method, params });
   return body.result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nchappell/codex-web-ui",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "private": false,
   "description": "Mobile-friendly web UI client for the official Codex app-server.",
   "license": "MIT",
@@ -22,7 +22,8 @@
   ],
   "type": "module",
   "bin": {
-    "codex-web-ui": "bin/codex-web-ui.js"
+    "codex-web-ui": "bin/codex-web-ui.js",
+    "codex-web-ui-docker-entrypoint": "bin/docker-entrypoint.sh"
   },
   "publishConfig": {
     "access": "public"

package/server/appApi.ts

@@ -231,12 +231,6 @@ async function dispatchApiRequest(request: Request, url: URL, cors: Headers): Pr
     return json({ ok: true, status: bridge.summary() }, 200, cors);
   }
 
-  if (pathname === "/api/app-server/recover" && request.method === "POST") {
-    const output = await recoverAppServerSidecar();
-    await bridge.restart();
-    return json({ ok: true, output, status: bridge.summary() }, 200, cors);
-  }
-
   if (pathname === "/api/server/stop" && request.method === "POST") {
     await bridge.stop();
     return json({ ok: true, status: bridge.summary() }, 200, cors);
@@ -828,25 +822,6 @@ function json(payload: unknown, status = 200, cors?: Headers): Response {
   );
 }
 
-async function recoverAppServerSidecar(): Promise<string> {
-  const socket = process.env.CODEX_APP_SERVER_SOCKET;
-  if (!socket) {
-    throw new Error("CODEX_APP_SERVER_SOCKET is not configured; this server owns its app-server connection.");
-  }
-  const binPath = path.join(projectRoot, "bin", "codex-web-ui.js");
-  return new Promise((resolve, reject) => {
-    execFile(process.execPath, [binPath, "app-server", "recover", "--socket", socket], { cwd: projectRoot, env: process.env, timeout: 12_000 }, (error, stdout, stderr) => {
-      const output = [stdout, stderr].filter(Boolean).join("\n").trim();
-      if (error) {
-        const message = output || error.message;
-        reject(new Error(message));
-        return;
-      }
-      resolve(output);
-    });
-  });
-}
-
 function noStoreHeaders(): Headers {
   return new Headers({
     "Cache-Control": "no-store"