> 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-server/server-installation/ai-agents/configuration-reference.md).

# Configuration reference

Properties and environment variables for the SonarQube Server AI agents, on both the server side and the Agent Orchestrator. This page is for SonarQube Server 2026.5.

Configuration is split between two places. SonarQube Server needs to know where the components are, and the Agent Orchestrator needs its own database, storage, and connection settings.

To learn how to set SonarQube Server properties in general, see [Configuration methods](/sonarqube-server/server-installation/system-properties/configuration-methods.md).

## SonarQube Server properties <a href="#server-properties" id="server-properties"></a>

These tell SonarQube Server how to reach the components you deployed. Set each one to the address of the component in your deployment.

{% hint style="danger" %}
An environment variable overrides one of these properties only when the property is already present in `conf/sonar.properties`. None of the agentic properties are built-in system properties, which means setting only the environment variable has no effect: SonarQube Server starts as though the components were never deployed.

The configuration directory in a container image is read-only at container start. Mount a complete `conf/sonar.properties` that declares each property you need. Declaring a property with an empty value is enough to make it overridable from the environment.
{% endhint %}

| Property                                   | Environment variable                       | Description                                                                                                             |
| ------------------------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `sonar.hunteragent.orchestrator.url`       | `SONAR_HUNTERAGENT_ORCHESTRATOR_URL`       | The Agent Orchestrator address used for Hunter Agent jobs                                                               |
| `sonar.remediationagent.orchestrator.url`  | `SONAR_REMEDIATIONAGENT_ORCHESTRATOR_URL`  | The Agent Orchestrator address used for Remediation Agent jobs                                                          |
| `sonar.vortex.analysis.url`                | `SONAR_VORTEX_ANALYSIS_URL`                | The Vortex analysis address                                                                                             |
| `sonar.vortex.enabled`                     | `SONAR_VORTEX_ENABLED`                     | <p>Enables Vortex analysis, where your license includes it.</p><p><strong>Default value:</strong> <code>true</code></p> |
| `sonar.agents.health.checkIntervalSeconds` | `SONAR_AGENTS_HEALTH_CHECKINTERVALSECONDS` | How often SonarQube Server polls component health for the **System** page, in seconds                                   |

{% hint style="info" %}
On Kubernetes, the Helm chart sets these for you when you enable the components. Set them yourself in a Docker Compose deployment, or when the components run somewhere the chart doesn't know about.
{% endhint %}

### Hunter Agent scheduling <a href="#hunter-scheduling" id="hunter-scheduling"></a>

| Property                                             | Environment variable                                 | Description                                                                                                                   |
| ---------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `sonar.hunteragent.scheduler.enabled`                | `SONAR_HUNTERAGENT_SCHEDULER_ENABLED`                | <p>Dispatches scheduled Hunter Agent runs.</p><p><strong>Default value:</strong> <code>true</code></p>                        |
| `sonar.hunteragent.scheduler.threads`                | `SONAR_HUNTERAGENT_SCHEDULER_THREADS`                | <p>Threads used to dispatch scheduled runs.</p><p><strong>Default value:</strong> <code>2</code></p>                          |
| `sonar.hunteragent.scheduler.pollingIntervalSeconds` | `SONAR_HUNTERAGENT_SCHEDULER_POLLINGINTERVALSECONDS` | <p>How often the scheduler looks for runs that are due, in seconds.</p><p><strong>Default value:</strong> <code>10</code></p> |

Keep the defaults unless scheduled runs start too slowly. Raising the thread count increases the load the scheduler puts on your instance.

### Request signing <a href="#server-signing" id="server-signing"></a>

The components authenticate to each other by signing each request with a key derived from one shared secret, rather than with tokens. SonarQube Server needs the secret itself, to derive the keys it accepts, and the `agentic-shared` key, to sign its own calls to the Orchestrator.

| Property                                    | Environment variable                        | Description                                                                                                                                                     |
| ------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sonar.agentic.signing.secretFile`          | `SONAR_AGENTIC_SIGNING_SECRETFILE`          | Path to the file holding the shared secret. A file with the same name and a `.previous` suffix is also accepted, so you can rotate the secret without downtime. |
| `sonar.agentic.orchestrator.signingKeyPath` | `SONAR_AGENTIC_ORCHESTRATOR_SIGNINGKEYPATH` | Path to the derived `agentic-shared` key SonarQube Server uses to sign its own calls to the Orchestrator.                                                       |

{% hint style="danger" %}
The secret must be at least 32 characters. SonarQube Server disables signature verification on a secret shorter than 32 characters without reporting an error, which leaves the agentic endpoints unauthenticated.
{% endhint %}

On Kubernetes, the Helm chart derives the keys with a pre-install hook. With Docker Compose you derive them yourself, see [Deploying with Docker Compose](/sonarqube-server/server-installation/ai-agents/deploying-with-docker-compose.md).

### Vortex analysis context storage <a href="#server-context-storage" id="server-context-storage"></a>

SonarQube Server writes analysis context to the same location Vortex analysis reads it from, under its own property namespace. Point both at one location, see [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md).

| Property                                    | Description                                                                                                                                                 |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sonar.agentic.storage.type`                | The storage backend to use, either `S3` or `FILESYSTEM`.                                                                                                    |
| `sonar.agentic.storage.bucket`              | Bucket holding analysis context.                                                                                                                            |
| `sonar.agentic.storage.region`              | Storage region.                                                                                                                                             |
| `sonar.agentic.storage.endpoint`            | The storage endpoint. Leave empty to target Amazon S3.                                                                                                      |
| `sonar.agentic.storage.access-key`          | Access key. Leave empty to use the credentials already available to the host or pod.                                                                        |
| `sonar.agentic.storage.secret-key`          | Secret key.                                                                                                                                                 |
| `sonar.agentic.storage.path-style-access`   | <p>Uses path-style addressing. Most S3-compatible endpoints require it, and Amazon S3 does not.</p><p><strong>Default value:</strong> <code>true</code></p> |
| `sonar.agentic.storage.filesystem.base-dir` | Root directory to use when the backend is a shared filesystem rather than object storage.                                                                   |
| `sonar.agentic.storage.presign-ttl-seconds` | How long presigned URLs for analysis context stay valid, in seconds.                                                                                        |

{% hint style="info" %}
These are a separate namespace from the `sonar.agentic.orchestrator.storage.*` properties below, which cover agent job artifacts. The two can share one bucket, but each namespace has to be configured.
{% endhint %}

## Agent Orchestrator properties <a href="#orchestrator-properties" id="orchestrator-properties"></a>

Set these on the Agent Orchestrator container. On Kubernetes, the Helm chart maps its own values onto them, so set the chart values instead where one exists, see [Deploying with the Helm chart](/sonarqube-server/server-installation/ai-agents/customizing-helm-chart.md).

### Storage <a href="#orchestrator-storage" id="orchestrator-storage"></a>

| Property                                                 | Description                                                                                                                                                                                                                   |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sonar.agentic.orchestrator.storage.type`                | <p>The storage backend to use.</p><p><strong>Default value:</strong> <code>S3</code></p>                                                                                                                                      |
| `sonar.agentic.orchestrator.storage.bucket`              | <p>Bucket holding job artifacts.</p><p><strong>Default value:</strong> <code>agentic-jobs</code></p>                                                                                                                          |
| `sonar.agentic.orchestrator.storage.endpoint`            | The storage endpoint. Leave empty to target Amazon S3.                                                                                                                                                                        |
| `sonar.agentic.orchestrator.storage.region`              | <p>Storage region.</p><p><strong>Default value:</strong> <code>us-east-1</code></p>                                                                                                                                           |
| `sonar.agentic.orchestrator.storage.access-key`          | Access key. Leave empty to use the credentials already available to the host or pod.                                                                                                                                          |
| `sonar.agentic.orchestrator.storage.secret-key`          | Secret key.                                                                                                                                                                                                                   |
| `sonar.agentic.orchestrator.storage.path-style-access`   | <p>Uses path-style addressing. Most S3-compatible endpoints require it, and Amazon S3 does not.</p><p><strong>Default value:</strong> <code>true</code></p>                                                                   |
| `sonar.agentic.orchestrator.storage.key-prefix`          | Prefix applied to all keys, so several instances can share one bucket.                                                                                                                                                        |
| `sonar.agentic.orchestrator.storage.filesystem.base-dir` | Root directory to use when the backend is a shared filesystem rather than object storage.                                                                                                                                     |
| `sonar.agentic.orchestrator.storage.presign-ttl-seconds` | How long a presigned URL stays valid once handed to a runtime, in seconds. Keep it above the longest job timeout in [#dispatch](#dispatch "mention"): the URL is issued when a job is dispatched and isn't refreshed mid-run. |

### Job dispatch <a href="#dispatch" id="dispatch"></a>

| Property                                                          | Description                                                                                                                                                               |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sonar.agentic.orchestrator.runtime.hunter-push-url`              | The Hunter Agent runtime address. Set it for the Hunter Agent to receive jobs.                                                                                            |
| `sonar.agentic.orchestrator.runtime.remediation-push-url`         | The Remediation Agent runtime address. Set it for the Remediation Agent to receive jobs.                                                                                  |
| `sonar.agentic.orchestrator.watcher.hunter-timeout-seconds`       | <p>How long a Hunter Agent job may run before the Orchestrator stops it and marks it failed, in seconds.</p><p><strong>Default value:</strong> <code>44400</code></p>     |
| `sonar.agentic.orchestrator.watcher.remediation-timeout-seconds`  | <p>How long a Remediation Agent job may run before the Orchestrator stops it and marks it failed, in seconds.</p><p><strong>Default value:</strong> <code>3600</code></p> |
| `sonar.agentic.orchestrator.watcher.timeout-seconds`              | Fallback timeout used when the per-type value above isn't set. No standalone default.                                                                                     |
| `sonar.agentic.orchestrator.tasks.worker-threads`                 | <p>How many jobs can run at once.</p><p><strong>Default value:</strong> <code>10</code></p>                                                                               |
| `sonar.agentic.orchestrator.runtime.hunter-signing-key-path`      | Path to the key the Orchestrator uses to sign job pushes to the Hunter Agent runtime.                                                                                     |
| `sonar.agentic.orchestrator.runtime.remediation-signing-key-path` | Path to the key the Orchestrator uses to sign job pushes to the Remediation Agent runtime.                                                                                |

Raising the job concurrency also raises the peak load on your storage, your LLM provider, and the hosts running the sandboxes. Size those first, see [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md).

### Access to SonarQube Server <a href="#orchestrator-sonarqube" id="orchestrator-sonarqube"></a>

| Property                                                | Description                                                                                              |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `sonar.agentic.orchestrator.sonarqube.url`              | SonarQube Server address. Required: the Orchestrator reads project data and publishes results through it |
| `sonar.agentic.orchestrator.sonarqube.signing-key-path` | Path to the signing key the Orchestrator uses to sign requests to SonarQube Server                       |

### Request signing and inbound verification <a href="#orchestrator-signing" id="orchestrator-signing"></a>

The Orchestrator verifies each inbound call with the key derived for that caller. See [#server-signing](#server-signing "mention") for how the keys are derived.

| Property                                                               | Description                                                                         |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `sonar.agentic.orchestrator.inbound.verification-key-path`             | Path to the `agentic-shared` key used to verify inbound calls from SonarQube Server |
| `sonar.agentic.orchestrator.inbound.hunter-verification-key-path`      | Path to the key used to verify inbound calls from the Hunter Agent runtime          |
| `sonar.agentic.orchestrator.inbound.remediation-verification-key-path` | Path to the key used to verify inbound calls from the Remediation Agent runtime     |
| `sonar.agentic.orchestrator.job-capability.signing-key-path`           | Path to the key the Orchestrator uses to sign job capability tokens                 |

### Retention <a href="#retention" id="retention"></a>

| Property                                    | Description                                                                                                                                          |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sonar.hunteragent.deleteOlderThan`         | <p>Days to keep Hunter Agent job artifacts. Set to <code>0</code> or less to disable.</p><p><strong>Default value:</strong> <code>30</code></p>      |
| `sonar.remediationagent.deleteOlderThan`    | <p>Days to keep Remediation Agent job artifacts. Set to <code>0</code> or less to disable.</p><p><strong>Default value:</strong> <code>30</code></p> |
| `sonar.agentic.orchestrator.purge.interval` | <p>How often the Orchestrator sweeps shared storage for expired artifacts.</p><p><strong>Default value:</strong> <code>24h</code></p>                |

Set the first two in **General Settings** > **Housekeeping** > **Agentic**, not as server properties.

### DevOps platform <a href="#devops-platform" id="devops-platform"></a>

Set these only if your DevOps platform is self-managed and its API isn't at the public address.

| Property                                                     | Description                                                                                                    |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `sonar.agentic.orchestrator.remediation.github.api-base-url` | <p>GitHub API base address.</p><p><strong>Default value:</strong> <code><https://api.github.com></code></p>    |
| `sonar.agentic.orchestrator.remediation.gitlab.api-base-url` | <p>GitLab API base address.</p><p><strong>Default value:</strong> <code><https://gitlab.com/api/v4></code></p> |

For a self-managed GitLab instance, the address on the project binding takes precedence over this value.

{% hint style="info" %}
Your DevOps platform credentials stay in SonarQube Server. The Orchestrator requests a short-lived credential from SonarQube Server before each Git operation, so you configure repository access once, where you already manage it. See [Remediation Agent](/sonarqube-server/instance-administration/ai-features/remediation-agent.md#devops-platform-permissions).
{% endhint %}

### Outbound proxy <a href="#proxy" id="proxy"></a>

| Property                                         | Description                                                    |
| ------------------------------------------------ | -------------------------------------------------------------- |
| `sonar.agentic.orchestrator.http.proxy-user`     | Proxy user. Leave empty when the proxy needs no authentication |
| `sonar.agentic.orchestrator.http.proxy-password` | Proxy password                                                 |

Set the proxy host and port through the JVM system properties, the same way you do for SonarQube Server. Set the credentials here.

## LLM provider configuration <a href="#llm-provider" id="llm-provider"></a>

Register your LLM providers once in SonarQube Server, under **Administration** > **Configuration** > **AI Capabilities** > **LLM Providers**. The Orchestrator passes the right credentials to each job when it starts, so you configure the provider in one place rather than on each deployed component.

## Next step <a href="#next-step" id="next-step"></a>

This page is a reference, not a step in the deployment itself. For the full sequence, see the [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#roadmap).

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Deploying with the Helm chart](/sonarqube-server/server-installation/ai-agents/customizing-helm-chart.md)
* [Deploying with Docker Compose](/sonarqube-server/server-installation/ai-agents/deploying-with-docker-compose.md)
* [List of properties common to all editions](/sonarqube-server/server-installation/system-properties/common-properties.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-server/server-installation/ai-agents/configuration-reference.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.