Last updated 13 October 2026
Use Claude Code with a corporate proxy
The terminal connection problem
When you run the claude command inside a corporate network, the first thing you see is often an error message about a connection failure or a refused socket. This happens because your terminal is trying to reach the Anthropic API directly, but the network gateway blocks any traffic that does not pass through the official proxy server. This is a common security measure in large offices to prevent data from leaving the building without inspection. You might also see a message about a self-signed certificate in the certificate chain. This means the network is using a man-in-the-middle approach to scan your encrypted traffic for safety.
The agent depends on a stable internet connection to send your prompts and receive code suggestions. If the initial handshake fails, the interactive interface will not start, and you will be stuck at the command prompt. You need to tell the tool exactly how to navigate the internal network to reach the outside world. This involves setting up specific instructions that the underlying software can read before it tries to open a network socket. Once these are set, the agent can pass through the corporate gate and reach the models it needs to function.
Environment variables for proxy routing
To fix this, you must define environment variables that the tool checks whenever it makes a web request. The most important one is the HTTPS_PROXY variable, which points to the address of your corporate gateway. This address usually looks like a URL with a hostname and a port number, such as http://proxy.company.com:8080. You should set this in your current terminal session to see if it resolves the connection issue. If your company uses a script to configure these automatically, you may need to look inside that script to find the static address of the server.
You should also set the HTTP_PROXY variable to the same value for consistency. Some networks also require a NO_PROXY variable, which lists internal addresses that the tool should reach directly without going through the gateway. This is useful if you are using MCP servers that run on your local machine or on a private network segment. You should include localhost, 127.0.0.1, and your own internal project domains in this list. Without a proper NO_PROXY setting, the agent might try to send local traffic to the corporate gateway, which will result in a timeout or a routing error.
Handling SSL certificate verification
Even with the proxy address set, you will likely encounter SSL certificate errors. Corporate proxies replace the original website certificate with one signed by the company. Your terminal does not recognize this internal certificate as a valid authority by default. To solve this, you need to find the root certificate file provided by your IT department, which is usually a file ending in .pem or .crt. You then set an environment variable named NODE_EXTRA_CA_CERTS that points to the full path of this file on your hard drive. This tells the tool to trust your company certificate just as it trusts major global authorities.
If you cannot find the certificate file, you can sometimes export it from your web browser. Navigate to a site that is allowed by your proxy, click the lock icon in the address bar, and view the certificate details. Look for the top-level certificate in the hierarchy and export it as a Base64-encoded file. Once you have this file saved, update your environment variables to include the path to this file. This step is critical because the agent will refuse to communicate over an insecure or untrusted connection to protect your code and data. It ensures that the encrypted tunnel between your machine and the model is secure.
Persistent configuration in shell profiles
Manual settings disappear every time you close your terminal window. To make your proxy settings permanent, you should add them to your shell configuration file. For users on macOS or Linux using the Z-shell, this is usually a hidden file in your home directory named .zshrc. If you use Bash, look for .bash_profile or .bashrc instead. Open this file in a text editor and add export commands for HTTPS_PROXY, HTTP_PROXY, NO_PROXY, and NODE_EXTRA_CA_CERTS. The next time you open a terminal, these settings will be active by default and ready for the next session.
You should also verify that these settings do not conflict with your project-specific configurations. Claude Code reads settings from the .claude/settings.json file inside your repo and the ~/.claude/settings.json file in your home directory. While the proxy settings live at the system level, you can use the /config command inside a session to check if the agent sees the network correctly. If you move between a home network and an office network, you might want to create a small shell script to toggle these variables. This prevents the agent from trying to use a corporate proxy that is not reachable when you are working from home.
Verifying the setup with Claude Code tools
Once you have configured your variables, you should use the built-in diagnostic tools to verify the connection. Run the claude doctor command in your terminal. This tool performs a series of checks on your installation, including your network connectivity and your authentication status. It will tell you if it can reach the Anthropic servers and if the SSL handshake is successful. If the doctor command reports a network error, double-check the spelling of your environment variables and the path to your certificate file to ensure they are accessible.
The doctor command is the most efficient way to debug proxy issues because it isolates network problems from project-specific issues. If the doctor says the network is fine but a specific project fails, the problem might be in your CLAUDE.md file or your local settings. You can also use the /status command inside an active session to see the current state of the agent and its connection. This is helpful if the connection drops after the session has already started. Keeping your installation updated with the claude update command also ensures you have the latest fixes for complex network environments.
Managing sessions with adhdTerminal
Managing a single proxy-bound session is simple, but developers often work on multiple projects that each require their own context. This is where adhdTerminal is the honest answer for a busy developer. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, not affiliated with Anthropic. It runs many Claude Code sessions side by side, each one a tile on a wall. A tile has a colour, a number and a name, and shows the last exchanges of its conversation. Each tile inherits the environment variables of your system, so your proxy and SSL settings carry over to every project automatically.
A tile shows whether it is working, waiting for you, done or idle, which is very helpful when working through a restrictive firewall. Tiles reopen in the same place after a restart and resume the same session, saving you from reconfiguring your environment every time. If you need to step away, a free iPhone app mirrors the wall over an end to end encrypted link and can answer a prompt or send the next task. This ensures you can keep an eye on long-running tasks that might be slowed down by corporate network traffic. It costs 99 dollars once, with a 7 day free trial and no account required.
Proxy authentication with credentials
Some corporate proxies require a username and a password for every request. You can include these credentials directly in your proxy URL. The format follows the standard pattern of http://username:password@proxy.company.com:8080. Be aware that if your password contains special characters, you must URL-encode them. For example, an exclamation mark becomes %21 and an at-symbol becomes %40. This ensures the terminal correctly parses the credentials before sending them to the gateway so that authentication does not fail.
Storing passwords in plain text in your shell profile is a security risk. If your company allows it, try to use a local proxy tool like CNTLM. These tools run on your local machine and handle the complex NTLM authentication with the corporate gateway for you. You then point your HTTPS_PROXY variable to the local tool, which usually runs on a port like 3128. This setup is often more stable and keeps your corporate credentials out of your environment variables. It also helps with command line tools that do not support complex authentication schemes natively.
Troubleshooting tool specific failures
Sometimes the agent can reach the API, but the tools it uses fail to access the internet. For example, if the agent uses the WebFetch tool to read a documentation page, that request must also go through the proxy. Because the agent runs these tools in a sub-shell, they should inherit your exported environment variables. If you find that WebFetch or WebSearch are failing while the main chat works, check if your settings are exported correctly. A variable that is set but not exported to the environment will not be visible to the tools the agent runs.
You can check the permissions for these tools in your .claude/settings.json file. Under the permissions section, you can see if specific tools are allowed or denied. If you are in bypassPermissions mode, the agent will run these tools without asking, but they will still fail if the proxy is not configured. If a tool fails, you can use the /bug command to report the behavior or press Escape twice to go back to earlier messages and try a different approach. Ensuring your proxy settings are global to your user account is the best way to keep every tool working as expected.
Questions people ask
How do I check if my proxy settings are active?
Run the claude doctor command in your terminal. This tool will test your connection to the Anthropic API and report any issues with your network configuration or SSL certificates. It is the fastest way to confirm that your environment variables are set correctly.
What if my proxy uses a custom port?
Include the port number at the end of your proxy URL separated by a colon. For example, if your proxy is at 10.0.0.1 and uses port 8888, your HTTPS_PROXY variable should be http://10.0.0.1:8888. This tells the agent exactly which gateway to use for all traffic.
Can I use different proxies for different projects?
You can set project-specific environment variables by using a local shell script within the project folder. However, Claude Code primarily looks at the environment variables of the shell where it was launched. If you use adhdTerminal, each tile can be configured to run in a shell with its own specific network environment.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.