Try free

Last updated 13 October 2026

Set SSL certs for Claude Code

SSL handshake errors block the connection

When you try to run the claude command for the first time in a corporate setting, you might see a wall of red text in your terminal. This usually happens during the initial handshake when the tool attempts to reach the secure servers at Anthropic. The error message often mentions a self-signed certificate in the chain or an inability to verify the first certificate. This is not a bug in the tool itself but a sign that your network environment is intercepting the connection to inspect the data for security reasons.

Corporate firewalls and transparent proxies act as a middleman between your computer and the internet. They present their own security certificates to your terminal instead of the certificates from the actual server. Because your local installation does not know to trust these specific corporate certificates, it terminates the connection to protect your data. You cannot skip this security check easily because the agent requires a secure and verified channel to transmit your code and receive instructions.

Identifying the corporate certificate authority

To fix this, you must identify which certificate is being injected into your connection. You can do this by attempting to visit the API endpoint in a standard web browser. Click the lock icon in the address bar and view the certificate hierarchy. You will likely see a root certificate named after your company or its security department. This is the root authority that your terminal needs to recognize as a trusted source for your encrypted traffic.

If you cannot find the certificate through your browser, you should contact your internal IT or security operations team. They usually provide a bundle of certificates for developers to use with command line tools and local development environments. Ask for the root CA certificate in a text-based format. Having the correct file is the most important step in resolving these connectivity issues without compromising the security of your workstation.

Exporting the root certificate to PEM format

Once you have identified the certificate in your system keychain or received it from IT, you need to save it in the PEM format. This format is a plain text file that contains a block of encoded data starting with a line that says begin certificate. If your certificate is currently in a binary format like DER or a container like PFX, you will need to convert it. Most systems have built-in tools to handle this conversion, or you can use standard cryptographic utilities available in your terminal.

Save this text block into a new file on your hard drive. A common practice is to create a directory named certs in your home folder to store these files. Ensure that the file name is simple and does not contain spaces, as this makes it easier to reference in your shell configuration. For example, you might name it corporate-ca.pem. This file will serve as the source of truth for your terminal whenever it needs to verify a connection through the corporate proxy.

Configuring the environment for the agent

After saving your PEM file, you must tell your terminal environment where to find it. Most tools that run in a terminal environment look for specific variables that define the path to extra CA certificates. You can test this by setting the variable in your current shell session. On macOS or Linux, you use the export command followed by the variable name and the full path to your PEM file. On Windows, the process involves using the set command or the environment variable editor in the system settings.

Once you have set the variable, run the claude command again. The agent should now be able to verify the certificate presented by your proxy because it can trace the trust back to the file you provided. If the session starts successfully and you see the interactive prompt, your configuration is correct. This temporary setting only lasts as long as your current terminal window stays open, so you will eventually need to make it permanent.

Making the certificate configuration persistent

To avoid setting the environment variable every time you restart your computer, you should add it to your shell profile. For users on macOS or Linux, this is typically a file like dot zshrc or dot bash-profile located in your home directory. Open this file with a text editor and add the export command at the end. This ensures that the variable is available in every new terminal window you open, allowing the agent to function without any manual setup.

Windows users can add the variable to their system or user environment variables through the control panel. This makes the setting global across the entire operating system. After saving these changes, you should restart your terminal application or your computer to ensure the new settings are active. You can verify that the variable is correctly set by using the command to print all environment variables and searching for the one you added.

Using the doctor command for verification

Claude Code includes a specific tool designed to diagnose environment issues. You can run claude doctor to perform a series of checks on your installation. This command will test your internet connection, verify your authentication status, and check if the agent can communicate with the necessary API endpoints. The output of this command will tell you explicitly if the SSL connection is working as expected.

If the doctor command reports a failure in the network section, it will often provide more details about why the connection failed. This is more useful than a generic error message because it helps you narrow down if the problem is a missing certificate, an incorrect path, or a secondary proxy issue. Use this output to refine your environment variables until all the network checks show a successful status. This ensures your development environment is stable before you start a long coding session.

Managing sessions with adhdTerminal

When you are working on multiple projects, managing different terminal windows for each agent session can become cluttered. This is where adhdTerminal becomes a useful tool for your workflow. adhdTerminal is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. It runs many Claude Code sessions side by side, where each one is a tile on a wall. A tile has a colour, a number and a name, and it shows whether it is working, waiting for you, done or idle.

Because adhdTerminal is a native application, it uses the environment variables you have configured on your system. This means that once you have set up your corporate SSL certificates, every tile in the app will inherit those settings. Tiles reopen in the same place after a restart and resume the same session, which preserves your workflow even after a reboot. It costs 99 dollars once, and one key runs one computer at a time and can be moved, with a 7 day free trial and no account.

Troubleshooting certificate chain issues

Sometimes a single root certificate is not enough to satisfy the security requirements of your proxy. Some proxies use an intermediate certificate that must also be trusted. If your connection still fails after pointing to your root certificate, try creating a combined PEM file. You can do this by opening your root certificate and your intermediate certificate in a text editor and pasting the contents of both into a single file. The agent will then have the full chain of trust it needs to verify the connection.

You should also check if you have any project-specific settings that might interfere. While files like CLAUDE.md are used for project instructions, settings like .claude/settings.json or .claude/settings.local.json hold your local configurations. Make sure you have not accidentally disabled network permissions or set a conflicting proxy configuration in these files. The agent respects your local overrides, so keeping your configuration clean is essential for a smooth experience.

Handling network changes and updates

Network environments are not static and your IT department might update the corporate proxy or change the certificates without notice. If you suddenly lose connectivity, run claude doctor again to see if the SSL verification is the culprit. You might also want to run claude update to ensure you have the latest improvements to the tool. A free iPhone app mirrors the wall of your adhdTerminal over an end to end encrypted link and can answer a prompt or send the next task, which is useful if you need to check on a task while away from your desk.

Maintaining your SSL setup is a one-time task that pays off in long-term productivity. By understanding how the agent interacts with your corporate infrastructure, you can resolve connection errors quickly and get back to writing code. Always keep a backup of your PEM file and documented notes on your environment variables. This preparation ensures that even if you move to a new computer or have to reinstall your tools, you can restore your working environment in a few minutes.

Questions people ask

Can I use the /config command to set SSL certificates?

The /config command allows you to view and modify settings within your session, but SSL certificates are typically handled at the environment level. You should set the necessary variables in your shell before starting the agent. This ensures the underlying network stack can establish a secure connection before the agent logic begins.

Does the agent respect the system certificate store on Windows?

The agent relies on its underlying runtime environment to manage connections. While some tools automatically use the Windows certificate store, many command line utilities require you to explicitly point to a PEM file using environment variables. Providing the path to your corporate CA certificate in your shell profile is the most reliable way to ensure connectivity.

What should I do if claude doctor shows a network error despite my changes?

Double check that the path to your certificate file is absolute and that the file is readable by your current user. You should also verify that the certificate is in the correct PEM format, which starts with a specific header line. If the error persists, check if your corporate proxy requires additional authentication steps like a username and password in the proxy string.

Read next

More on when it goes wrong·All posts