Skip to contentHow to Use a Proxy with GitHub Codespaces for a Restricted Network
A GitHub Codespace runs its development container in a hosted environment, while the browser displaying it runs on your own device. That distinction matters: configuring a proxy inside the container can route package downloads from the Codespace, but it does not automatically change how your local browser reaches websites.
If a dependency install fails behind a corporate firewall, start by finding out which connection is blocked. The answer determines where the proxy must be configured and what your organization needs to allow.
1. Identify which Codespaces traffic needs the proxy
List the specific operation that fails. Installing a Python package with pip, fetching a Node.js dependency with npm, and downloading a command-line tool from a terminal are requests made by software in the development container. A browser tab opened on your laptop, by contrast, uses your laptop’s network path.
This difference can save time. If a website fails to load in your local browser, adding HTTPS_PROXY to the Codespace may have no effect. If npm install fails in the Codespace terminal, a proxy configured only on your laptop may not help either.
Write down the failing tool, the destination it tries to reach, and whether the request comes from the terminal, an editor extension, or your local browser. For example, a failure from pip install points to container traffic; a failed sign-in page in your local browser points to the local network or browser configuration.
Keep the scope narrow. Routing all traffic through a proxy when only one package registry is blocked can create unnecessary failures, particularly if internal services should remain directly reachable.
2. Check what your organization’s proxy allows
Ask your network administrator for the proxy hostname and port, the required protocol, and the authentication method. Also ask whether the proxy expects a username and password, a client certificate, or a certificate authority installed in the container. Do not guess these details from a proxy setting used on another device.
Request the permitted destinations for the exact task. A package manager may need access to a registry, while a tool installer may download from a separate release host. Your administrator can confirm which hostnames are allowed; record them before troubleshooting so you can distinguish a blocked destination from a bad proxy address.
Check whether HTTPS inspection is enabled. With inspection, the proxy may present certificates issued by your organization rather than the public certificate authority a tool expects. The organization’s certificate and approved installation process should come from the administrator, not from a certificate copied out of an error message.
If you are comparing proxy types or setting up access for other tools, the proxy authentication best practices guide covers safe handling of credentials. For a broader decision about network routing, see how to choose a VPN; a VPN and a proxy do not configure Codespaces in the same way.
3. Configure proxy variables for the development container
Many command-line tools read the environment variables HTTP_PROXY and HTTPS_PROXY. Set them in the Codespace’s development-container environment, using the address format your administrator supplied. A typical value has the shape http://proxy.example.net:8080, but use your organization’s actual protocol, hostname, and port.
Set NO_PROXY for destinations that should bypass the proxy, such as approved internal services or local addresses. The exact entries depend on your network and tools. A value that is too broad can send internal requests outside the intended path; one that is too narrow can leave a request trying to reach a blocked destination directly.
For a quick, temporary test, you can set variables in a terminal session before running a command. This is useful for checking whether a package install works, but it is not a reliable way to configure every terminal or future Codespace session. Shell syntax also varies; avoid pasting a credential-bearing proxy URL into a command that may be saved in shell history.
For repeatable project setup, put non-secret settings in the development-container configuration used by the repository, such as an appropriate Dev Container configuration or setup script. Keep passwords and tokens out of tracked files. If you need a credential, use an approved secret-injection method that your organization supports, and confirm which processes can read it.
Do not assume that every application follows these variables. Some tools read lowercase variants, some use their own configuration files, and others ignore environment variables. Test the particular command that failed rather than treating the presence of HTTPS_PROXY as proof that all Codespace traffic is routed.
4. Make proxy settings persist across Codespace rebuilds
A setting entered in one terminal can disappear when the terminal closes or the Codespace is rebuilt. To keep project-required, non-sensitive settings available, use a repository-level configuration that is created as part of the development container. A teammate opening the same project can then receive the same basic setup without copying a private credential into the repository.
Personal settings may be more appropriate when the proxy applies only to your account or when the value is sensitive. Check your organization’s Codespaces policies and available settings before choosing this route: an administrator may restrict personal configuration, secrets, or the use of particular development-container features.
After changing configuration, rebuild the Codespace if the change affects how the container is created, then open a fresh terminal and check the variables. A rebuild is a useful test: if the proxy setting vanishes afterward, it was probably added only to the previous shell rather than to a persistent configuration source.
Separate shared configuration from secrets. A repository can document the proxy variable names and expected format, but a real password should be supplied through an approved secret mechanism. That keeps a routine commit from exposing credentials to everyone who can read the project history.
5. Trust the proxy’s certificate when required
If HTTPS requests fail with a certificate verification error and your organization confirms HTTPS inspection, the container may need to trust the organization’s certificate authority. Obtain the official certificate and installation instructions from the administrator. Never disable certificate checks as a workaround; that can conceal an interception problem rather than fix it.
The installation procedure depends on the container’s operating system and base image. A Debian-based image, an Alpine-based image, and a language-specific image may handle certificate bundles differently. Also confirm whether the certificate must be added during container creation so it remains available after a rebuild.
Once installed, test a normal HTTPS request to an approved destination with the same tool that originally failed. If the browser works but a command-line client still reports an untrusted issuer, that client may use a separate certificate store or require its own setting. Ask your administrator which certificate file and format the container should use before changing trust configuration.
6. Test Git and development tools separately
Start with one harmless request to a destination your administrator has approved. Then test the failing package manager or tool. A successful request from one command does not prove that Git, pip, npm, and a language-specific installer all share the same proxy behavior.
For Git, inspect whether the installed version reads the proxy environment variables in your setup. If it does not, Git may require its own proxy configuration. Avoid putting a password directly into a Git configuration file that could be committed or copied into logs; use an organization-approved credential method instead.
For package managers, check both the proxy setting and the configured registry. A package manager pointed at an internal registry may not need the same external destination as a direct download, while a tool fetching a release archive may contact another host entirely. Compare the error’s destination with the allowlist you received.
Record which test passed, which failed, and the hostname involved. That short record gives your administrator something actionable—such as “Git reaches the approved host, but the package registry returns a proxy denial”—rather than the vague report that Codespaces has no internet.
7. Diagnose connection failures without exposing credentials
Use a harmless connectivity test against an approved destination, and inspect whether the result points to DNS resolution, a timeout, proxy authentication, a denied destination, or certificate validation. Each failure suggests a different next step. A timeout, for example, is not the same as an authentication rejection.
Check that the proxy hostname and port match the values your administrator supplied, and confirm that the variable is present in the same terminal session where you run the test. If the proxy requires authentication, a missing or expired credential can prevent access even when the address is correct.
Before sharing terminal output, remove usernames, passwords, tokens, and credential-bearing URLs. Proxy errors can include the full request address, and shell history can retain commands that contain secrets. Share the error type, destination hostname, tool name, and time of failure instead; those details often give network support enough to check its logs.
If the proxy works in one Codespace but not another, compare their container configuration, operating-system image, environment variables, and certificate setup. Make one change at a time, then repeat the same test. That makes it easier to identify whether the cause is a missing variable, a blocked destination, or a trust-store difference.