How to Fix Self-Signed SSL Certificate Errors in the Codex Desktop Browser on macOS

A practical workaround for accessing local HTTPS services, such as Unraid, through the built-in browser in OpenAI Codex.

The Problem

When working with local development environments, home servers, or self-hosted applications, HTTPS connections frequently rely on self-signed SSL certificates.

This is common with applications such as:

• Unraid
• Proxmox
• Home Assistant
• Local development servers
• Internal dashboards and administration interfaces

Most browsers, including Chrome, Safari, and Brave, allow users to acknowledge a certificate warning and proceed to the website.

However, the built-in browser in OpenAI’s Codex Desktop application behaves differently.

When attempting to access a local server using a self-signed certificate, such as:

https://hs0.local/

the browser may refuse to establish a connection, displaying an error similar to:

NET::ERR_CERT_AUTHORITY_INVALID

Unlike conventional browsers, Codex does not currently provide a documented way to bypass this warning through its browser interface.

This limitation is also documented in GitHub Issue #23891, which describes the absence of a certificate-warning bypass in Codex Desktop.

Why Does This Happen?

Self-signed certificates provide encryption, but they are not automatically trusted by operating systems or browsers.

HTTPS certificate validation generally involves three important checks:

1. Trust: The certificate must be issued by a trusted certificate authority or explicitly trusted by the system.
2. Hostname verification: The hostname must match one of the certificate’s Subject Alternative Names (SANs).
3. Validity: The certificate must be within its validity period and satisfy other security requirements.

When a self-signed certificate is used, the first requirement normally fails.

Traditional browsers often allow users to override that failure. Codex’s embedded browser currently lacks an equivalent visible option.

Fortunately, macOS provides a mechanism for explicitly trusting certificates.

Solution: Export the Certificate and Add It to macOS Keychain

The workaround involves retrieving the SSL certificate from the local server, configuring macOS to trust it, and opening the server using a hostname covered by the certificate. In my setup, that hostname is hs0.local. Replace it with the hostname listed in your own certificate.

Step 1: Verify the HTTPS Connection

First, open Terminal on macOS and execute:

curl -vk https://hs0.local/ -o /dev/null

The -k flag tells curl to skip certificate verification for this request.

This allows us to determine whether the server is reachable and whether the SSL handshake succeeds. Because -k skips verification, a successful response does not prove that the certificate is trusted or that its hostname matches.

Important: This command does not modify system settings or disable certificate validation globally.

Step 2: Export the Self-Signed Certificate

Next, retrieve the certificate from the local server.

Export the certificate using the hostname you intend to open in the browser:

openssl s_client -connect hs0.local:443 -servername hs0.local </dev/null | openssl x509 -outform PEM > "$HOME/Desktop/hs0.crt"

Let’s break down the command:

After successful execution, the certificate is available at:

~/Desktop/hs0.crt

The exported file contains the public certificate, not the server’s private key.

Note: This command exports the first certificate presented by the server. If the server uses a certificate issued by a private CA, installing the corresponding root CA certificate is generally preferable.

Step 3: Verify the Certificate

Before installing the certificate, inspect it:

openssl x509 -in "$HOME/Desktop/hs0.crt" -noout -subject -issuer -dates -fingerprint -sha256

This displays information about the certificate, including its issuer, expiration dates, and SHA-256 fingerprint.

Compare the fingerprint against the certificate configured on the server through a trusted administrative channel.

You can also inspect the certificate’s Subject Alternative Names:

openssl x509 -in "$HOME/Desktop/hs0.crt" -noout -ext subjectAltName

Use the hostname listed in the certificate. In this example, the certificate contains DNS:hs0.local, so open https://hs0.local/. Using https://hs0/ produces ERR_CERT_COMMON_NAME_INVALID, even after trusting the certificate. Adding trust does not fix a hostname mismatch.

Step 4: Import the Certificate into macOS Keychain

Once the certificate has been verified, it can be added to macOS.

1. Open Keychain Access using Spotlight.
2. Select the login keychain.
3. Import the hs0.crt certificate.
4. Double-click the imported certificate.
5. Expand the Trust section.
6. Change When using this certificate to Always Trust.
7. Close the dialog and authenticate if requested.

macOS supports explicitly overriding certificate trust policies through Keychain Access. Apple documents this mechanism in its official Keychain Access guide.

Only enable this setting for certificates whose identity and origin you have verified.

Step 5: Restart Codex Desktop and Open the Matching Hostname

After importing the certificate, quit Codex Desktop completely.

On macOS:

Cmd + Q

Restart the application and try opening:

https://hs0.local/

In my setup, this address opened successfully after the certificate had been trusted in the login keychain.

Certificate handling may vary across application versions. If access still fails, verify the certificate’s hostname, validity, and trust configuration.

Alternative: Use a Publicly Trusted Certificate

For long-term use, a publicly trusted SSL certificate is often the cleaner solution.

For example, Unraid supports certificates through its myunraid.net infrastructure.

These certificates can be provisioned under:

Settings → Management Access

Unlike self-signed certificates, the myunraid.net certificates are designed to be trusted by conventional browsers without manually installing a certificate on each client device.

The exact access URL differs from the local hostname and is provided by Unraid. Unraid Docs

This approach avoids manual certificate distribution and is particularly useful when multiple devices need access to the same server.

Security Considerations

There is an important distinction between trusting an individual self-signed certificate and disabling certificate verification entirely.

Trusting a specific certificate establishes an explicit trust relationship with that certificate.

Disabling certificate verification globally allows connections to servers whose identities cannot be validated, creating a significantly larger security risk.

For administration interfaces such as Unraid, which provide access to virtual machines, Docker containers, storage, and privileged system operations, global certificate verification bypasses should be avoided.

A properly configured trust relationship is preferable.

Conclusion

The Codex Desktop browser’s handling of self-signed SSL certificates presents a practical limitation for developers and system administrators working with local infrastructure.

Unlike Chrome or Safari, Codex currently lacks a visible option to accept a certificate warning and continue.

Two steps were necessary in my setup: explicitly trust the self-signed certificate in macOS Keychain Access, and use the hostname listed in that certificate.

The certificate covered hs0.local, so the working URL was:

https://hs0.local/

This allowed access without disabling TLS verification globally.

Related resources:

• GitHub: Codex Desktop certificate validation issue #23891
• Apple: Change certificate trust settings on macOS
• Unraid: Securing Your Connection