Skip to main content
Version: Next

Running Backstage behind a Corporate Proxy

Sometimes you have to run Backstage with no direct access to the public internet, except through a corporate proxy. The backend is most likely where you'll run into proxy issues, as it isn't helped by your browser or OS proxy settings.

Using Node.js built-in proxy support​

Starting with Node.js 22.21.0 and 24.5.0, Node.js has built-in support for proxy environment variables. When enabled, native fetch(), node:http, and node:https all respect the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables without any additional packages. See the Node.js enterprise network configuration docs for full details.

To enable the built-in proxy support, set the NODE_USE_ENV_PROXY environment variable along with your proxy settings:

export HTTP_PROXY=http://username:password@proxy.example.net:8888
export HTTPS_PROXY=http://username:password@proxy.example.net:8888
export NO_PROXY=localhost,127.0.0.1,.internal.company.com
export NODE_USE_ENV_PROXY=1
yarn start

Compatibility with third-party fetch libraries​

Per ADR014, Backstage backend code should use native fetch(), which works with Node.js's proxy out of the box. Some core packages and many community plugins still use node-fetch (see ADR013) or cross-fetch (for isomorphic packages). Both libraries delegate to node:http/node:https internally and do not set a custom HTTP agent by default, which means Node.js's proxy works for them as well.

The exception is code that explicitly passes a custom agent to its fetch calls (e.g. the Kubernetes plugins, which use new https.Agent(...) for TLS client certificates). In those cases, the custom agent takes precedence and the built-in proxy is bypassed. This is generally the desired behavior, since those agents are configured for direct connections to specific endpoints like cluster APIs.

Legacy approach​

If you are on a Node.js version older than 22.21.0, you can use third-party packages to add proxy support. See the legacy proxy setup guide for instructions using undici, global-agent, and proxy-agent.