Webview Server Evaluation

Context

The current launcher starts a local python3 -m http.server "$CODEX_LINUX_WEBVIEW_PORT" process for the extracted webview bundle. It waits for the configured port to become reachable before launching Electron, and exports ELECTRON_RENDERER_URL so side-by-side app IDs can use an isolated local origin.

The extracted webview payload is a static bundle under codex-app/content/webview and is relatively large: about 35 MB across 693 files. The generated index.html references hashed assets through relative paths, so the app still expects a stable local origin.

Options

1. Keep Python and harden lifecycle handling

What changes:

• Keep python3 -m http.server "$CODEX_LINUX_WEBVIEW_PORT"
• Keep improving the current process lifecycle and readiness behavior
• Improve port-collision handling and logging

Benefits:

• Lowest implementation risk
• No packaging or runtime-binary changes
• Preserves the existing static-asset serving model

Risks:

• Python remains an external runtime dependency for the launcher path
• Startup reliability still depends on a separate process being spawned correctly
• Performance improvements are limited, because the server is still a generic Python HTTP server

2. Ship a tiny Rust static-file server

What changes:

• Replace the Python server with a small Rust binary that serves content/webview
• Bundle that binary with the Linux app or package it alongside the launcher
• Add deterministic startup, port selection, and readiness signaling

Benefits:

• Better control over startup behavior, logging, and shutdown
• Fewer runtime dependencies once the Rust binary is packaged
• More room for future optimizations around caching and path handling

Risks:

• Larger implementation and maintenance surface
• Requires packaging updates and a new build artifact
• Could duplicate functionality that the current app may only need in a very narrow way

3. Remove the local server entirely

What changes:

• Change the Electron/webview integration so the app can load the static bundle directly
• Eliminate the localhost origin requirement

Benefits:

• Simplest runtime model if it is truly feasible
• Removes a whole local-server process from the launcher path
• Best theoretical startup behavior

Risks:

• Highest product risk
• May require app-bundle changes outside this Linux repo
• Relative asset loading and origin-sensitive behavior could break in subtle ways

Recommendation

Keep Python for now, but harden the launcher lifecycle and readiness handling.

Why this wins:

• The current problem looks more like process orchestration than raw server throughput.
• The webview payload is static, so the launcher only needs a reliable local origin, not a high-performance application server.
• This path preserves compatibility while leaving the door open for a Rust server later if evidence shows Python is still a bottleneck.

Integration Points

If we later implement the recommended hardening or a Rust server, the change points are:

• install.sh launcher generation
• the local webview startup block around the configured webview port
• packaging if a Rust server binary is added
• launcher logging and cleanup logic around the PID file and http.server shutdown

Risks To Watch

• Port conflicts on the configured webview port
• Stale launcher/server processes after crashes
• Chromium waiting on a server that has not finished binding yet
• Hidden assumptions in the extracted app about a localhost origin

Acceptance Criteria For A Future Change

• Electron starts reliably when the launcher is invoked once
• A stale server process does not block a new launch
• The webview origin is available before Electron tries to load it
• Launcher logs clearly show server start, bind, and shutdown events
• The app still renders the same webview assets without broken relative paths

Future Test Plan

• Launcher smoke test for start/stop/restart behavior
• Port-collision test for the configured webview port
• Stale-process cleanup test
• Basic render test that verifies the webview assets are reachable from the expected origin