> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md).

# Advanced network configuration

Configure proxy servers, custom CA certificates, TLS client certificates, and MCP container networking for the SonarQube CLI.

The SonarQube CLI communicates with your SonarQube server and downloads auxiliary components over HTTPS. In enterprise environments that route traffic through a proxy, use a custom certificate authority (CA), or require mutual TLS (mTLS), configure the CLI's network behavior with environment variables or stored `sonar config` keys.

The same resolved settings apply when the CLI launches the [SonarQube MCP Server](https://github.com/SonarSource/sonarqube-mcp-server) for agent integrations or `sonar run mcp`.

To reach a SonarQube Server or SonarQube Community Build on the same machine from that container, store the `mcp.container.*` keys. See [Reach a SonarQube Server on the same machine](#reach-a-sonarqube-server-on-the-same-machine).

> **Note:** Proxy and certificate configuration is not fully supported by secrets detection, Software Composition Analysis, and [Vortex context](https://docs.sonarsource.com/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) features inside the CLI.

## Configuration sources

The CLI checks sources in this order:

1. The matching `SONAR_*` environment variable. See [Environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity).
2. The matching stored `sonar config` key. Store it with [`sonar config set`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set), print one key with [`sonar config get`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-get), print every key with [`sonar config list`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-list), and remove it with [`sonar config unset`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-unset).
3. A generic environment variable, for proxy and custom CA settings only.

The custom CA certificate and each client certificate setting use the first source that has a value. Generic proxy names also match `https_proxy`, `http_proxy`, and `no_proxy`.

| Setting                     | `SONAR_*` variable            | Stored key                     | Generic variable      |
| --------------------------- | ----------------------------- | ------------------------------ | --------------------- |
| HTTPS proxy                 | `SONAR_HTTPS_PROXY_URL`       | `network.proxy.https`          | `HTTPS_PROXY`         |
| HTTP proxy                  | `SONAR_HTTP_PROXY_URL`        | `network.proxy.http`           | `HTTP_PROXY`          |
| Hosts that bypass the proxy | `SONAR_NO_PROXY`              | `network.proxy.noProxy`        | `NO_PROXY`            |
| Custom CA certificate       | `SONAR_CA_CERT`               | `network.tls.caCert`           | `NODE_EXTRA_CA_CERTS` |
| Client certificate          | `SONAR_TLS_CLIENT_CERT`       | `network.tls.clientCert`       | None                  |
| Client key                  | `SONAR_TLS_CLIENT_KEY_FILE`   | `network.tls.clientKey`        | None                  |
| Client passphrase           | `SONAR_TLS_CLIENT_PASSPHRASE` | `network.tls.clientPassphrase` | None                  |

The HTTPS proxy URL, HTTP proxy URL, and no-proxy list are one group. The highest-priority source that sets either proxy URL supplies all three. A no-proxy value alone does not select that source.

Client certificate path, key file, and passphrase are separate. A `SONAR_*` variable overrides only that setting's stored key. Client certificates have no generic fallback.

Sensitive stored keys (`network.proxy.https`, `network.proxy.http`, and `network.tls.clientPassphrase`) live in the OS keychain. If the CLI cannot read a stored key, it treats that key as unset. See [State and storage](https://docs.sonarsource.com/sonarqube-cli/administration/state-and-storage.md).

Run `sonar system status` to see which source the CLI resolved.

## Proxy configuration

Set `SONAR_HTTPS_PROXY_URL`, `SONAR_HTTP_PROXY_URL`, and `SONAR_NO_PROXY` as described in [Environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity). The matching stored keys are `network.proxy.https`, `network.proxy.http`, and `network.proxy.noProxy`.

### Proxy URL format

```
http://proxy.corp.com:3128
```

For proxies that require basic authentication, include credentials in the URL:

```
http://username:password@proxy.corp.com:3128
```

> **Warning:** Do not set credentials inline in terminal commands; they'll be saved to shell history. To store a proxy URL that includes a password, run `sonar config set network.proxy.https` or `sonar config set network.proxy.http` and type the URL at the masked prompt. The value is saved in the OS keychain. You can also add the URL to your shell profile (for example, `~/.bashrc` or `~/.zshrc`), or use your CI/CD platform's secrets management.

### Bypassing the proxy for specific hosts

Set `SONAR_NO_PROXY` to a comma-separated list of hosts that the CLI should reach directly, without going through the proxy:

```bash
export SONAR_NO_PROXY="sonar.internal.corp.com,localhost,127.0.0.1,::1"
```

Supported entry formats:

| Format                    | Matches                                                    |
| ------------------------- | ---------------------------------------------------------- |
| `sonar.internal.corp.com` | Exact hostname only                                        |
| `corp.com`                | The domain itself and all its subdomains                   |
| `*.corp.com`              | Subdomains only; does not match the root domain `corp.com` |
| `sonar.corp.com:9000`     | That hostname, but only when connecting on port 9000       |
| `::1`                     | Exact IPv6 address, unbracketed                            |
| `[::1]`                   | Exact IPv6 address, bracketed                              |
| `[::1]:9000`              | That IPv6 address, but only when connecting on port 9000   |
| `*`                       | All hosts; bypasses the proxy entirely                     |

For an IPv6 address with a port, use `[IPv6]:port`. The CLI cannot treat an unbracketed value such as `::1:9000` as a host-and-port entry.

## Workarounds for unsupported proxy types

The CLI supports only basic-authentication proxies. If your environment uses a more complex proxy protocol, use a local proxy adapter to bridge the gap.

### NTLM and Kerberos proxies

Corporate proxies that require Windows-domain authentication (NTLM or Kerberos) cannot be configured directly. Tools like [Cntlm](http://cntlm.sourceforge.net/) and [Px Proxy](https://github.com/genotrance/px) authenticate with the corporate proxy using your domain credentials and expose a simple unauthenticated endpoint on localhost that the CLI can use.

1. Install and configure Cntlm or Px Proxy with your domain credentials.
2. Start the local proxy. By default it listens on `http://localhost:3128`.
3. Point the CLI to the local proxy:

```bash
export SONAR_HTTPS_PROXY_URL="http://localhost:3128"
```

Your domain credentials stay in the local proxy's configuration file and are never passed to the CLI.

### PAC file environments

The CLI does not read PAC (Proxy Auto-Config) files. If your organization distributes proxy settings via a PAC file, find the proxy URL that applies to your SonarQube server hostname (or ask your network team) and set it manually:

```bash
export SONAR_HTTPS_PROXY_URL="http://proxy.corp.com:3128"
```

In many environments, a PAC file evaluates to a single proxy for most corporate traffic, which reduces to one URL to copy.

## Custom CA certificates

Use this when your SonarQube server's certificate is signed by an internal CA, or when an SSL-inspecting proxy (such as Zscaler, Bluecoat, or Netskope) re-encrypts HTTPS traffic with a corporate certificate.

Set `SONAR_CA_CERT` as described in [Environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity). The matching stored key is `network.tls.caCert`.

> **Warning:** Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0` as a workaround for certificate errors. It bypasses `NODE_EXTRA_CA_CERTS` but not `SONAR_CA_CERT`. As a result, it will not resolve issues with this CLI, and it disables certificate validation. Use `SONAR_CA_CERT` to trust a specific CA instead.

### Certificate format

The certificate must be in PEM format: a Base64-encoded text file that begins with `-----BEGIN CERTIFICATE-----`. If your certificate is in a different format, convert it using `openssl` before setting the environment variable.

#### DER (.der, .crt)

```bash
openssl x509 -inform DER -in corp-ca.der -out corp-ca.pem
```

#### PKCS#12 / PFX

```bash
openssl pkcs12 -in bundle.pfx -nokeys -cacerts -out corp-ca.pem
```

#### P7B / PKCS#7

```bash
openssl pkcs7 -print_certs -in corp-ca.p7b -out corp-ca.pem
```

### Export from the system certificate store

#### macOS

1. Open **Keychain Access** and find the CA certificate.
2. Right-click the certificate and select **Export**.
3. Choose **Privacy Enhanced Mail (.pem)** as the format and save the file.

#### Windows

1. Open **certmgr.msc**.
2. Expand **Trusted Root Certification Authorities > Certificates**.
3. Right-click the CA certificate and select **All Tasks > Export**.
4. On the **Export File Format** page, choose **Base-64 encoded X.509 (.CER)**.
5. Complete the wizard and choose a file name when prompted.

The exported file is in PEM format and can be used directly with `SONAR_CA_CERT`.

## TLS client certificates

Use this when your SonarQube server requires a client certificate for HTTPS connections (mutual TLS).

Set `SONAR_TLS_CLIENT_CERT`, and when needed `SONAR_TLS_CLIENT_KEY_FILE` and `SONAR_TLS_CLIENT_PASSPHRASE`, as described in [Environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity). The matching stored keys are `network.tls.clientCert`, `network.tls.clientKey`, and `network.tls.clientPassphrase`.

### Required variables

| Variable                      | Description                                                                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SONAR_TLS_CLIENT_CERT`       | Path to your client certificate PEM file, or a PKCS#12 bundle (`.p12` or `.pfx`)                                                                                    |
| `SONAR_TLS_CLIENT_KEY_FILE`   | Path to the private key PEM file that matches the certificate. Required for a PEM certificate unless `network.tls.clientKey` is set. Not used for a PKCS#12 bundle. |
| `SONAR_TLS_CLIENT_PASSPHRASE` | Optional passphrase when the private key (PKCS#8) or PKCS#12 bundle is encrypted                                                                                    |

When the client certificate is a PEM file, a key file is required (`SONAR_TLS_CLIENT_KEY_FILE` or `network.tls.clientKey`). If a required file is missing or cannot be read, the CLI records a configuration error and reports it in `sonar system status`.

### Certificate and key format

Configure a client certificate in either of these ways:

**PEM files (separate certificate and key)**

Both files must be in PEM format. The certificate file begins with `-----BEGIN CERTIFICATE-----`. The key file begins with one of these lines:

* `-----BEGIN PRIVATE KEY-----` or `-----BEGIN RSA PRIVATE KEY-----` for an unencrypted key
* `-----BEGIN ENCRYPTED PRIVATE KEY-----` for an encrypted key (PKCS#8). Set `SONAR_TLS_CLIENT_PASSPHRASE` to its passphrase, or store it as `network.tls.clientPassphrase`.

Encrypted keys in the legacy OpenSSL format, which contain `Proc-Type: 4,ENCRYPTED` and `DEK-Info` header lines, are not supported. Convert such a key to the supported encrypted format with OpenSSL:

```bash
openssl pkcs8 -topk8 -in legacy-key.pem -out client-key.pem
```

OpenSSL prompts for the current passphrase, then for the passphrase that protects the new file. You can reuse the same passphrase.

**PKCS#12 bundle (`.p12` or `.pfx`)**

Set the certificate path to the bundle (`SONAR_TLS_CLIENT_CERT` or `network.tls.clientCert`). The CLI extracts the certificate and private key from the file, so you do not set a key file. When the bundle is password-protected, set the passphrase (`SONAR_TLS_CLIENT_PASSPHRASE` or `network.tls.clientPassphrase`).

Combine a client certificate with a custom CA certificate (`SONAR_CA_CERT`) when your server uses an internal CA and also requires a client certificate.

### Examples

PEM certificate and key:

```bash
export SONAR_TLS_CLIENT_CERT=/etc/ssl/client-cert.pem
export SONAR_TLS_CLIENT_KEY_FILE=/etc/ssl/client-key.pem
export SONAR_TLS_CLIENT_PASSPHRASE=my-secret   # only when the key is encrypted
sonar list issues -p <YourProjectKey>
```

PKCS#12 bundle:

```bash
export SONAR_TLS_CLIENT_CERT=/etc/ssl/client-cert.p12
export SONAR_TLS_CLIENT_PASSPHRASE=my-secret   # only when the bundle is encrypted
sonar list issues -p <YourProjectKey>
```

> **Warning:** Do not set `SONAR_TLS_CLIENT_PASSPHRASE` to its value directly in the terminal; it'll be saved to shell history. To store the passphrase, run `sonar config set network.tls.clientPassphrase` and type it at the masked prompt. You can also add it to your shell profile (for example, `~/.bashrc` or `~/.zshrc`), or use your CI/CD platform's secrets management.

Run `sonar system status` to verify the CLI resolved your certificate path (and key path for PEM files). When configuration is invalid, the **Network** section shows the error and **Recommendations** suggests how to fix it.

## SonarQube MCP Server

When the CLI starts the SonarQube MCP Server (`sonar run mcp` or through `sonar integrate` for supported agents), it passes your resolved network configuration into the MCP container:

| Setting                                                                   | How the CLI applies it                                                                                        |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Proxy (`SONAR_HTTPS_PROXY_URL`, `SONAR_HTTP_PROXY_URL`, `SONAR_NO_PROXY`) | Translated to Java proxy system properties in `JAVA_OPTS`.                                                    |
| Custom CA (`SONAR_CA_CERT`)                                               | Certificate file mounted read-only into the container; the MCP image updates the system CA bundle at startup. |
| Client certificate (`SONAR_TLS_CLIENT_*`)                                 | PKCS#12 keystore mounted for mutual TLS.                                                                      |

When `SONAR_TLS_CLIENT_CERT` points to PEM files, the CLI converts them to a temporary PKCS#12 file under `~/.sonar/sonarqube-cli/cli-tmp/` and removes it when the MCP server process exits. PKCS#12 bundles (`.p12` or `.pfx`) are mounted directly.

Set the `SONAR_*` network variables in the environment of your AI agent or terminal session before the MCP server starts. Stored `sonar config` keys are included in that same resolved configuration. On Windows, the CLI translates certificate paths when it runs the container through WSL. See [Environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#mcp-container-runtime-on-windows).

## Reach a SonarQube Server on the same machine <a href="#reach-a-sonarqube-server-on-the-same-machine" id="reach-a-sonarqube-server-on-the-same-machine"></a>

Store a container network, host mapping, or container-only server URL when the MCP container cannot use the saved SonarQube Server or SonarQube Community Build URL. The usual case is a server on this machine whose saved URL uses a loopback host. SonarQube Cloud ignores these keys. Your other CLI commands keep the saved server URL.

Store the keys with [`sonar config set`](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set). They apply the next time `sonar run mcp` starts, including when an agent integration starts the server. Leave the MCP configuration that `sonar integrate` writes unchanged. On Windows, choosing Docker, Podman, nerdctl, or WSL is separate. See [Environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md#mcp-container-runtime-on-windows).

> **Note:** With none of these keys set, the container starts without `--network`, `--add-host`, or a rewritten server URL. Automatic routing stays off until you set `mcp.container.autoNetwork` to `true`.

| Key                         | What it stores                                                                  |
| --------------------------- | ------------------------------------------------------------------------------- |
| `mcp.container.network`     | Network name passed as `--network` to Docker, Podman, or nerdctl.               |
| `mcp.container.addHost`     | Host mapping in `name:address` form, passed as `--add-host`.                    |
| `mcp.container.serverUrl`   | HTTP or HTTPS URL used only inside the container, with no username or password. |
| `mcp.container.autoNetwork` | `true` or `false`. Only a stored `true` turns automatic routing on.             |

If you set `mcp.container.network`, `mcp.container.addHost`, or `mcp.container.serverUrl`, the CLI uses those stored values and does not apply automatic routing. That stays true when `mcp.container.autoNetwork` is also `true`.

Automatic routing runs only when `mcp.container.autoNetwork` is `true`, the saved server URL is a loopback host, a container runtime is available, and none of the other three keys is set:

* On Linux, the container uses `--network host` and keeps the saved URL. This includes Docker, Podman, and nerdctl.
* On macOS and Windows, Docker replaces the host in the container URL with `host.docker.internal`. Podman uses `host.containers.internal`. A Windows runtime reached through WSL follows this same rule.
* On macOS and Windows, nerdctl keeps the saved URL. Set `mcp.container.serverUrl` and `mcp.container.network` to values the runtime can reach.

The CLI treats a host as loopback when it is `localhost`, a name ending in `.localhost`, an IPv4 address that starts with `127.`, `0.0.0.0`, or `[::1]`.

Host networking and host mappings depend on your container runtime and platform. The CLI passes the stored values through and does not check that the runtime accepts them.

`sonar config set` accepts any non-empty string for `mcp.container.serverUrl`. `sonar run mcp` checks the value when it starts. A value that cannot be parsed as a URL, such as `http://`, fails with exit code `2` and the message `mcp.container.serverUrl must be an HTTP or HTTPS URL.` A URL with another scheme (for example `ftp://`), no host, or a username or password fails with exit code `2` and the message `mcp.container.serverUrl must be an HTTP or HTTPS URL without credentials.`

### Store a container route

Turn on automatic routing:

```bash
sonar config set mcp.container.autoNetwork true
```

Point the container at a server on a user-defined network:

```bash
sonar config set mcp.container.network sonar-net
sonar config set mcp.container.serverUrl http://sonarqube:9000
```

Add a host mapping:

```bash
sonar config set mcp.container.addHost sonarqube:host-gateway
```

### Read container networking guidance

`sonar integrate` for an agent prints guidance on stderr when the saved SonarQube Server or SonarQube Community Build URL is a loopback host, unless `mcp.container.serverUrl` is set to a URL that is not loopback. The text starts with `MCP container networking:`.

`sonar system status` adds that same text under **Recommendations**, and to the JSON `recommendations` array, when saved credentials are present and at least one integration shows MCP Server status **configured**. The guidance does not by itself mark the check unhealthy.

The text depends on what you stored:

* With no container keys set, it tells you to set `mcp.container.autoNetwork` to `true`, or to set `mcp.container.serverUrl` and `mcp.container.network` yourself.
* With automatic routing on and no explicit network, host mapping, or container URL, it describes Linux host networking, the Docker and Podman host aliases, and the nerdctl case on macOS and Windows.
* With `mcp.container.network` set to `host` and no container URL, it tells you to verify that the server is reachable from the container runtime.
* With any other explicit network, host mapping, or loopback container URL, it tells you to set `mcp.container.serverUrl` to an address the container can reach.

If the container exits with a code other than `0`, `130`, or `143`, and the URL passed into the container is still a loopback URL, `sonar run mcp` prints the guidance on stderr. The line starts with `[sonarqube-cli] The MCP container exited with an error.` MCP messages on stdout stay unchanged. Exit code `130` is an interrupt, and `143` is termination. A host-alias rewrite, or an `mcp.container.serverUrl` that is not loopback, means this stderr line is not printed.

## Troubleshooting TLS errors

### Certificate not trusted

If the CLI reports an error like "unable to get local issuer certificate" or "self-signed certificate in certificate chain", the server's certificate is signed by a CA that's not in your system trust store. This is common with internal CAs and SSL-inspecting proxies such as Zscaler or Bluecoat.

Set `SONAR_CA_CERT` to the path of a PEM file containing the CA certificate. See [Custom CA certificates](#custom-ca-certificates).

### Java TLS exceptions

If you see `SSLHandshakeException: PKIX path building failed` or similar Java TLS errors, run `sonar system status` to identify which component is failing. The SonarQube CLI manages underlying Java binaries (such as secrets detection and SCA) that can surface these errors. If none of those components is failing but you're still seeing Java TLS errors, you may be running `sonar-scanner` (SonarScanner CLI) rather than `sonar` (SonarQube CLI). See the SonarScanner CLI docs for [SonarQube Server](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/scanners/sonarscanner/) or [SonarQube Cloud](https://docs.sonarsource.com/sonarqube-cloud/analyzing-source-code/scanners/sonarscanner-cli.md) for how to configure its truststore.

### Skipping SSL verification

The SonarQube CLI does not have an option to skip certificate validation. Use `SONAR_CA_CERT` to trust a specific CA instead.

## Related pages

* [Check system status](https://docs.sonarsource.com/sonarqube-cli/administration/system-status.md)
* [Environment variables](https://docs.sonarsource.com/sonarqube-cli/using-sonarqube-cli/environment-variables.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
