Desktop supports Simplified Chinese, Traditional Chinese (zh-TW), English, Japanese, Korean, German, and French. Change language in Settings; the selection persists and controls activity time formatting. Traditional Chinese uses dedicated catalogs. Tray menus follow the selected language, including background startup. Raw backend diagnostics remain English; file dialogs follow the operating system language.
For normal Windows or macOS personal use, WebCodex Desktop + the official OpenAI Secure Tunnel is the recommended path. WebCodex Desktop runs the local Server and Runner; you send coding requests from ChatGPT Web. You do not need a public WebCodex endpoint, reverse proxy, or ChatGPT OAuth configuration.
This guide covers the published Desktop artifact path, including v0.4.6 Windows
x64/arm64 setup .exe and macOS Intel/Apple Silicon .dmg files. For
version-specific commands and UI, use the v0.4.6 guide.
The current development unified NSIS/.pkg/.deb workflow is documented in
Unified installation and Deployment validation;
its pending native acceptance is separate from published Desktop artifacts.
Before starting, prepare:
- the real project directory that ChatGPT should use, preferably under version control;
- a ChatGPT Web account that shows Developer Mode and the Plugins page;
- access to the OpenAI Platform pages for creating a Tunnel and API key.
WebCodex can read and modify files and run commands inside registered project boundaries. Register only directories you intend to expose, review tool calls, and keep API keys, tokens, and other secrets out of prompts, screenshots, Git, issues, and shared logs.
- Install and open WebCodex Desktop. Download the Windows installer or DMG matching your machine's architecture from GitHub Releases. On macOS, use System Settings → Privacy & Security → Open Anyway if the current non-notarized build is blocked; do not disable Gatekeeper globally.
- Create the main node. Choose Create main node to configure separate Server and local Runner services. The initial repository is optional; skipping it keeps the Runner enabled. Wait for setup to finish and check both services. Join main node adds this computer’s Runner to an existing Server; see the device instructions.
- Create the OpenAI Tunnel credentials. Create a Tunnel on the OpenAI Tunnels page, record its exact Tunnel ID, and create an API key on the API keys page. Prefer a Restricted key with only the Tunnel permissions required, including Tunnels: Read and Tunnels: Use.
- Save the credentials in WebCodex Desktop. Open Connection → Tunnel connection settings, enter the Tunnel ID and API key, then select Save configuration. The API key is stored unencrypted in the current user's local application-data directory; do not share or commit that file.
- Set networking only when needed. Leave Settings → OpenAI Tunnel network on Automatic unless your environment requires Direct or a Custom HTTP proxy. After changing this setting, stop and restart the Tunnel; restarting WebCodex Desktop is not required.
- Start the Tunnel. Open Connection → OpenAI Secure Tunnel and select Start secure tunnel. Continue only after WebCodex Desktop reports OpenAI Secure Tunnel ready; waiting for ChatGPT.
- Add the plugin in ChatGPT Web. Open Security and login, enable Developer Mode, then open the Plugins page. Create a plugin using Tunnel, select the correct available Tunnel or use Use tunnel ID instead, choose No Auth, accept the custom MCP warning only if you trust this installation, select Create, and then Connect. Never paste the Tunnel API key into ChatGPT Web. If the Tunnel list looks stale, compare the complete ID with the OpenAI Tunnels page.
- Verify the complete path from ChatGPT Web. Send: “List the WebCodex projects, then list the top-level files in the project I just selected; report an empty directory as empty.” This real project read—not local green status alone—is the final proof that ChatGPT Web, the Tunnel, Server, Runner, and project authority are connected.
“OpenAI Secure Tunnel ready” proves only that the local Tunnel is ready for ChatGPT; WebCodex Desktop may continue to display “waiting for ChatGPT” even after the plugin is saved. Use the real project read in step 8 as the acceptance check. If a step fails, use the matching detailed section below; those sections retain operational and recovery details and are not ordered as a second setup checklist.
For everyday operation after setup, see Using Desktop. For CLI, an existing remote Server, production hosting, or advanced networking, use the Full Setup or Deployment guides.
Contributors who want to modify Desktop or build their own Windows/macOS package should use Desktop development and local packaging; the install guide below assumes a finished release artifact.
Download the matching Desktop artifact from the GitHub Releases page:
- Windows: use the installer matching your architecture, x64 or ARM64. Windows ARM64 Desktop is part of the v0.4.2+ release build path.
- macOS: use the DMG matching your Mac architecture, Intel or Apple Silicon.
macOS signing has three explicit modes: self-signed is the current persistent fallback for public releases and long-lived dogfood; developer-id uses Developer ID Application plus notarization/stapling when Apple credentials are available; adhoc is only for disposable CI/local verification and promises no TCC upgrade continuity. Keep the same self-signed certificate and private key across builds and upgrades. Recreating a certificate with the same name changes identity. Both Desktop (dev.webcodex.desktop) and bundled Runner (dev.webcodex.runner) use certificate-anchored designated requirements without binary cdhash. Final app/DMG verification runs after Tauri nested signing. This does not preserve grants from historical ad-hoc builds automatically: users may need to reauthorize the new persistent identity once. Self-signed distribution is not Apple notarized; use System Settings → Privacy & Security → Open Anyway if Gatekeeper requires it, without disabling Gatekeeper globally.
Launch WebCodex Desktop after installation.
Success looks like: the main WebCodex window opens without a missing package/runtime error.
If it fails: use Open Anyway for the Gatekeeper case above; if the packaged runtime is missing, reinstall the same Desktop version instead of manually assembling internal binaries.
Next: if you are following the complete quick start above, choose the real project before starting the Tunnel. The following sections provide detailed reference for each setup area.
Closing the main window hides WebCodex Desktop; it does not quit the application or stop the local runtime and Tunnel:
- On macOS, use the WebCodex menu-bar item to reopen the window.
- On Windows, use the WebCodex system-tray icon to reopen the window.
- Use Stop Desktop-owned runtime to stop the runtime, or Quit WebCodex to exit the application and stop Desktop-managed processes.
- Enable Settings → Background & startup → Launch WebCodex at login if you want WebCodex to start in the background when you sign in.
For navigation, keyboard shortcuts, Activity filters, and other controls used after setup, see Using Desktop.
Create a Tunnel in the OpenAI Platform and prepare an API key that can use that Tunnel:
The Tunnel name is up to you. Record the Tunnel ID. A Restricted API key with only the required Tunnels: Read and Tunnels: Use permissions is recommended.
Do not commit or share real API keys, WebCodex tokens, or authorization values.
Open Connections and add a ChatGPT connection. In a persistent local Environment:
- Enter a profile name and the exact Tunnel ID.
- Enter the authorized API key in the write-only password field.
- Choose Run with WebCodex Server (recommended), or choose Separate Tunnel service (advanced) only when an independent service lifecycle is required.
- Save the profile. Saving never restarts a working Server. Add any remaining profiles, then use the single explicit Restart Server action if Desktop reports that the saved runtime state has not been applied.
A Server-owned profile is written to the current EnvironmentStore and is loaded only when the Server starts. It never creates a standalone Tunnel service. A separate-service profile retains per-profile Start, Stop and Restart controls. Existing owners cannot be changed in the ordinary editor; use the explicit ownership-transfer flow after the previous owner is cleanly stopped and uninstalled.
Desktop never reads an API key back into the form. Leaving the key blank while editing retains the selected profile's saved key; a replacement is accepted only against the current profile revision. Keys remain unencrypted in an owner-private binding, so keep Environment data, support bundles, tickets, screenshots and backups appropriately protected.
Success looks like: each card shows its independent name, Tunnel ID, owner and readiness. Server-owned profiles additionally show their per-profile startup selection. A Server-owned profile may show Restart Server until the one explicit restart loads all pending profiles. Saving configuration and observing a live Tunnel are separate results.
For a persistent Environment, EnvironmentStore is canonical for both CLI and Desktop: tunnel.json stores the catalog and server/tunnels/<profile>/webcodex.env stores the private binding. A profile added by CLI appears on the Desktop Connections page, and a Desktop save is visible to CLI tunnel-status.
A historical Desktop secrets/tunnel-config.json is not a second writable catalog in persistent mode. It is checked only as a fail-closed identity reconciliation fence: matching profile/Tunnel identities are accepted, but a missing or different identity blocks mutation rather than silently overwriting, importing or deleting either side. Historical API-key bytes are not compared after authority transfer, because key rotation belongs only to the revision-fenced EnvironmentStore binding.
Legacy/non-persistent Desktop runtimes continue to use secrets/tunnel-config.json in the local application-data directory:
- macOS:
~/Library/Application Support/dev.webcodex.desktop/secrets/tunnel-config.json. - Windows:
%LOCALAPPDATA%\dev.webcodex.desktop\secrets\tunnel-config.json.
macOS/Unix writes are owner-only (0600); Windows inherits current-user application-data permissions. Saves use guarded atomic replacement and retain no old secret backup. Invalid, unreadable, symlinked or oversized files fail closed.
Without saved legacy/non-persistent configuration, Desktop can use its inherited process environment:
CONTROL_PLANE_TUNNEL_ID
CONTROL_PLANE_API_KEY
No additional OPENAI_ADMIN_KEY or OPENAI_API_KEY is needed. Environment variables are not a persistent multi-profile format and are never merged field-by-field with saved data. OpenAI Secure Tunnel uses the built-in native Rust client, so there is no separate tunnel-client download or installation. If startup fails, check connection health and the control-plane route; if WebCodex reports unconfirmed prior work, resolve that state before restarting the same Tunnel identity.
Windows users can set persistent variables for the current user. On macOS, Finder / Dock launches do not read ~/.zshrc; launch from a Terminal that has loaded the variables or configure the login session environment. After changing variables through this advanced path, use Quit WebCodex in the tray and launch it again. Closing the window only hides it and cannot refresh its process environment. Recheck configuration neither executes shell startup scripts nor reloads manually edited configuration files.
A first foreground launch with missing Desktop permissions opens an in-app explanation. Explicit request buttons use the native macOS permission APIs; Continue leaves permissions unchanged. Background/login launches do not steal focus. Settings → Computer Use permissions shows observed Desktop permissions and lets you recheck or open System Settings. It does not infer the actual Runner's authorization from Desktop's state.
For screenshots, window observation, keyboard or pointer control, grant the relevant permissions under System Settings → Privacy & Security to the process actually running WebCodex Runner/Desktop. These include Screen & System Audio Recording, and Accessibility for UI control. Restart the affected process when macOS requires it.
On first use, choose Create main node. You can select an initial repository or skip it and add one later; the local Runner is enabled in either case. Runner filesystem policy remains the access boundary, and Project registration never grants access outside that policy. Advanced retains Server-only, viewer-only and Quick Share; reopening setup preserves saved roles.
On Home, expand View runtime diagnostics and confirm:
- Service: Running / Ready;
- Runner: Connected / Ready;
- Project: Ready with the selected directory, if you chose an initial Project. An empty Project list does not stop Server or Runner.
To add a repository later, open Projects → Add local project. The existing Runner identity and Server connection are reused.
Success looks like: Server and local Runner are ready. When a Project has been registered, check its exact path and owning Runner. A real project read from ChatGPT still verifies the full connection separately.
If it fails: use Activate project again. If it still fails, inspect the error and Activity details. Do not broaden project access to work around the error.
Next: start the OpenAI Secure Tunnel only after these three are ready.
Most users should leave Settings → OpenAI Tunnel network on Automatic and continue to step 6. Change it only when your environment requires a proxy or Tunnel startup reports a network error:
- Automatic (recommended): use the proxy inherited by Desktop; Windows can also detect the system proxy.
- Direct: do not use a proxy.
- Custom HTTP proxy: for example
http://127.0.0.1:7890.
If the Tunnel is already running, stop it, save the new network setting, and start it again. You do not need to restart Desktop; each Tunnel start reads the current setting.
If the error continues, inspect the Tunnel error and Activity details. Do not change project access or Runner configuration to work around a network error.
After saving any required change, continue to step 6.
Start automatically in each connection controls restoration when Desktop opens. For a Desktop-managed local Runtime, enabled connections with autostart resume after Runtime becomes ready, including when Runtime autostart is off but Runtime is already running. Stop disables that connection, so reopening does not restart it. Persistent environments delegate Tunnel lifecycle to system services; opening Desktop observes their actual status without restarting stopped services.
Open Connection, select OpenAI Secure Tunnel, then click Start secure tunnel. Selection alone does not start or stop processes. If an existing tunnel reports an error, stop it before starting again; failures remain visible with a retry path. When local handoff is ready, Desktop should show wording such as:
OpenAI Secure Tunnel ready; waiting for ChatGPT
Desktop copies the Tunnel ID to the clipboard when the operating system allows it.
Desktop must not promote daemon readiness or a successful clipboard copy to “ChatGPT connected” or “Ready to use”. Those facts prove only that the Tunnel is ready for ChatGPT.
Success looks like: the Tunnel itself is locally ready while the overall presentation still makes clear that ChatGPT connection/final verification is pending.
If it fails: first confirm that both configuration-presence fields from step 3 are Detected, then check the proxy mode in step 5 and use the on-screen Tunnel recovery action.
Next: enter the Tunnel ID in ChatGPT Web.
All ChatGPT setup in this section is performed in ChatGPT Web. "Desktop" throughout this guide refers to WebCodex Desktop, not a ChatGPT desktop application.
- Open ChatGPT Web account security settings.
- Under Account security and sign-in, enable Developer Mode. Review the warning shown by ChatGPT before enabling it; Developer Mode permits adding connectors that may make permanent changes or delete data.
- Open the ChatGPT Plugins page.
- Create a new plugin, then choose Tunnel as the connection method.
- Under Available tunnels, select the Tunnel configured for WebCodex. To use a specific ID, choose Use tunnel ID instead and enter the current Tunnel ID from WebCodex Desktop/OpenAI. Verify the ID if the available list appears stale or shows a similarly named Tunnel.
- Set Authentication to No Auth / None / No authentication.
- Read the custom MCP server warning and select I understand and want to continue only if you trust this WebCodex installation.
- Select Create.
- On the Add … to ChatGPT confirmation screen, select Connect.
You do not configure OAuth in ChatGPT Web for this path. WebCodex keeps the MCP authorization credential locally and the Tunnel client injects it; ChatGPT Web does not need the local credential.
After saving the connector in ChatGPT Web, return to WebCodex Desktop. Saving a connector in ChatGPT Web does not magically upgrade local Tunnel evidence into an authoritative “connected” signal. If this WebCodex Desktop version has no stable external-MCP-client observation signal, it intentionally continues to say that it is waiting for ChatGPT.
Success looks like: the ChatGPT Web connector is saved and the WebCodex Desktop Tunnel remains running.
If it fails: verify that you selected or entered the current Tunnel ID, not the API key; Authentication should be No Auth / None / No authentication. If the Tunnel is missing or rejected, verify that it is associated with the target ChatGPT workspace and that your OpenAI Platform identity has Tunnels: Read + Use for that Tunnel; Developer Mode and Tunnel permissions are separate. If the available Tunnel list merely looks stale, compare the exact ID with the OpenAI Tunnels page or use Use tunnel ID instead. Do not paste the Tunnel API key into ChatGPT Web.
Next: immediately perform one real project read.
After connecting, start with one minimal real project read, for example: “List the WebCodex projects, then list the top-level files in the project I just selected; report an empty directory as empty.” If it succeeds, the basic ChatGPT Web → Tunnel → Server → Runner → Project path is working.
The following checks are optional and exercise additional capabilities:
- list the WebCodex projects;
- read a file from the project you explicitly added;
- create, read back, and remove one temporary file inside that project;
- run a read-only command such as
git status,uname -a, orver; - if you enabled Computer Use, list windows or capture a browser window.
Run only the checks you need and understand, especially those that modify files or use Computer Use.
If Desktop shows a healthy Service / Runner / Project / Tunnel but ChatGPT still cannot list projects or read a file, do not treat local green status as proof of an external connection. Recheck the Tunnel ID and ChatGPT connection configuration, then inspect Desktop Connection / Activity for the latest state.
OpenAI Secure Tunnel is disabled: check Desktop's OpenAI Tunnel configuration diagnostics, which identify a missing Tunnel ID or API key. Recheck configuration observes the current process only; if using environment fallback, fully quit and reopen WebCodex after changing variables.
macOS Terminal sees the values but Desktop does not: Finder/Dock apps do not load ~/.zshrc; use the Terminal-launch or launchctl setenv path above. Desktop Recheck does not execute shell startup scripts.
Tunnel startup or ChatGPT connection times out: check Settings → OpenAI Tunnel network first, then stop and restart the Tunnel after changing the proxy mode.
A repository is not accessible: add that directory explicitly on the Projects page instead of broadening the default Desktop project's filesystem authority.
You see project_not_loaded / Project not ready: use Activate project again. Desktop retries the same project and manages only its own Runner; normal users do not need to edit or understand the internal project registry.
I closed the window and reopened it, but new environment variables are still missing: since the background-lifecycle change, closing the window hides Desktop in the tray/menu bar. Use Quit WebCodex there, then start a new process.
Use Settings → Runtime to inspect an extracted official archive or native source build, then explicitly activate it. Do not edit the app bundle. See Runtime compatibility and diagnostics; unknown/missing Custom files do not silently fall back to bundled binaries.
This detailed walkthrough documents the existing release-specific Desktop + OpenAI Tunnel path. For the unified package under development, use Unified installation; the new package is not yet published or fully accepted across native platforms.