How to Install a Codex Theme on Windows

This guide is based on the current Windows documentation referenced by the Codex Theme Hub repository, last checked July 17, 2026. Codex Dream Skin is an independent third-party project. It is not made or endorsed by OpenAI, and Codex Theme Hub is not the project maintainer.

The Windows implementation currently uses a local loopback Chrome DevTools Protocol (CDP) connection to add an external theme behind the native Codex interface. The upstream project says it does not take ownership of WindowsApps, rewrite app.asar, modify the official install directory, or change the app signature. You should still review the scripts and understand the local debugging boundary before running them.

Check the Windows requirements

The current upstream Windows README lists three requirements:

The official OpenAI.Codex application installed from Microsoft Store and registered to your current Windows user.
Node.js 22 or later, with node.exe available on PATH.
Windows PowerShell 5.1 or later.

Installation must run while Codex is fully closed. The project says ordinary use does not require administrator privileges and does not require ownership of the protected WindowsApps directory. If a repackaged guide asks you to run as Administrator or change WindowsApps permissions, stop and compare it with the original documentation.

Check Node.js in a new PowerShell window:

node --version

The returned major version must be 22 or higher according to the current project documentation. If PowerShell cannot find node, install Node.js from its primary source, reopen PowerShell so PATH refreshes, and run the check again. Do not download a renamed node.exe from a theme archive.

You can confirm that the official Store package is registered with the exact upstream troubleshooting command:

Get-AppxPackage -Name OpenAI.Codex

An empty result means the installer will not find the supported package. Install or repair the official Store app and open it normally before continuing. The scripts intentionally reject arbitrary executable paths.

Download the original source

Go to the Codex Theme Hub GitHub repository and follow its maintained source links. Use Code → Download ZIP only when the repository instructions direct you to download that repository. Do not use a third-party mirror, shortened download URL, repackaged PowerShell bundle, or file attached to an unrelated issue.

Extract the archive to a normal user-owned folder. Keep the whole repository structure intact. Open the windows directory and review README.md, the scripts you will run, and recent commits after this page’s last-checked date. PowerShell can make significant changes on behalf of your user account even when it is not elevated, so source review is part of installation—not an optional extra.

Close every Codex window before the next step. Check Task Manager if the installer reports that Codex is still running; do not force-close an unidentified process simply because it uses a port.

Understand the execution-policy argument

The original Windows instructions currently call powershell.exe with -NoProfile and -ExecutionPolicy Bypass for the specific script process. This does not permanently change the machine-wide execution policy. It tells that one PowerShell process to run the reviewed local script without loading your profile.

Bypass is not a safety guarantee and should never be applied to an unknown script. Review the exact repository content first, keep the source path visible, and use the command only from inside the original windows directory.

Run the installer

In PowerShell, change into the extracted repository’s windows directory. Then run the current documented command:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-dream-skin.ps1

The installer currently validates the official Store package and Node.js, saves a restorable appearance configuration, prepares a local theme library, and installs a self-contained managed runtime under the user’s local application data. Recent upstream work explicitly moved Windows runtime assets into a managed engine directory so the source checkout can later be moved or removed without breaking shortcuts.

The current installer creates shortcuts named:

Codex Dream Skin — start or reapply the skin.
Codex Dream Skin - Tray — open system-tray theme controls.
Codex Dream Skin - Restore — restore the official appearance and close the saved CDP session.

The upstream script also supports a custom port between 1024 and 65535. Most users should keep the default automatic behavior. If you have a documented conflict and understand why a fixed port is necessary, the current example is:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-dream-skin.ps1 -Port 9444

Do not choose a port by terminating an unknown listener. Without an explicit port, the current start script begins at its default and looks for an available local port.

Start the theme session

Use the Codex Dream Skin shortcut created by the installer. When it discovers that Codex is already running, the current flow asks whether to restart it. Restarting through the managed shortcut matters because a normal Codex launch does not enable the local debugging session required by the theme.

The command-line equivalent documented by the project is:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-dream-skin.ps1 -PromptRestart

Run that command from the original windows directory when using repository scripts directly. After installation, the shortcut points to the managed runtime, which is the easier and less path-sensitive option.

Import and save a background

Open Codex Dream Skin - Tray. The current tray interface can change the background, save the current theme, switch between saved themes, pause or continue the visual layer, reapply it, and restore Codex.

The upstream Windows image importer currently accepts PNG, JPEG, and WebP. Its limits are 16 MB, 16,384 pixels per side, and 50 megapixels. Use pure background artwork only. Do not import a screenshot that contains window chrome, sidebar labels, buttons, a prompt box, readable text, a logo, or a watermark. Duplicate interface elements can be confusing and make accessibility testing unreliable.

A wide 2560 × 1440 image is a practical starting point. Put the focal subject away from the left navigation area, preserve calm space behind the center content, and check the image at several window sizes. You can use our browser-only preview to test cover, contain, position, overlay, and panel opacity before importing the file.

Verify the installation

The original project includes a verification script. From the windows directory, run:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-dream-skin.ps1 `
  -ScreenshotPath "$env:TEMP\codex-dream-skin.png"

According to the current README, verification checks that the CDP endpoint is bound only to the loopback address and belongs to the official Codex package, the expected skin version is loaded, native sidebar and composer elements remain present, the decorative layer does not intercept pointer events, and the themed home structure is active when you are on the home route.

Open the generated screenshot yourself. Check horizontal overflow, text contrast, focus visibility, and cropping. Then test the live app: open the project menu, navigate between the home view and a task, type into the prompt composer without sending sensitive content, and confirm native controls respond normally.

Restore the official appearance

Use the Codex Dream Skin - Restore shortcut, or run the current documented restore command from the windows directory:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\restore-dream-skin.ps1 `
  -RestoreBaseTheme -PromptRestart

To restore and remove the shortcuts created by Dream Skin, the current command adds -Uninstall:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\restore-dream-skin.ps1 `
  -RestoreBaseTheme -PromptRestart -Uninstall

The upstream project documents -RecoverConfigBackup as an exceptional recovery option for a damaged configuration when normal -RestoreBaseTheme is insufficient. It saves the current configuration first. Do not use it as a routine uninstall flag; review the latest repository explanation before recovering a full backup.

After restore, launch Codex normally from the Start menu or its official entry. Confirm that the standard home view, title bar, sidebar, tasks, and composer have returned. If not, keep the logs and use the restore guide rather than deleting local application data indiscriminately.

Common PowerShell and runtime errors

`node` is not recognized

Run node --version. Install or update the supported runtime and open a fresh PowerShell window. The current project requires Node.js 22 or newer on PATH.

The official Codex package is not found

Run Get-AppxPackage -Name OpenAI.Codex. The script accepts the registered Store package and does not launch arbitrary executables. Repair or reinstall through the official distribution path.

The installer asks you to close Codex

Close all official Codex windows and allow the app to exit. Installation preserves and updates configuration, so the project requires a stable closed state.

The selected port is busy

Remove the explicit -Port option and let the current start script find an available port, or choose another known free port. Do not terminate an unidentified process just to reclaim a number.

Verification cannot find CDP

Start Codex through Codex Dream Skin, not the normal app shortcut, and rerun verification. A standard app launch does not open the theme’s debugging session.

A Codex update breaks the skin

Restore first, confirm the official app works, and then check the upstream repository for a compatibility change. Re-run the installer only after reviewing the latest scripts and open issues.

You need help from the maintainer

Use the Codex Theme Hub issue chooser. Include Windows version, Codex source and version, Dream Skin commit or version, installation method, exact error, sanitized logs, and reproduction steps. Remove API keys, auth.json, relay tokens, private paths when unnecessary, and conversation content. Our support page provides a structured report template.

Keep installation, verification, and restoration as one documented workflow. A theme is much easier to evaluate when the default path remains tested and visible.